Skip to content

Getting Started

Jump to bottom
Bill Moore edited this page Oct 9, 2024 · 19 revisions

This page describes the steps to get up and running with your first Bathtub simulation.

  1. Download and Install Bathtub
  2. Set up your Environment
  3. "Hello, World!"

Download and Install Bathtub

View the available releases at https://github.com/williaml33moore/bathtub/releases. Download the latest tarball (tar.gz) from the Assets section to a suitable download directory. You can use a web browser to download the file, or a command line tool like curl.

curl --location --remote-name https://github.com/williaml33moore/bathtub/archive/refs/tags/vX.Y.Z.tar.gz

Curl requires the --location option because GitHub stores the files at a different location than the URL.

Unpack the downloaded file with the appropriate tool.

tar xzvf vX.Y.Z.tar.gz

The resulting directory bathtub-X.Y.Z is your Bathtub VIP directory. Move it to its final installation location, which could be a shared directory that your entire team can access, or a personal workspace for your own use.

mkdir -p /path/to/installation/dir
mv bathtub-X.Y.Z /path/to/installation/dir
ls /path/to/installation/dir/bathtub-X.Y.Z

It's a common practice to create symbolic links that point to the latest installed release so users' environments don't need to change each time a new release is installed.

ln -s /path/to/installation/dir/bathtub-X.Y.Z /path/to/installation/dir/bathtub-latest
ln -s /path/to/installation/dir/bathtub-latest /path/to/installation/dir/bathtub

See the [Complete Setup Guide] for alternative methods of downloading the release, and for instructions on cloning the entire repository.

Set up Your Environment

Define an environment variable called BATHTUB_VIP_DIR and set it to the absolute path to your bathtub installation directory.

# csh/tcsh
setenv BATHTUB_VIP_DIR /path/to/installation/dir/bathtub

# or

# sh/bash
export BATHTUB_VIP_DIR=/path/to/installation/dir/bathtub

See the [Complete Setup Guide] for alternative methods of setting up the environment, such as running a Bathtub setup shell script or SystemVerilog script.

"Hello, World!"

Run a simple simulation to ensure that Bathtub is functional.

Your First Bathtub Testbench

Create the following two plain text files, hello_world.sv and hello_world.feature, in a suitable workspace directory. You can copy the files from your Bathtub installation:

// hello_world.sv

`timescale 1s/1ms
`include "uvm_macros.svh"
`include "bathtub_macros.sv"

program hello_world();

    import uvm_pkg::*;
    
    class echo_step extends uvm_sequence implements bathtub_pkg::step_definition_interface;
        `Given(".*")

        `uvm_object_utils(echo_step)

        function new (string name="echo_step");
            super.new(name);
        endfunction : new

        virtual task body();
            get_step_attributes().print_attributes(UVM_NONE);
        endtask : body
    endclass : echo_step


    class bathtub_test extends uvm_test;
        bathtub_pkg::bathtub bathtub;

        `uvm_component_utils(bathtub_test)

        function new(string name, uvm_component parent);
            super.new(name, parent);
            bathtub = new();
        endfunction : new
        
        virtual task run_phase(uvm_phase phase);
            bathtub.run_test(phase);
        endtask : run_phase
    endclass : bathtub_test
    
    initial run_test("bathtub_test");
    
endprogram : hello_world
# hello_world.feature
Feature: Hello, World!
    Scenario: Print a simple message
        Given a Bathtub simulation
        When I print 'Hello, World!'
        Then the test should pass

Indentation in the feature file is customary, but not required or significant. Leading and trailing white space is ignored.

Run the Simulation

You need a SystemVerilog simulator which can run UVM. The most prevalent options are:

Change to your workspace directory, where you created the two files hello_world.sv and hello_world.feature. Use the one of the following commands for your preferred simulator to run Bathtub with UVM. You may customize the command for your system, environment, and preferences. (The VCS command line is untested; it's a guess.)

# Xcelium
xrun -uvm -f $BATHTUB_VIP_DIR/src/bathtub_vip.f hello_world.sv +bathtub_features=hello_world.feature

# Questa
qrun -uvm -f $BATHTUB_VIP_DIR/src/bathtub_vip.f hello_world.sv +bathtub_features=hello_world.feature

# VCS
vcs -R -full64 +incdir+$UVM_HOME/src $UVM_HOME/src/uvm.sv $UVM_HOME/src/dpi/uvm_dpi.cc -CFLAGS -DVCS -sverilog -f $BATHTUB_VIP_DIR/src/bathtub_vip.f hello_world.sv +bathtub_features=hello_world.feature

The simulation should compile and run with no errors, and the log file should contain deconstructed representations of the steps in your feature file. An excerpt from UVM 1.2 or later:

UVM_INFO bathtub/src/bathtub_pkg/gherkin_document_runner/gherkin_document_runner.svh(597) @ 0: bathtub [runner] When I print 'Hello, World!'
UVM_INFO bathtub/src/bathtub_pkg/gherkin_document_runner/gherkin_document_runner.svh(181) @ 0: bathtub [bathtub_pkg::gherkin_document_runner.start_step] When I print 'Hello, World!'
UVM_INFO bathtub/src/bathtub_pkg/step_nurture.svh(65) @ 0: reporter [step_attributes] 
 +--------------------------------------------------------------------------------------
 +Name               Type                                  Size  Value                  
 +--------------------------------------------------------------------------------------
 +element_container  uvm_report_message_element_container  -     @2287                  
 +  runtime_keyword  string                                4     When                   
 +  text             string                                23    I print 'Hello, World!'
 +  argument         object                                -     <null>                 
 +--------------------------------------------------------------------------------------
 +
UVM_INFO bathtub/src/bathtub_pkg/step_nature.svh(77) @ 0: reporter [static_step_object] 
 +------------------------------------------------------------------------
 +Name               Type                                  Size  Value    
 +------------------------------------------------------------------------
 +element_container  uvm_report_message_element_container  -     @2255    
 +  keyword          string                                5     Given    
 +  expression       string                                2     .*       
 +  regexp           string                                6     /^.*$/   
 +  step_obj_name    string                                9     echo_step
 +------------------------------------------------------------------------
 +

The log file from UVM 1.1 or earlier would look like this:

# UVM_INFO bathtub/src/bathtub_pkg/gherkin_document_runner/gherkin_document_runner.svh(597) @ 0: bathtub [runner] When I print 'Hello, World!'
# UVM_INFO bathtub/src/bathtub_pkg/gherkin_document_runner/gherkin_document_runner.svh(181) @ 0: bathtub [bathtub_pkg.gherkin_document_runner.start_step] When I print 'Hello, World!'
# UVM_INFO bathtub/src/bathtub_pkg/step_nurture.svh(65) @ 0: reporter [step_attributes] 
# UVM_INFO bathtub/src/bathtub_pkg/step_nurture.svh(66) @ 0: reporter [step_attributes] runtime_keyword:When
# UVM_INFO bathtub/src/bathtub_pkg/step_nurture.svh(67) @ 0: reporter [step_attributes] text:I print 'Hello, World!'
# UVM_INFO bathtub/src/bathtub_pkg/step_nurture.svh(68) @ 0: reporter [step_attributes] argument:null
# UVM_INFO bathtub/src/bathtub_pkg/step_nature.svh(77) @ 0: reporter [static_step_object] 
# UVM_INFO bathtub/src/bathtub_pkg/step_nature.svh(78) @ 0: reporter [static_step_object] keyword:Given
# UVM_INFO bathtub/src/bathtub_pkg/step_nature.svh(79) @ 0: reporter [static_step_object] expression:.*
# UVM_INFO bathtub/src/bathtub_pkg/step_nature.svh(80) @ 0: reporter [static_step_object] regexp:/^.*$/
# UVM_INFO bathtub/src/bathtub_pkg/step_nature.svh(81) @ 0: reporter [static_step_object] step_obj_name:echo_step

Congratulations, Bathtub is installed correctly and is working!

Bathtub Options File

You ran your simulation with the Bathtub options file bathtub_vip.f. It specifies search directories for included files and paths to the Bathtub source code packages. The options file is available in a few different ways.

There are two equivalent versions of the options file in the installation directory:

File Description
$BATHTUB_VIP_DIR/src/bathtub_vip.f Specifies absolute paths by means of the $BATHTUB_VIP_DIR environment variable. This file is suitable for use with the simulators' -f <file> command line option (lowercase -f).
$BATHTUB_VIP_DIR/src/bathtub_vip_rel.f Specifies relative paths, relative to bathtub_vip_rel.f itself. This file is suitable for use with the simulators' -F <file> command line option (uppercase -F).

The motivation behind having two versions is that the absolute path version requires that $BATHTUB_VIP_DIR be defined, whereas the relative path version does not, and works fine without it. There may be situations where you do not have the environment variable defined, or you do have it defined but want to use a different installation of Bathtub without having to redefine the variable.

Here are the same simulator commands without the environment variable. Note that these commands use -F for the options file whereas the earlier commands used -f.

# Xcelium
xrun -uvm -F /path/to/installation/dir/bathtub/src/bathtub_vip_rel.f hello_world.sv +bathtub_features=hello_world.feature

# Questa
qrun -uvm -F /path/to/installation/dir/bathtub/src/bathtub_vip_rel.f hello_world.sv +bathtub_features=hello_world.feature

# VCS
vcs -R -full64 +incdir+$UVM_HOME/src $UVM_HOME/src/uvm.sv $UVM_HOME/src/dpi/uvm_dpi.cc -CFLAGS -DVCS -sverilog -F /path/to/installation/dir/bathtub/src/bathtub_vip_rel.f hello_world.sv +bathtub_features=hello_world.feature

VIP Setup Script

There is one more way to acquire a Bathtub options file. The installation directory contains a SystemVerilog program called vip_setup.sv that outputs a bathtub_vip.f options file in your current working directory. You run the program in any directory to "bless" it in preparation for Bathtub simulations.

The program also generates local copies of the bathtub_vip.csh and bathtub_vip.sh environment setup scripts. If you didn't set your environment variable before, you can do so now by running one of these local scripts.

# Create a new working directory
mkdir -p my/new/work/dir
cd my/new/work/dir

# Run the setup program with Xcelium/Questa/VCS
xrun /path/to/installation/dir/bathtub/vip-spec.sv /path/to/installation/dir/bathtub/vip_setup.sv
# or
qrun /path/to/installation/dir/bathtub/vip-spec.sv /path/to/installation/dir/bathtub/vip_setup.sv
# or
vcs -R /path/to/installation/dir/bathtub/vip-spec.sv /path/to/installation/dir/bathtub/vip_setup.sv

# Run a Bathtub simulation with the newly created options file, "./bathtub_vip.f"
xrun -uvm -f ./bathtub_vip.f # <additional files and options...>
# or
qrun -uvm -f ./bathtub_vip.f # <additional files and options...>
# or
vcs -R -f ./bathtub_vip.f # <additional files and options...>

# Run one of the newly created environment setup scripts.
source ./bathtub_vip.csh
# or
source ./bathtub_vip.sh

echo $BATHTUB_VIP_DIR
Clone this wiki locally