Skip to content

Getting Started

Jump to bottom
Bill Moore edited this page Oct 10, 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.

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

See the Complete Setup Guide for alternative methods to download the release, and for instructions to clone the 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-X.Y.Z

# or

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

See the Complete Setup Guide for alternative methods of setting up the environment, including how to run a Bathtub setup script or SystemVerilog VIP setup 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:

cd /path/to/my/work/dir
cp $BATHTUB_VIP_DIR/examples/getting_started/hello_world.sv .
cp $BATHTUB_VIP_DIR/examples/getting_started/hello_world.feature .

$BATHTUB_VIP_DIR/examples/getting_started/hello_world.sv:

// 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

$BATHTUB_VIP_DIR/examples/getting_started/hello_world.feature:

# 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

Run the Simulation

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

In your workspace directory, where you created the two files hello_world.sv and hello_world.feature, use 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(605) @ 0: bathtub [runner] When 
I print 'Hello, World!'
UVM_INFO bathtub/src/bathtub_pkg/gherkin_document_runner/gherkin_document_runner.svh(189) @ 0: bathtub [bathtub_pkg::
gherkin_document_runner.start_step] When I print 'Hello, World!'
UVM_INFO bathtub/src/bathtub_pkg/step_nurture.svh(89) @ 0: reporter [step_attributes] 
 +--------------------------------------------------------------------------------------
 +Name               Type                                  Size  Value                  
 +--------------------------------------------------------------------------------------
 +element_container  uvm_report_message_element_container  -     @2331                  
 +  step             step                                  -     @2171                  
 +    keyword        string                                4     When                   
 +    text           string                                23    I print 'Hello, World!'
 +    argument       object                                -     <null>                 
 +--------------------------------------------------------------------------------------
 +

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

Congratulations, Bathtub is installed correctly and is working!

See the Complete Setup Guide for Bathtub options file choices available for your simulations.

Next Steps

Check out "Hello, World!" for a tour of our simple example.

Clone this wiki locally