Skip to content

Getting Started

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

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

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

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

Change to your workspace directory, where you created the two files hello_world.sv and hello_world.feature. Use the command 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:

# 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 functional!

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 files are available in a few different ways.

There are two 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.
$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.
Clone this wiki locally