bathtub Class Reference

bathtub

Name	Description
Class bathtub	The simulation's entry point to Bathtub.
new()	Constructor.
configure()	Configures how the Bathtub object runs its sequences.
run_test()	Runs the Bathtub test.
get_plusarg_opts()	Gets the plusarg options object.
get_feature_files()	Gets the list of feature files.
concat_feature_files()	Concatenates strings to the end of the internal list of feature files to run.
push_back_feature_file()	Pushes a single string to the end of the internal list of feature files to run.
set_report_object()	Sets the Bathtub object's report object.
get_report_object()	Gets the Bathtub object's report object.
get_sequencer()	Gets Bathtub's configured sequencer.
get_sequence_priority()	Gets Bathtub's configured sequence priority.
get_sequence_call_pre_post()	Gets Bathtub's configured call_pre_post value.
get_dry_run()	Gets Bathtub's dry-run status.
get_starting_scenario_number()	Gets Bathtub's starting scenario number.
get_stopping_scenario_number()	Gets Bathtub's stopping scenario number.
get_include_tags()	Gets the list of Bathtub's include tags.
get_exclude_tags()	Gets the list of Bathtub's exclude tags.
concat_undefined_steps()	Adds steps to Bathtub's list of undefined steps.
as_sequence()	Gets a sequence that can configure and run Bathtub.

Class bathtub

class bathtub extends uvm_component implements bathtub_interface;

The simulation's entry point to Bathtub.

The Bathtub class reads Gherkin feature files and runs them aginst the DUT. In your UVM test or some other component, instantiate a Bathtub object, configure it with a sequencer (perhaps a virtual sequencer from your UVM environment), then run it. Note that bathtub is a uvm_component.

Typical usage:

class bathtub_test extends uvm_test;
	bathtub_pkg::bathtub bathtub;
	uvm_env my_env;

    virtual function void build_phase(uvm_phase phase);
        bathtub = bathtub_pkg::bathtub::type_id::create("bathtub", this);
        super.build_phase(phase);
        ...
    endfunction

    task run_phase(uvm_phase phase);
        phase.raise_objection(this);
        bathtub.configure(my_env.my_sequencer);
        bathtub.run_test(phase);
        phase.drop_objection(this);
    endtask
endclass

Bathtub creates its own sequence, called current_test_sequence, which is an instance of class bathtub_pkg::test_sequence. This sequence is the parent sequence of all sequences Bathtub creates, and provides context that persists for the duration of the simulation. It contains UVM pools of various types so all the child sequences down to the step definitions can share information. current_test_sequence also contains a reciprocal reference back to the Bathtub object, so child sequences have access to it as well.

Bathtub is a subclass of uvm_report_object and by default serves as its own report object for the messages it prints through `uvm_info(), `uvm_error(), etc. The Bathtub object's verbosity can be set with simulator command line plusarg +bathtub_verbosity=<verbosity> independently of +UVM_VERBOSITY=<verbosity>.

---
title: Class Diagram
---
classDiagram
    namespace bathtub_pkg{
        class bathtub{
			#feature_files : string[*]
			#sequencer : uvm_sequencer_base
			#parent_sequence : uvm_sequence_base
			#sequence_priority : int
			#sequence_call_pre_post : bit
			#dry_run : bit
			#starting_scenario_number : int
			#stopping_scenario_number : int
			#bathtub_verbosity : uvm_verbosity
			#report_object : uvm_report_object
			#include_tags : string[*]
			#exclude_tags : string[*]
			#undefined_steps : gherkin_pkg::step[*]
			#plusarg_opts : plusarg_options$ 
            +new()
            +configure()
            +run_test()
        }
        class test_sequence
    }
    namespace uvm_pkg{
        class uvm_report_object
    }
    bathtub --|> uvm_report_object
    bathtub *-- test_sequence : current_test_seq
	test_sequence --> bathtub : bt

Loading

new()

function new(string name="bathtub", uvm_component parent=null);

Constructor.

Initializes the Bathtub object with the given name.

configure()

virtual function void configure(
		uvm_sequencer_base sequencer,
		uvm_sequence_base parent_sequence = null,
		int sequence_priority = 100,
		bit sequence_call_pre_post = 1
	);

Configures how the Bathtub object runs its sequences.

Parameters sequencer, parent_sequence, sequence_priority, and sequence_call_pre_post are all related to the respective arguments of uvm_sequence_base::start(). These parameters all influence how Bathtub executes its context and step definition sequences. Call this function before calling run_test().

sequencer is the sequencer on which Bathtub will execute all its sequences. This is the only required argument.

The Bathtub object creates its own context sequence called current_test_seq. If parent_sequence is null, then current_test_seq is a root parent, otherwise it is a child of parent_sequence.

Bathtub assigns sequence_priority to all its sequences.

sequence_call_pre_post determines whether the sequences' pre_body() and post_body() tasks are called.

run_test()

virtual task run_test(uvm_phase phase);

Runs the Bathtub test.

run_test() causes the Bathtub object to read the provided feature files and execute them on the configured sequencer.

This task is typically called from a UVM test or component's phase implementation method, such as run_phase(). The phase argument is passed along from the phase method's parameter. Be sure to call configure() prior to calling run_test().

Typical usage:

class bathtub_test extends uvm_test;
    ...
    task run_phase(uvm_phase phase);
        phase.raise_objection(this);
        bathtub.configure(my_env.my_sequencer);
        bathtub.run_test(phase);
        phase.drop_objection(this);
    endtask
endclass

If Bathtub encounters any feature file steps that don't have step definitions registered in the resource database, then before returning, run_test() outputs a step definition snippet for each of the steps in the log file and in a separate file called bathtub_snippets.svh. The snippets can be used as the basis for actual step definitions.

get_plusarg_opts()

virtual function plusarg_options get_plusarg_opts();

Gets the plusarg options object.

The plusarg options object contains values passed as +bathtub_* plusargs on the simulator command line.

get_feature_files()

virtual function strings_t get_feature_files();

Gets the list of feature files.

strings_t is a typedef for uvm_queue#(string).

concat_feature_files()

virtual function void concat_feature_files(string files[$]);

Concatenates strings to the end of the internal list of feature files to run.

files is a queue of strings. Each string should be a single filename or a whitespace-separated list of filenames for Gherkin feature files.

e.g.

bathtub.concat_feature_files('{"path/to/features/feature_A.feature"});
bathtub.concat_feature_files('{"path/to/features/feature_B.feature", "path/to/features/feature_C.feature"});
bathtub.concat_feature_files('{"path/to/features/feature_D.feature path/to/features/feature_E.feature"});
bathtub.concat_feature_files(my_queue_of_strings);
bathtub.run_test(phase);

push_back_feature_file()

virtual function void push_back_feature_file(string file);

Pushes a single string to the end of the internal list of feature files to run.

file should be a single filename or a whitespace-separated list of filenames for Gherkin feature files. e.g.

bathtub.push_back_feature_file("path/to/features/feature_A.feature");
bathtub.push_back_feature_file("path/to/features/feature_B.feature path/to/features/feature_C.feature");
bathtub.run_test(phase);

set_report_object()

virtual function void set_report_object(uvm_report_object report_object);

Sets the Bathtub object's report object.

By default, Bathtub is its own UVM report object for the reports (`uvm_info(), `uvm_error(), etc.) it issues. This accessor assigns a different report object. e.g.

bathtub.set_report_object(uvm_root::get()); // Global object
bathtub.set_report_object(bathtub); // Back to self

get_report_object()

virtual function uvm_report_object get_report_object();

Gets the Bathtub object's report object.

By default, Bathtub is its own UVM report object for the reports (`uvm_info(), `uvm_error(), etc.) it issues, but the report object could be reassigned by set_report_object(). Use get_report_object() to get the current report object.

get_sequencer()

virtual function uvm_sequencer_base get_sequencer();

Gets Bathtub's configured sequencer.

Returns the sequencer on which Bathtub will execute all its sequences, as set by configure().

get_sequence_priority()

virtual function int get_sequence_priority();

Gets Bathtub's configured sequence priority.

Returns the sequence priority Bathtub starts all its sequences with, as set by configure().

get_sequence_call_pre_post()

virtual function bit get_sequence_call_pre_post();

Gets Bathtub's configured call_pre_post value.

Returns the call_pre_post value Bathtub starts all its sequences with, as set by configure().

get_dry_run()

virtual function bit get_dry_run();

Gets Bathtub's dry-run status.

If the simulation is run with the +bathtub_dryrun command-line plusarg, then Bathtub will parse the Gherkin feature files, but not run them. The get_dry_run() function returns the dry-run status: 1=dry-run; 0=run.

get_starting_scenario_number()

virtual function int get_starting_scenario_number();

Gets Bathtub's starting scenario number.

The simulator command-line plusarg +bathtub_start=<number> sets the zero-based index of the scenario Bathtub will start running with. This is useful for narrowing the simulation down to scenarios of interest, for example to reproduce failures quickly. get_starting_scenario_number() returns the starting number.

get_stopping_scenario_number()

virtual function int get_stopping_scenario_number();

Gets Bathtub's stopping scenario number.

The simulator command-line plusarg +bathtub_stop=<number> sets the zero-based index of the scenario to stop running with. This is useful for narrowing the simulation down to scenarios of interest, for example to reproduce failures quickly. get_stopping_scenario_number() returns the stopping number.

get_include_tags()

virtual function strings_t get_include_tags();

Gets the list of Bathtub's include tags.

The simulator command-line plusarg +bathtub_include=<tags> sets the comma-separated list of Gherkin tags to include. Only scenarios that have or inherit these tags will run. get_include_tags() returns the list of tags.

get_exclude_tags()

virtual function strings_t get_exclude_tags();

Gets the list of Bathtub's exclude tags.

The simulator command-line plusarg +bathtub_exclude=<tags> sets the comma-separated list of Gherkin tags to exclude. Scenarios that have or inherit these tags will not run. get_exclude_tags() returns the list of tags.

concat_undefined_steps()

virtual function void concat_undefined_steps(gherkin_pkg::step steps[$]);

Adds steps to Bathtub's list of undefined steps.

As it runs, Bathtub maintains a list of feature file steps which do not have matching step definitions. The Gherkin runner uses concat_undefined_steps() to add a queue of gherkin_pkg::step objects to the end of the list. Bathtub uses the list to produce snippets at the end of run_test(). This is for internal use.

as_sequence()

virtual function uvm_sequence_base as_sequence();

Gets a sequence that can configure and run Bathtub.

The classic way to run Bathtub is with the run_test() method. This as_sequence() method presents an alternative way to run Bathtub. Given a bathtub instance, as_sequence() returns a uvm_sequence object. The user can start that sequence like any other sequence. The sequence automatically configures and runs Bathtub, so the user doesn't have to call run_test() or configure(). The Bathtub sequence may even be run implicitly by providing it as the default sequence instance (not type) to the user's sequencer.

This example explicitly runs the Bathtub sequence with start().

virtual function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    bathtub = bathtub_pkg::bathtub::type_id::create("bathtub", this);
    env = basic_env::type_id::create("env", this);
endfunction

virtual task main_phase(uvm_phase phase);
    uvm_sequence_base bathtub_seq;

    bathtub_seq = bathtub.as_sequence();
    bathtub_seq.set_starting_phase(phase);
    bathtub_seq.start(env.seqr);
endtask

This example configures the sequencer so that the Bathtub sequence is the default sequence that runs implicitly.

virtual function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    bathtub = bathtub_pkg::bathtub::type_id::create("bathtub", this);
    env = basic_env::type_id::create("env", this);

    uvm_config_db#(uvm_sequence_base)::set(this, "env.seqr.main_phase",
        "default_sequence", bathtub.as_sequence());
endfunction