Complete Setup Guide

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. Use this flowchart to navigate the process with its many options.

---
title: Getting Started
---
flowchart
    start([Start]) --> create_install_dir

    create_install_dir["Create install dir"] --> release_or_repo

    release_or_repo{"Release
    or repository?"}

    release_or_repo -- release --> download_release["Download release"] --> zip_tar[[.zip/.tar.gz]] --> unzip_to_install_dir["Unpack into install dir"] --> define_env_var
    release_or_repo -- repository -->clone_repo["Clone repository to install dir"] --> define_env_var
    
    define_env_var{"Define environment
    variable?"}

    define_env_var -- yes --> env_setup
    define_env_var -- no --> create_wd

    env_setup{"Manually or
    with setup script?"}

    env_setup -- manually --> env_setup_manual_sh
    env_setup -- script --> env_setup_script_sh

    env_setup_manual_sh[[csh/sh]] --> env_setup_manual
    env_setup_manual["Define environment variable"]
    env_setup_manual --> create_wd

    env_setup_script_sh[[csh/sh]] --> env_setup_script
    env_setup_script["Run install dir setup script"]
    env_setup_script --> create_wd

    create_wd["Create working dir"]
    create_wd --> cp1

    cp1["Copy 'Hello, World!' files"]
    cp1 --> run_vip_setup

    run_vip_setup{"Run setup program
    in working dir?"}
    run_vip_setup -- yes --> run_vip_setup_sim[[Xcelium/Questa/VCS]] --> run_vip_setup_here["Run install dir's setup program
to prepare working dir"] --> env_setup_script_sh2[[csh/sh]] --> opt_run_setup["Optionally run local setup script"] --> sim_local
    run_vip_setup -- no --> abs_or_rel

    sim_local[[Xcelium/Questa/VCS]] --> run_local
    run_local["Run 'Hello, World!' with
local options file"]
    run_local --> finish

    abs_or_rel{"Use options file with
    absolute or relative paths?"}
    
    abs_or_rel -- absolute --> sim_abs
    abs_or_rel -- relative --> sim_rel

    sim_abs[[Xcelium/Questa/VCS]] --> run_abs
    run_abs["Run 'Hello, World!' with
installed absolute path options file"]
    run_abs --> finish

    sim_rel[[Xcelium/Questa/VCS]] --> run_rel
    run_rel["Run 'Hello, World!' with
installed relative path options file"]
    run_rel --> finish


    finish([Finish])

Loading

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

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

  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

We recommend you define an environment variable called BATHTUB_VIP_DIR and set it to the absolute path to your bathtub installation directory. The Bathtub source code doesn't strictly require the environment variable, but some of the included scripts do, and the documentation assumes you have it set. Without the environment variable, you'll need to provide explicit paths.

By definition, you need to define the environment variable every time you start a new shell. We recommend setting it in some type of project initialization script. You can set the environment variable yourself manually, or you can use the setup scripts provided with Bathtub.

Set BATHTUB_VIP_DIR Manually

The syntax varies whether you are using the csh/tcsh family of shells, or the sh/bash family.

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

# or

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

Run a Bathtub Setup Script

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:

• $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

# 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:

• Cadence Xcelium
• Siemens EDA Questa
• Synopsys VCS

Change to 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(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>                 
 +--------------------------------------------------------------------------------------
 +

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!

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