Skip to content

Getting Started

Jump to bottom
Bill Moore edited this page Aug 21, 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!"

The theme here is TMTOWTDI.

Download and Install Bathtub

There are two ways to download and install Bathtub: download a release or clone the Git repository.

A release is a stable snapshot of the repository at a particular point in time. In contrast, the repository contains the entire history of the project, and will continue to evolve. Also, the repository contains every file associated with the project, whereas the release is a curated subset.

The release is the recommended choice if you want to use Bathtub. The repository is the better choice if you want to develop Bathtub.

You could use both methods. For example, you could install the release in a central location for an entire team to use, and clone a Git repository in a personal space for your own use.

Download the Release

View the available releases at https://github.com/williaml33moore/bathtub/releases. Download the latest zip or 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.zip
# or
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.

unzip vX.Y.Z.zip
# or
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

Clone the Repository

Create an empty Bathtub VIP directory in your installation location. This could be a central location that your entire team can share, or a personal workspace for your own use. You can give your new directory any name, e.g., bathtub. Clone the repository into your new directory.

mkdir -p /path/to/installation/dir/bathtub
git clone https://github.com/williaml33moore/bathtub.git /path/to/installation/dir/bathtub

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
setenv BATHTUB_VIP_DIR /path/to/installation/dir/bathtub-X.Y.Z

# sh/bash
export BATHTUB_VIP_DIR=/path/to/installation/dir/bathtub
# or
export BATHTUB_VIP_DIR=/path/to/installation/dir/bathtub-X.Y.Z

The Bathtub directory contains simple setup scripts you can use to set up your environment: bathtub_vip.csh and bathtub_vip.sh.

cd /path/to/installation/dir/bathtub*

source ./bathtub_vip.csh
# or
source ./bathtub_vip.sh

echo $BATHTUB_VIP_DIR

"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.f hello_world.sv +bathtub_features=hello_world.feature

# Questa
qrun -uvm -F /path/to/installation/dir/bathtub/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 /path/to/installation/dir/bathtub/src/bathtub_vip.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 an options file in your current working directory. The program also generates local copies of the bathtub_vip.csh and bathtub_vip.sh environment setup scripts. You run the program in any directory to "bless" it in preparation for Bathtub simulations.

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

# Run the setup program
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 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