uvm_config_db Examples

The UVM configuration database accessed by the class uvm_config_db is a great way to pass different objects between multiple testbench components.

Methods

There are two primary functions used to put and retrieve items from the database which are set() and get() respectively.

static function void set (  uvm_component   cntxt,
                            string          inst_name,
                            string          field_name,
                            T               value);

static function bit get (   uvm_component  cntxt,
                            string         inst_name,
                            string         field_name,
                      inout T              value);

Rules

• Create or update a config setting for field_name in inst_name from cntxt
• The setting is made at cntxt with the full scope being {cntxt, ".", inst_name}
• If cntxt is null, then inst_name provides the complete scope information of the setting
• field_name is the target field
• Both inst_name and field_name may be glob style or regular expression style expressions
• Settings from hierarchically higher levels have higher precedence
• Settings from the same level of hierarchy have a last setting wins semantic

How to debug uvm_config_db ?

The best way to understand how the combination of cntxt, inst_name and field_name works is by enabling the commandline debug +UVM_CONFIG_DB_TRACE switch for UVM that dumps information on all the set() and get() calls within a simulation.

$> irun <all_other_options> +UVM_CONFIG_DB_TRACE

Example

We'll look at how two testbench environments behave when set and get methods are called from different hierarchies.

1. Test and Env

To understand how config_db evaluates expressions, we'll set up a small testbench structure with an empty environment as shown below. An expression is set from the test class and retrieved in the environment's build_phase

We set cntxt to null and inst_name to uvm_test_top to indicate that all components in the test can access the item. To keep things simple, we'll put a string item tagged as Friend.

class base_env extends uvm_env;
	...
	string name;
	
	virtual function void build_phase (uvm_phase phase);
		super.build_name ();
		
		// Retrieve the string that was set in config_db from the test class
		if (uvm_config_db #(string) :: get (null, "uvm_test_top", "Friend", name))
			`uvm_info ("ENV", $sformatf ("Found %s", name), UVM_MEDIUM)
			
	endfunction
endclass

class base_test extends uvm_test;
	...
	base_env 	m_env;
	
	virtual function void build_phase (uvm_phase phase);
		...
		
		// Set this string into config_db
		uvm_config_db #(string) :: set (null, "uvm_test_top", "Friend", "Joey");
	endfunction
endclass

It is quite clear that the first argument cntxt cannot be anything other than a uvm_component object. From the following simulation log, we can see that when +UVM_CONFIG_DB_TRACE is passed as a command-line switch, simulation will dump all function calls to set and get into the log. However, the lines of our interest are higlighted in color, the yellow one representing a set call and the green representing a successful get call. The concatenation of cntxt, inst_name and field_name match for both set and get calls and hence the database successfully finds and returns the string tagged as "Friend".

ncsim> run
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_root.svh(392) @ 0: reporter [UVM/RELNOTES] 
----------------------------------------------------------------
UVM-1.2
(C) 2007-2014 Mentor Graphics Corporation
(C) 2007-2014 Cadence Design Systems, Inc.
(C) 2006-2014 Synopsys, Inc.
(C) 2011-2013 Cypress Semiconductor Corp.
(C) 2013-2014 NVIDIA Corporation
----------------------------------------------------------------
UVM_INFO @ 0: reporter [RNTST] Running test base_test...
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.base_env.recording_detail' (type logic signed[4095:0]) read by uvm_test_top.base_env = null (failed lookup)
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.base_env.recording_detail' (type int) read by uvm_test_top.base_env = null (failed lookup)
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/SET] Configuration 'uvm_test_top.Friend' (type string) set by  = (string) "Joey"
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.base_env.m_agent0.recording_detail' (type logic signed[4095:0]) read by uvm_test_top.base_env.m_agent0 = null (failed lookup)
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.base_env.m_agent0.recording_detail' (type int) read by uvm_test_top.base_env.m_agent0 = null (failed lookup)
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.base_env.m_agent1.recording_detail' (type logic signed[4095:0]) read by uvm_test_top.base_env.m_agent1 = null (failed lookup)
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.base_env.m_agent1.recording_detail' (type int) read by uvm_test_top.base_env.m_agent1 = null (failed lookup)
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.Friend' (type string) read by  = (string) "Joey"
UVM_INFO testbench.sv(36) @ 0: uvm_test_top.base_env [ENV] Found Joey
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_report_server.svh(847) @ 0: reporter [UVM/REPORT/SERVER] 
--- UVM Report Summary ---

** Report counts by severity

Here, we'll make a slight modification to the set method, rest of the code being the same. The first argument cntxt gets this pointer, while inst_name is empty and still we get the same path "uvm_test_top.Friend" after concatenation.

	uvm_config_db #(string) :: set (this, "", "Friend", "Joey");
	
	// Same get method
	if (uvm_config_db #(string) :: get (null, "uvm_test_top", "Friend", name))
			`uvm_info ("ENV", $sformatf ("Found %s", name), UVM_MEDIUM)

...
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/SET] Configuration 'uvm_test_top.Friend' (type string) set by uvm_test_top = (string) "Joey"
...
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.Friend' (type string) read by  = (string) "Joey"

2. Test, Env, and two Agents

Now we'll expand the environment to have a couple of agents to make things more interesting.

class base_agent extends uvm_agent;
	...
	
	virtual function void build_phase (uvm_phase phase);
		if (uvm_config_db #(string) :: get (null, "uvm_test_top", "Friend1", name))
			`uvm_info ("AGENT", $sformatf ("[%s] found %s", this.get_name(), name), UVM_MEDIUM)
	endfunction
endclass

class base_env extends uvm_env;
	...
	base_agent 	m_agent0;
	base_agent 	m_agent1;
	...
endclass

If we run the code again with the new agents in place, you'll find that both agents also found the string tagged as "Friend1".

UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/SET] Configuration 'uvm_test_top.Friend1' (type string) set by uvm_test_top = (string) "Joey"
...
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.Friend1' (type string) read by  = (string) "Joey"
UVM_INFO testbench.sv(44) @ 0: uvm_test_top.base_env [ENV] Found Joey
...
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.Friend1' (type string) read by  = (string) "Joey"
UVM_INFO testbench.sv(22) @ 0: uvm_test_top.base_env.m_agent0 [AGENT] [m_agent0] Found Joey
...
UVM_INFO /playground_lib/uvm-1.2/src/base/uvm_resource_db.svh(121) @ 0: reporter [CFGDB/GET] Configuration 'uvm_test_top.Friend1' (type string) read by  = (string) "Joey"
UVM_INFO testbench.sv(22) @ 0: uvm_test_top.base_env.m_agent1 [AGENT] [m_agent1] Found Joey

Recommended Practice

The setting in config_db is visible by only those elements that can evaluate to the same expression as the set call. If we keep a global scope such as uvm_test_name, then all components will be able to retrieve that setting. However, this poses a potential problem of collision of field_name within the same scope, as well as retrieval of settings via unintended get calls. Hence, the recommended practice is to make the setting available to only those components that really require the setting to function. In a similar way, during get calls, components should look for settings that are available to them.

The expression that is set in config_db is "uvm_test_top.Friend" based on the set function call. config_db results show the expression evaluated by the get method call. If both of these expressions match or satisfies the glob properties, it is considered to be a match. In the case below, all the three get method calls failed simply because the expression each of the component tried to get is different from the expression that is set.

uvm_config_db #(string) :: set (this, "m_env.m_agent*", "Friend", "Joey");    // Set in test, available to agents
uvm_config_db #(string) :: get (this, "", "Friend", name);                   // Get in env
uvm_config_db #(string) :: get (this, "", "Friend", name);                   // Get in agent

cntxt = uvm_test_top, inst_name = m_env.m_agent*, tag = Friend
Expression set : "uvm_test_top.m_env.m_agent1*.Friend"

CONFIG_DB_TRACE results:
[CFGDB/SET] Configuration 'uvm_test_top.m_env.m_agent*.Friend' (type string) set by uvm_test_top = (string) "Joey"
[CFGDB/GET] Configuration 'uvm_test_top.m_env.Friend' (type string) read by uvm_test_top.m_env = null (failed lookup)
[CFGDB/GET] Configuration 'uvm_test_top.m_env.m_agent0.Friend' (type string) read by uvm_test_top.m_env.m_agent0 = (string) "Joey"
[CFGDB/GET] Configuration 'uvm_test_top.m_env.m_agent1.Friend' (type string) read by uvm_test_top.m_env.m_agent1 = (string) "Joey"

In the above case, the setting was made available only to the agents and hence environment was not able to retrieve it at its level. To make the setting available to the environment, we'll make another set call just for the environment. If you put a * like m_env*, then the setting will be made available to all the components in the environment.

uvm_config_db #(string) :: set (this, "m_env.m_agent*", "Friend", "Joey");    // Set in test, available to agents
uvm_config_db #(string) :: set (this, "m_env",          "Friend", "Joey");    // Set in test, available to env
uvm_config_db #(string) :: get (this, "", "Friend", name);                    // Get in env
uvm_config_db #(string) :: get (this, "", "Friend", name);                    // Get in agent

cntxt = uvm_test_top, inst_name = m_env.m_agent*, tag = Friend
Expression set : "uvm_test_top.m_env.m_agent1*.Friend"
cntxt = uvm_test_top, inst_name = m_env, tag = "Friend"
Expression set : "uvm_test_top.m_env.Friend"

CONFIG_DB_TRACE results:
[CFGDB/SET] Configuration 'uvm_test_top.m_env.Friend' (type string) set by uvm_test_top = (string) "Joey"
[CFGDB/SET] Configuration 'uvm_test_top.m_env.m_agent*.Friend' (type string) set by uvm_test_top = (string) "Joey"
[CFGDB/GET] Configuration 'uvm_test_top.m_env.Friend' (type string) read by uvm_test_top.m_env = (string) "Joey"
[CFGDB/GET] Configuration 'uvm_test_top.m_env.m_agent0.Friend' (type string) read by uvm_test_top.m_env.m_agent0 = (string) "Joey"
[CFGDB/GET] Configuration 'uvm_test_top.m_env.m_agent1.Friend' (type string) read by uvm_test_top.m_env.m_agent1 = (string) "Joey"

A few examples on set and get methods were illustrated in the previous article. Now we'll see more combinations of expressions used to set and get settings from config_db and see the result of such operations on the same testbench structure with two agents in an environment.

set vs get results

To recap, a setting with field_name "Friend" is set with different cntxt and inst_name in the config_db. This is obtained by both agents and the environment using the get method with different cntxt and inst_name combinations. If the get call is successful, the cell is highlighted in pale green, else it is highlighted in pale red.

// Set the given field_name "Friend" in test
uvm_config_db #(string) :: set (cntxt, inst_name, "Friend", "Ross");

// Get "Friend" in env and agents
uvm_config_db #(string) :: get (cntxt, inst_name, "Friend", "Ross");

Hierarchy of each component:
  Environment : uvm_test_top.m_env
  Agent1      : uvm_test_top.m_env.m_agent1
  Agent2      : uvm_test_top.m_env.m_agent2

The first column in the table shown below is for the test class that sets the field Friend with the given cntxt and inst_name. All subsequent columns represent different components that try to get the setting from config_db which in our example is the environment and two agents.