VMM Golden Reference Guide Jan 2010

A concise guide to VMM Verification Methodology Version 1.
2
VMM is available for free download at www.vmmcentral.org

VMM Golden Reference Guide

First Edition, January 2010

Copyright 2010 by Doulos Ltd. All rights reserved.

The information contained herein is the property of Doulos
Ltd and is supplied without liability for errors or omissions.
No part may be used, stored, transmitted or reproduced in
any form or medium without the written permission of
Doulos Ltd.

Doulos
is a registered trademark of Doulos Ltd.

VMM is licensed under the Apache Software Foundations
Apache License, Version 2.0, January 2004. The full
license is available at http://www.apache.org/licenses/
All other trademarks are acknowledged as the property of
their respective holders.

First published by Doulos 2010

ISBN 0-9547345-7-2

Doulos
Church Hatch
22 Market Place
Ringwood
Hampshire
BH24 1AW
UK

Tel +44 (0) 1425 471223
Fax +44 (0) 1425 471573

Email: info@doulos.com
Web: http://www.doulos.com

Contents

Page
Preface ............................................................................................5
Using This Guide .............................................................................6
A Brief Introduction To VMM ...........................................................7
Alphabetical Reference .................................................................15
Index ........................................................................................... 337

Copyri ght 2010 by Doul os Ltd. All ri ghts reserved. 5
Preface
The VMM Golden Reference Guide is a compact reference guide to VMM
Standard Library 1.2 for SystemVerilog.
The intention of the guide is to provide a handy reference. It does not offer a
complete formal description of all VMM classes and class members. Instead it
offers answers to the questions most often asked during the practical application
of VMM in a convenient and concise reference format. It is hoped that this guide
will help you understand and use VMM more effectively.
This guide is not intended as a substitute for a full training course and wi ll
probably be of most use to those who have received some training. Also it is not
a replacement for the official VMM Standard Library Reference Guide and User
Guide, which form part of the VMM and are avai lable from www.vmmcentral.org.
The VMM Golden Reference Guide was developed to add value to the Doulos
range of training courses and to embody the knowledge gained through Doulos
methodology and consulting acti vities.
You wi ll find some additional resources at the VMM Golden Reference Guide's
companion web page, http://www.doulos.com/vmm.

6 Copyri ght 2010 by Doul os Ltd. All ri ghts reserved.
Using This Guide
The VMM Golden Reference Guide comprises a Brief Introduction to VMM, the
Alphabetical Reference section and an Index.
This guide assumes a knowledge of SystemVerilog and testbench automation. It
is not necessary to know the full SystemVerilog language to understand the
VMM classes, but you do need to understand object-oriented programming in
SystemVerilog. You will find some tutorials at http://www.doulos.com/knowhow.
Organization
The main body of this guide is organized alphabetically into sections and each
section is indexed by a key term, which appears prominently at the top of each
page. Often you can find the information you want by flicking through the guide
looking for the appropriate key term. If that fails, there is a full index at the back.
Except in the index, the alphabetical ordering ignores the prefi x vmm_. So you
will find TLM Interfaces between the articles vmm_timeline and
vmm_unit.
Additionally, some articles are not in strict alphabetical order for example i t
makes sense for RTL Configuration to come before vmm_rtl_config.
The Index
Bold index entries have corresponding pages in the main body of the guide. The
remaining index entries are followed by a list of appropriate page references in
the alphabetical reference sections.
Methods and Members
Most sections document the methods and members of VMM classes. Not all
public members and methods are included; we have tried to concentrate on
those that you may want to use when using the VMM. Also, deprecated features
are not usually included. For details on all the members and methods, please
refer to the official VMM Standard Library Reference Guide and the actual VMM
source code.

A Brief Introduction To
VMM
Background
The VMM methodology facilitates the creation of robust, reusable and scalable
verification environments using SystemVerilog. Introduced in 2005, it is the
industrys most widely used and proven verification methodology for
SystemVerilog.
The VMM methodology enables verification novices and experts alike to develop
powerful transaction-level, constrained-random and directed verification
environments. A comprehensi ve set of guidelines, recommendations and rules
help engineers avoid common mi stakes while creating interoperable verification
components. The VMM Standard Library provides the foundation base classes
for building advanced testbenches, while VMM Applications provide higher-level
functions for improved producti vi ty.
The SystemVerilog language introduced powerful new verification language
constructs such as constraints, functional coverage and object-oriented
programming. Recognizing that many engineers would require guidance on how
to take advantage of these language features, ARM and Synopsys began a
collaboration in 2004 to develop a SystemVerilog verification methodology. The
result the VMM methodology was defined in the book Verification
Methodology Manual for SystemVerilog. Over 4,000 copies of the English
language edi tion have been distributed, making it one of the top-selling
verification references in print.
The SystemVerilog language and the VMM Standard Library provide a stable
foundation for methodology innovation. In 2007, Synopsys expanded the scope
of the VMM methodology by introducing VMM Applications. VMM Applications
are high-level functions that facilitate on-chip register verification, connections to
hardware-assisted verification, verification of on-chip memory, and more.
VMM 1.2 builds on the earlier versions by providing many new classes. These
provide enhanced support for configuration, si mulation control, object hierarchy
and hierarchical name matching and transaction-level modeling.
The VMM Standard Library
The VMM Standard Library provides base classes for key aspects of the
verification environment, an event notification service, and a message logging
service. VMM-compliant test environments must use these base classes,
suitably extended to provide any required custom functionali ty.
A Brief Introduction to VMM
VMM and SystemVerilog
VMM is written in SystemVerilog and is supported by industry-standard
simulators.
The VMM source code can be downloaded from www.vmmcentral.org. There
is also an acti ve user forum on the site that any registered user can freely
participate in.
VMM Testbench Structure
The structure of a typical VMM testbench can be summarized thus:
Notification and message-logging services
A key feature of VMM is its pervasi ve message-logging mechanism. Almost
every object in a VMM testbench, including transaction data objects, will have
access to an instance of the vmm_log class through which it can deli ver textual
messages for diagnostics, debug, warnings and general reporting. The logging
service is highly configurable instance-by-instance and provides a uniform,
flexible mechanism for managing text output to the console and to files.
The notification service provides an enhanced form of event signaling, allowing
components and transactions to indicate significant events in their lifecycle and
to publish status flags. It is considerably more versatile than the conventional
Verilog event mechani sm.
Data objects and the testbench structure
User-defined transaction data are captured as a class derived from vmm_data.
This base class, and its associated automation macros, provide many features
supporting copying, randomization, comparison, cloning, transformation and
identification of such transaction data objects as they flow through the testbench
and are manipulated by transactors.
The testbench comprises a structure of transactors, interconnected by channels
or TLM connections, instanced in an environment and persisting for the duration
of the test run. The whole of this structure is built dynamically under program
control, as is always the case with SystemVerilog classes.
Transactors
Transactors form the leaves of the VMM testbench tree structure. A transactor
can be any of the following:
Generators, which create a stream of (usually) randomized transactions.
Built-in generator classes exist to create straightforward streams of
randomized transactions (atomic generator) and streams of randomized but
structured sets of transactions (scenario generator). Generators deli ver
their transaction stream to output (sink) channels.
Function-level transactors accept transactions on one or more input
(source) channels or sockets, manipulate and store those transactions in a
user-defined manner, and deli ver one or more streams of transactions
(possibly of a quite different data type) on one or more outputs.
Command-level transactors manage the relationship between transaction
data objects and acti vi ty on ports of the device under test. Typically, they
have the functionality that would be encapsulated in a bus functional model
(BFM) in a traditional Verilog testbench. A command-level transactor
communicates with other transactors using channels or sockets, and
interacts with the DUT by manipulating signals through a virtual interface.
The functionality of transactors can be augmented using callbacks. This
technique allows arbitrary user code to be introduced at predetermined points in
a transactor's procedural flow. Callbacks provide a flexible mechanism
supporting observation of transactor acti vity, error injection, packet loss,
coverage collection and many other extensions of testbench behavior. They can
be added to a transactor (registered) dynamically, at any time. A registered
callback can equally easily be removed (unregistered) at any time.
Channels
A channel is a sophisticated FIFO buffer, with many additional features, used to
connect one transactor to another. The use of channels effecti vely decouples
transactors from one another, and also provides buffering so that the ti ming of
DUT acti vi ty (as seen at command-level transactors) is largely hidden from
higher-level parts of the testbench. Specialized versions of channels support
many-to-one and one-to-many connection among transactors.
TLM-style connection
To support interoperability wi th TLM-based verification IP, VMM 1.2 offers a
connection scheme based on the OSCI TLM-2 standard. New features of the
channel base class make it straightforward for VMM 1.2-style components, using
TLM connection, to interoperate with classic transactors designed for channel-
based communication. An analysis port mechanism supports broadcasting of
transactions to observer components.
Explicit phasing and the environment class
The topmost level of the testbench hierarchy is an instance of an environment
class, derived from the standard library base class vmm_env. The environment
has data members holding instances of all necessary sub-environments,
transactors and channels. The environment base class has a run() method
that automatically sequences execution of the environment's phases a series
of virtual methods that should be overridden, in the user's deri ved environment
class, wi th application-specific functionality. Each phase performs a clearly
defined operation in the testbench's lifecycle. The phases, and the operations
that user code in them should perform, are:
gen_cfg()
Create configuration data objects (usually by randomization) that will be
used to determine the detai led configuration of each testbench component.
build()
Create instances of all necessary testbench components subenvs,
transactors, generators and channels. Connect channels to appropriate
source and sink transactors.
reset_dut(), cfg_dut()
Use the testbench (which is, by now, fully constructed) to perform any
necessary initializations on the DUT.
start()
Call the start_xactor() method of every transactor and generator, so
that all transactors begin their normal operation sequence.
wait_for_end()
By observing the testbench's behavi or, or by any other appropriate method,
allow testbench execution to proceed unti l all desired test acti vity has
completed. In this task, the environment itself may perform autonomous
activi ty as part of the test.
stop(), cleanup()
Call the stop_xactor() method of every generator (and potentially every
transactor), so that the DUT becomes idle. Flush out data structures, files
etc. as necessary, so that the result of the test can be cleanly checked.
report()
Dump report data to appropriate files, display summary information etc.
Phases and timelines
Co-exi sting with the explicitly-phased si mulation phases described above, VMM
1.2 has a sophisticated implicit phasing mechanism that supports the
composi tion of a testbench or component's lifecycle from a series of phases,
each of which is implemented by overriding a virtual method in the component.
The topmost level of an implicitly-phased testbench hierarchy is an instance of
an environment class, derived from the standard library base class vmm_group.
Execution of these phases is managed by a vmm_timeline component which,
by default, runs each phase on all components below it in the instance hierarchy.
However, it is also possible to include additional ti meline components lower
down the hierarchy. These lower-level timelines allow their own children to have
a different lifecycle which is nevertheless coordinated with the upper timeline's
flow in a well-controlled way. Pre-defined phases can be modified or removed,
and users can insert their own custom phases.
RTL configuration
Many RTL designs, particularly those intended for re-use, are heavily
parameterized. This introduces two challenges for verification: ensuring that the
testbench correctly respects the DUT's configuration parameters, and running
verification on various DUT implementations with a sufficiently diverse set of
parameters. A specific but highly configurable VMM 1.2 mechanism, based on
classes vmm_rtl_config and vmm_rtl_config_file_format, supports
management of the relationship between parameters that were used to control
elaboration of the DUT and those used to control the construction and execution
of the testbench.
Sub-environment
The vmm_group and vmm_subenv base classes facilitate the creation of self-
contained re-usable verification components. Like the environment, they act as
containers for instances of transactors and channels and their simulation phases
can be controlled implicitly or explicitly. However, it can have channel and DUT-
level interfaces, and therefore also has si milar status to a transactor. An
environment can contain instances of transactors, channels and sub-
environments.
Named component hierarchy
In addition to the structural hierarchy of environment, sub-environments and
transactors, VMM 1.2 offers a uniform mechanism for composing any testbench
components into a named hierarchy. To support this hierarchy structure, all
testbench components should be derived from the new base class
vmm_object. Unless the NO_VMM_12 macro is defined at compi lation ti me,
vmm_group is automatically used as an underlying base class for all testbench
component classes.
Options and configuration
Well-designed testbench components and sub-environments are likely to have
many configurable options. Consequently, the testbench as a whole will be
capable of performing many different types of test si mply by setting appropriate
values for these options. However, some options may be applicable only to
components that are deeply buried in the testbench's instance hierarchy, at a
location that may vary somewhat from one test run to another. As a result, the
control of these option values can be troublesome in practice.
VMM 1.2 offers a powerful options control mechanism, based on string pattern
matching, that leverages the named component hierarchy mentioned earlier.
The flexibi lity of string-based name matching makes it possible to locate relevant
testbench components even in a complex hierarchy. Each component
announces its need for option values by placing calls to appropriate "get option"
methods these calls include documentation text, allowing the testbench to
report the options that it requires in a human-readable form. The "get option"
methods pull values from an options database that can be populated in various
ways: by explicit "set option" calls during the testbench's configuration or build
phase, on the si mulator's command line, or from one or more plain-text option
control files. The option management methods are provided in class vmm_opts
and are supported by various configuration macros.
This option mechani sm makes it possible to write highly configurable verification
IP that can in turn be composed into highly configurable testbenches.
Configuration is then achieved si mply by modifying a command line or an
options file; in many cases, no code changes are required.
Class factory
Object-oriented programming (OOP) makes it easy to create derived classes
that have all the functionality of a base class with a few extensions or
modifications, and this appears at first glance to be an attracti ve idea for
testbenches where, for example, a transaction data object with error injection
could be expressed as a class derived from the error-free data class. However,
in practice it is not so simple; much of the testbench infrastructure may need to
be modified to make use of the deri ved class. To support late modification of
testbench behavior, VMM requires the use of a factory mechanism and uses
such a mechanism in its pre-defined generators. If a testbench component
creates objects not by calling their constructor but, rather, by calling a factory
method, then this single centralized factory method can be made aware of the
existence of a derived class and can arrange to create a deri ved class object
whenever it is asked to create a base class object. Thanks to the object naming
mechanism already mentioned, this factory override can be implemented in a
very flexible and dynamic way based on the string names of the various data
classes.
In principle the class factory can also be used to create testbench components.
However, it is generally preferable to use callbacks rather than class inheritance
to extend the capabi lities of transactors and other testbench components,
because callbacks can be revoked (un-registered) at any time without trashing
the host component's state, whereas inheritance-based extension can only be
undone by destroying a component and replacing it with another. Furthermore,
orthogonal callback extensions can be easi ly combined in arbitrary combinations
whereas arbitrary combinations of orthogonal class extensions require an
exponential number of classes.
VMM 1.2 Class Hierarchy
The following diagram shows the relationship between the various base classes
familiar from classic VMM and the most heavi ly-used new classes introduced by
VMM 1.2 (shown in the shaded area). Dashed lines indicate an inheritance
relationship that is optional, and is managed by macros that are enabled unless
the NO_VMM_12 macro is defined at compilation time. This optional
underpinning is the default behavi or in VMM 1.2 and is appropriate for all new
VMM user code and should be used in the few instances that backward
compatibility may be compromised.

Alphabetical Reference Section

VMM
Alphabetical
Reference

vmm_atomic_gen
An atomic generator is a specialized vmm_xactor that generates a stream of
randomized transaction objects. The atomic generator uses a class factory
pattern to create, randomize then put into the output channel the number of
transaction objects specified by stop_after_n_insts. Each transactions
vmm_data::stream_id property is set to the stream identifier specified when
the constructor is called. The data_id is set to the current transaction count or
0 if the generator is reset.
The atomic generators transactions can be customized in three ways: (1)
replacing the class factory pattern, (2) defining an atomic generator callback
faade, or (3) manually injecting transactors into the output channel using the
inject() method. With the first approach, additional random constraints are
added to a deri ved vmm_data object and assigned to the generator's factory.
The second approach involves defining a callback method. The callback method
is called post_inst_gen and it must be a member of a class derived from
vmm_atomic_gen_callbacks. Since vmm_atomic_gen is a template class,
macros have been provided to si mplify defining callbacks
`vmm_atomic_gen() and `vmm_atomic_gen_using(). These macros
automatically create a generator named class_name_atomic_gen and a
callback class named class_name_atomic_gen_callbacks. The new
callback class can be extended to affect the transaction object before it is put in
the output channel and then registered with the atomic generator using
vmm_xactor:: append_callback() or
vmm_xactor::prepend_callback().
The third approach involves using the inject() method. When a transaction is
injected, it is not randomized but the registered callbacks are invoked. If the
callback sets the dropped argument, then the transaction wi ll not be placed into
the output channel.
In addition to the standard vmm_xactor notifications, the atomic generator
defines two new notifications: GENERATED and DONE. When a transaction
object is added to the output channel, a GENERATED notification is indicated, and
when the atomic generator has reached its maxi mum number of generated
transactions then the DONE notification is indicated.
For more sophisticated sti mulus generation, see vmm_ms_scenario.

Atomic
Generator
out_chan
factory
vmm_atomic_gen
Declaration
class vmm_atomic_gen_base extends vmm_xactor;
class vmm_atomic_gen #(
type T = vmm_data,
C = vmm_channel_typed#(T),
string text = "" )
extends vmm_atomic_gen_base;
Methods
function new(
string inst,
int stream_id = -1,
C out_chan = null);
stream_id is an optional
stream identifier.
out_chan is an optional
channel for the stream of
output transactions.
virtual task inject(
T obj,
ref bit dropped);
Injects a transaction into the
output stream.
The post_inst_gen
callback is invoked.
dropped is passed into the
callback faade method,
post_inst_gen(). If
dropped equals 0, then the
transaction has not been
added to the output channel.
virtual task post_inst_gen(
vmm_atomic_gen #(T,C,text)gen,
T obj,
ref bit drop);
Callback invoked when a
transaction is created.
virtual function void
reset_xactor(
vmm_xactor::reset_e rst_type
= SOFT_RST);
Resets the transactor and
flushes the output channel.
When rst_type equals
FIRM_RST, the transactor
notification object is reset.
When rst_type equals
HARD_RST, the
stop_after_n_insts
variable is cleared and the
factory is reset
vmm_atomic_gen
Members
C out_chan; Output channel.
Created automatically if a reference is
not provided to the constructor.
T randomized_obj; Class factory template used for
randomizing and copying to generate
new transaction objects for the output
channel.
int unsigned
stop_after_n_insts;
Maxi mum number of transaction
objects to generate.
If less than or equal to 0, then the
maxi mum is unlimi ted.
typedef enum int {
GENERATED,
DONE
} symbols_e;
Atomic generator specific notification
values.
GENERATED: A ONE_SHOT notification
generated each ti me a transaction
object is generated or injected.
DONE: An ON_OFF notification
generated when the atomic generator
is finished.
Macros
`vmm_atomic_gen(
T,
text)
Macro to automatically generate an
atomic generator and callback with the
names class_name_atomic_gen and
class_name_atomic_gen_callbacks.
T = generated transaction object class
name (by default, vmm_data).
text = name of atomic generator.
`vmm_atomic_gen_using(
T,
C,
text)
Macro to automatically generate an
atomic generator with the name
class_name_atomic_gen that uses a
specific output channel type.
T = generated transaction object class
name (by default, vmm_data).
C = channel class type (by default,
vmm_channel).
text = name of atomic generator.
vmm_atomic_gen
Example
`vmm_atomic_gen( plcp_trans, "PLCP transaction Generator" )
// Define a callback
class plcp_cb extends plcp_trans_atomic_gen_callbacks;
function new ( mac_phy_env env );
this.env = env;
endfunction

virtual task post_inst_gen(
plcl_trans_atomic_gen gen,
plcp_trans obj,
ref bit drop );
// Keep a history of all transactions
env.history_q.push_back( obj );
endtask
endclass

class mac_phy_env extends vmm_env;

plcp_trans tr;
plcp_trans history_q[$];
plcp_trans_atomic_gen mac_gen;
mac_model mac;

virtual function void build();
super.build();
tr = new ( ... );
mac = new ( ... );
mac_gen = new( "MAC Transactor", 1, mac.tx_chan );
mac_gen.stop_after_n_insts = 20;
mac_gen.randomized_obj = tr;
begin
plcp_cb cb = new ( this );
mac_gen.append_callback( cb );
end
endfunction

virtual task start();
super.start();
mac.start_xactor();
mac_gen.start_xactor();
endtask

vmm_atomic_gen
virtual task wait_for_end();
super.wait_for_end();
mac_gen.notify.wait_for( vmm_atomic_gen::DONE );
...
endtask
...
endclass
Tips
Use a callback to modify transactions after randomization. Use the class
factory pattern to change the random constraints.
Use a callback to sample the generated transactions in a coverage model
or forward them to a scoreboard.
Gotchas
The atomic generator macros do not require a semicolon!
When using the `vmm_atomic_gen_using() macro, be sure that the
specified channel type can handle the specified transaction type.
If stop_after_n_insts equals 0 or less, the atomic generator wi ll not
stop.
See also
vmm_xactor, vmm_xactor_callbacks, vmm_ms_scenario
vmm_broadcast
VMM channels facilitate point-to-point transaction-level communication between
components. The vmm_broadcast class offers a point-to-multi-point
mechanism for duplicating a stream of transaction data from a single source to
multiple output channels. The replicated transactions are sent either by
reference or by copy.

Broadcast channels have two operational modes: (1) As Fast As Possible
(AFAP), and (2) As Late As Possible (ALAP). In AFAP mode, the full level of the
output channel(s) is ignored, and only the source channel level is used to control
the flow of transactions. Consequently, if an active output channel becomes
empty, a transaction is removed from the source channel and sent to all output
channels, even if they are full. In ALAP mode, whichever channel, source or
output(s), is slowest determines the flow and control of transactions. When all
output channels are empty, then a transaction is removed from the source
channel and added to all the output channels.
Declaration
class vmm_broadcast extends vmm_xactor;
Methods
function new(
string name,
string inst,
vmm_channel source,
bit use_references = 1,
int mode = AFAP,
vmm_object parent = null);
source refers to the source
channel.
If use_references equals
1, then transactions are
passed by references;
otherwise, they are passed
as copies.
mode is either AFAP or
ALAP.
channel
channel
channel
channel
v
m
m
_
b
r
o
a
d
c
a
s
t

vmm_broadcast
virtual protected function bit
add_to_output(
int unsigned decision_id,
int unsigned output_id,
vmm_channel channel,
vmm_data obj);
Overloadable function that
changes the broadcasting
rules.
Returns 1 if the transaction
can be added to the specific
channel. Returns 0 if
transaction was is not to be
added to channel.
decision_id is
incremented each time the
function is called during a
broadcast cycle.
virtual function void bcast_off(
int unsigned output_id);
Turns off broadcasting to
the specified output
channel.
virtual function void bcast_on(
int unsigned output_id);
Turns on broadcasting to
the specified output
channel.
virtual task broadcast_mode(
bcast_mode_e mode);
Changes broadcasting
mode (takes effect
immediately).
Possible modes: AFAP and
ALAP.
virtual function int new_output(
vmm_channel channel,
logic use_references = 1'bx);
Adds the specifies channel
to the broadcast output
channels.
use_references defines:
1 : references sent to output
0 : copies sent to output
X: default configuration used
(specified in constructor)
Returns unique integer
channel id.
virtual function string
psdisplay(
string prefix = "");
Function to print out the
broadcast information.
reset_xactor(
vmm_xactor::reset_e rst_typ
= SOFT_RST);
Resets broadcaster and
flushes input/output
channels.
Reset type equals
SOFT_RST,
PROTOCOL_RST,
FIRM_RST, or HARD_RST
(see VMM reference manual
for details).
vmm_broadcast
start_xactor();
Starts the broadcaster
instance.
stop_xactor();
Stops the broadcaster
instance.
Members
typedef enum {
AFAP,
ALAP
} bcast_mode_e;
Broadcaster mode
enumeration.
Example
`vmm_channel( trans )
class my_env extends vmm_env;
trans_channel input_chan = new( "Input channel",
"input_chan", 3 );
vmm_broadcast bcast = new ("Broadcaster",
"bcast",
input_chan, // Src channel
0); // Use copies
...

trans_channel out_chan[4]; // Output channels

function void build();
int chan_ids[4];
// Create the output channels
foreach ( out_chan[i] )
out_chan[i] = new( "Out Channel", i, 1 );

// Add channel to broadcaster
foreach ( out_chan[i] )
chan_ids[i] = bcast.new_output( out_chan[i], 1'bx );

// Connect channels to environmental components
producer.chan = input_chan;
consumer1.chan = out_chan[0];
consumer2.chan = out_chan[1];
...
endfunction
...
endclass
vmm_broadcast
// In the producer
repeat (10) begin
trans tr = new;
void'( tr.randomize() );
chan.put( tr ); // Send transaction
end

// In the consumers
trans tr;
chan.get( tr ); // Consume the transaction
Tips
If a transaction only needs to be broadcast to 2 channels, then the
vmm_channel::tee() method could also be used.
If no output channels are attached to the broadcaster or the output
channels are turned off (via bcast_off()), then data is constantly drained
to avoid accumulation.
The decision ID passed into add_to_output() can be used to detect the
start of a broadcasting cycle because it is reset to 0 and incremented as it
is sent to the output channels each broadcasting cycle.
A transaction can be duplicated on an output if it is explicitly added to the
output channel in add_to_output() and 1 is returned.
Gotchas
Any extension of the methods start_xactor(), stop_xactor(),
bcast_off(), bcast_on() must call the its base class method (e.g.,
super.start_xactor())
If the output channels do not consume transactions at the same average
rate, then mode AFAP should not be used when the input channel can
produce data at a higher rate than the slowest output channel.
Make sure that extensions to add_to_output() do not return false for
ALL output channels, or lock-up may occur.
If transactions are manually added by add_to_output() to the output
channel(s), then use the vmm_channel::sneak() method and return 0 to
avoid blocking the execution thread and the transaction from being
duplicated.
See also
vmm_channel, vmm_xactor
vmm_channel
A VMM channel provides a transaction level interface between testbench
components. Since all channels have the same interface methods, they provide
a means of decoupling the connections between components, facilitating greater
reuse and flexi bility.
A channel is created either using the macro `vmm_channel, which creates a
channel of the specified name wi th a _channel suffix, or directly using the
vmm_channel_typed parameterized class. Each component on either end of
the channel holds a reference to the channel, typically passed through a
constructor call or connected at a higher level of hierarchy.
Channels have many modes of operation based on how they are used. For
example, they can transfer transactions atomically, in a blocking or non-blocking
manner, and out-of-order. When connecting to a channel, it is important that the
consumer implements a compatible use model.
The methods put() and get() are used to insert or remove transactions.
Components requiring blocking channel behavior may need to avoid emptying
the channel by calling peek() or activate(), or may wish to avoid blocking
by using sneak().
An important feature of channels is the active slot. The acti ve slot keeps track of
the currently acti ve transaction, allowing transactors to fill a channel wi thout
retaining references to each transaction. The functions activate(), start(),
complete(), and remove() modify the active slot status so a consumer can
update the transaction status as it is processed. Typically, a channel consumer
should use the acti ve slot and a producer should use put() followed by a
wait_for(ENDED) indication.
VMM 1.2 has extended the vmm_channel functionality for interoperability with
the TLM 2.0 interfaces. TLM interfaces can be connected to a channel using the
tlm_bind() method, and transactions are seamlessly forwarded through the
channel and TLM connections. The channel can also be used to adapt a
(non)blocking TLM initiator to a (non)blocking TLM target.
Declaration
`vmm_channel( channel_name )
class vmm_channel_typed #(type T = vmm_data) extends
vmm_channel;
VMMchannel
-(n-1)
1
-n
0
-2
n-2
-1
n-1
-(n-2)
2
active slot
vmm_channel
Methods
function new(
string name,
string inst,
int full = 1,
int empty = 0,
bit fill_as_bytes = 0);
full specifies the FIFO
depth. empty specifies
minimum bounds on the
FIFO. fill_as_bytes
specifies if FIFO level is
based on number of
transactions or number of
bytes.
task activate(
output T
1
obj,
input int offset
2
= 0);
Sets transaction at the
specified offset in the acti ve
slot.
Returns current acti ve slot
transaction in obj.
function T
1
active_slot(); Returns a reference to the
transaction in the acti ve slot.
function T
1
complete(
vmm_data status = null);
Updates the acti ve slot
status to completed.
function int unsigned
empty_level();
Returns the value of empty.
function void flow(); Starts the flow of
transactions through the
channel.
function void flush(); Empties the channel
contents.
function vmm_data for_each(
bit reset = 0);
Iterates through all the
transactions in a channel
(except the acti ve slot
transaction).
Returns a reference to the
next transaction if reset is
0; returns a reference to the
first transaction if reset is
1; returns null after last
transaction.
for_each_offset();
Returns the position (offset)
in the channel of the
transaction returned by
for_each().
full_level();
Returns the channel depth.
task get(
output vmm_data obj,
input int offset
2
= 0);
Returns the next transaction
from the channel at the
specified offset.
vmm_channel
task grab(vmm_scenario grabber); Grabs exclusi ve access for
the specified scenario.
function bit is_full(); Returns 1 if channel is full.
function bit is_grabbed(); Returns 1 if channel has
been grabbed.
function void kill(); Prepare the channel for
deletion.
function bit is_locked(
bit [1:0] who);
Returns 1 if the specified
side of the channel is
locked.
who specified as
vmm_channel::SOURCE,
vmm_channel::SINK, or
vmm_channel::SOURCE+
vmm_channel::SINK.
function int unsigned level(); Returns the current fill level
of the channel.
function void lock(
bit [1:0] who);
Blocks producer as if the
FIFO was full.
who specified as
vmm_channel::SINK.
task peek(
input int offset
2
= 0);
specific (offset) transaction
in the channel wi thout
removing it.

task playback(
output bit success,
input string filename,
input vmm_data factory,
input bit metered = 0,
vmm_scenario grabber = null);
Loads a channel with the
transaction objects found in
filename. The file is read
by the vmm_data::load()
method. The metered
argument specifies loading
transactions with the same
relati ve ti ming as when
recorded. grabber
specifies the scenario that
has grabbed the channel.
Returns sucess = 1 upon
sucess.
function string psdisplay(
Prints out channel status.
vmm_channel
task put(
vmm_data obj,
int offset
2
= -1);
Places transaction object
into channel as specified by
offset.
function void reconfigure(
int full = -1,
int empty = -1,
logic fill_as_bytes = 1'bx);
Modify channel
configuration values.
function bit record(
string filename);
Starts recording
transactions into filename.
Transaction objects need
the vmm_data::save()
method implemented for
recording.
function void register_vmm_sb_ds(
vmm_sb_ds sb,
vmm_sb_ds::kind_e kind,
vmm_sb_ds::ordering_e order
= vmm_sb_ds::IN_ORDER);
Registers scoreboard with
channel.
Registering a data stream
scoreboard with a channel
causes all transactions or
indications forwarded to the
scoreboard at the ti me of
removal.
function T
1
remove(); Removes the current
transactor from the
channels acti ve slot.
function void reset(); Flushes the channel and
releases any grabbers.
function void sink(); Flushes the channel and
causes it to be put in the
sink state (i.e., always
empty) until flow() is
called.
function int unsigned size(); Returns the number of
transactions in a channel
including the acti ve slot
transaction.
function void sneak(
vmm_data obj,
int offset
2
= -1,
vmm_scenario grabber = null);
Places a transaction in the
channel at the specified
offset. sneak() never
blocks (like put()) even if
FIFO is full.
function T start(); Updates the status of the
active slot transaction to
vmm_channel::STARTED.
vmm_channel
function active_status_e
status();
Returns status of acti ve slot
transaction: INACTIVE,
PENDING, STARTED, or
COMPLETED.
task tee(
output vmm_data obj);
If tee mode is set, then
returns a copy of the
transaction retrieved by the
get() or activate()
methods.
Blocks until one of those
methods completes
successfully.
function bit tee_mode(
bit is_on);
Sets or clears tee mode for
the channel.
function bit try_grab(
vmm_scenario grabber);
Non-blockingly attempts to
grab the channel.
Returns 1 upon success.
function T try_peek(
int offset = 0);
Non-blockingly attempts to
return the transaction at the
specified channel offset.
function void ungrab(
vmm_scenario grabber);
Releases a scenarios
exclusi ve access on a
channel.
function void unlock(
bit [1:0] who);
Blocks consumer as if the
FIFO was empty.
who specified as
vmm_channel::SINK.
function T
1
unput(
int offset
2
= -1);
Remove transaction from
channel at the specified
offset.
function void
unregister_vmm_sb_ds(
vmm_sb_ds sb);
Unregisters scoreboard from
the channel.

1
T represents the class type supplied to `vmm_channel (type) or
vmm_channel_type( type ).
2
offset defined as: 0 = head of channel, -1 = tail of channel, posi ti ve offsets
from head of channel, and negati ve offsets from tail of channel.
vmm_channel
Members
typedef enum {
INACTIVE,
PENDING,
STARTED,
COMPLETED
} active_status_e;
Status of channel enumeration
(return by status() method).
vmm_log log; Message service interface for
this component.
vmm_notify notify; Notification service interface.
typedef enum int unsigned {
FULL, EMPTY, PUT, GOT,
PEEKED, ACTIVATED,
ACT_STARTED, ACT_COMPLETED,
ACT_REMOVED, LOCKED,
UNLOCKED, GRABBED,
UNGRABBED, RECORDING,
PLAYBACK, PLAYBACK_DONE
} notifications_e;
Channel notifications.
Macros
`vmm_channel( channel_name )
Automatically creates a
channel called
channel_name.
Example
Basic example using a channel.
// Create the channel class using the channel macro
`vmm_channel( my_trans )
class my_driver extends vmm_xactor;
my_trans_channel chan;

task main();
// Get the next transaction from the channel
chan.get( tr );
...
endtask
endclass
class my_xactor extends vmm_xactor;
task main();
...
vmm_channel

// Put the next transaction into the channel
chan.put (tr);
endtask
endclass

class my_subenv extends `VMM_SUBENV;
my_xactor xact;
my_driver drv;

chan = new ( "my_trans_channel",
"my_trans_channel" );
xact = new ( ... );
drv = new ( ... );

// Connect the channel between the producer and consumer
xact.chan = chan;
drv.chan = chan;
...
endfunction
endclass
Example using the channel acti ve slot.
task main();
...
forever begin
...
chan.activate( tr );
...
chan.start();
...
chan.complete();
chan.remove();
end
endtask
endclass
vmm_channel
Example using TLM connections
vmm_tlm_b_transport_export #( my_driver, my_trans ) ch;
task b_transport( int id = -1, my_trans tr,
ref int delay );
...
endtask
endclass

`vmm_atomic_gen( my_trans, "Atomic Generator" )
class my_subenv extends `VMM_SUBENV;
my_trans_atomic_gen gen;
my_driver drv;

function build();
gen = new ( "My Atomic Generator", 0 );
drv = new ( this, "drv" );
// Connect the TLM export to the channel using vmm_connect
vmm_connect #(.D(my_trans))::tlm_bind(gen.out_chan,
drv.b_export, vmm_tlm::TLM_BLOCKING_PORT );
endfunction
endclass
Tips
Use a channel full size of 1 for a blocking channel.
A producer should wai t for the completion of a transaction by using its
vmm_data::wait_for( vmm_data::ENDED ) method.
To connect a channel to a TLM port or export, use vmm_connect
Gotchas
Using reconfigure() to change a channels configuration may cause
blocked threads to unblock.
Calling a channel method that requires an offset will generate an error if the
offset does not exi st.
Calling remove() when an acti ve slot is in the vmm_channel::STARTED
state will generate an error.
See also
vmm_connect, TLM Interfaces
Command Line Switches
The following are a list of useful command line switches that affect both VMM
compilation and simulation.
Compile-time command line switches
+define+VMM_12 Enables VMM 1.2
features (default)
+define+VMM_IN_PACKAGE Enables vmm.sv to be
included in a package.
+define+VMM_LOG_ANSI_COLOR Colorizes messages
based on severity (see
vmm_log).
+define+VMM_LOG_FORMAT_FILE_LINE Includes filename and line
number in all messages
(see vmm_log).
+define+VMM_NO_STR_DPI Disables string matching
using the DPI extensions.
+define+VMM_NULL_LOG_MACROS Turns off debug
messages.
+define+VMM_PARAM_CHANNEL Enables parameterized
channels (default with
VMM 1.2).
+define+VMM_POST_INCLUDE=<filename> Include file containing
customization macros to
be included after vmm.sv
+define+VMM_PRE_INCLUDE=<filename> Include file containing
customization macros to
be included before
vmm.sv
+define+VMM_REGEX_DEBUG Enables debug messages
for all methods using
regex path matching.
+define+VMM_RW_ADDR_WIDTH=<width> Set the default RAL
address width (see
Register Abstraction
Layer).
+define+VMM_SB_DS_IN_STDLIB Enables the scoreboard
integration functions (see
vmm_sb_ds).
Run-time command line switches
+vmm_break_on_phase=<phase> Breaks simulation upon
starting the gi ven phase
(see vmm_ti meline).
+vmm_break_on_timeline=<timeline> Breaks simulation upon
starting the gi ven ti meline
+vmm_channel_fill_thresh=<int> Sets the number objects
in a channel.
+vmm_force_verbosity=[ERROR|WARNING
|NORMAL|TRACE|DEBUG|VERBOSE]
Overrides message
verbosity (see
Messaging)
+vmm_gen_rtl_config Generates VMM RTL
configuration.
+vmm_log_debug Enables debug messages
(see Messaging)
+vmm_log_default=[FATAL|ERROR|
WARNING|NORMAL|TRACE|DEBUG|VERBOSE]
Sets the default message
verbosity (see
Messaging)
+vmm_log_nofatal_at_1000 Suppresses fatal
messages when more
than 1000 log instances
are created (see
Messaging)
+vmm_log_nowarn_at_200 Suppresses warning
messages when more
than 200 log instances
are created (see
Messaging)
+vmm_object_children_thresh=<int> Sets the total number of
children objects.
+vmm_object_root_thresh=<int> Sets the total number of
root objects.
+vmm_object_thresh_check Enables object threshold
checking.
+vmm_opts_file=<filename> Specifies an option file
(see vmm_opts article).
+vmm_opts+<option1>+<option2>+... Specifies run-time options
(see vmm_opts article)
+vmm_rtl_config=<prefix> Specifies prefix for RTL
configuration file(s)
(see RTL Configuration).
+vmm_test_file=<filename> Specifies filename with
list of test cases (see
vmm_simulation)
+vmm_test=<test> Specifies the test case to
run (see vmm_simulation)
+vmm_tr_verbosity=[NORMAL|TRACE|
DEBUG|VERBOSE]
Sets the transaction
debug verbosity level.

Configuration Macros
The configure_ph() method of any object deri ved from vmm_unit must pull
applicable configuration values out of the options database (see vmm_opts)
and use them to set the values of its data members. This group of convenience
macros automates much of the creation of that configure_ph method.
Where
class my_bfm extends vmm_xactor;
... // Data members of the class here
`vmm_unit_config_begin(my_bfm)
`vmm_unit_config_type(...) // one per data member
... // Additional code in configure_ph() here
`vmm_unit_config_end(my_bfm)
endclass
Macros
`vmm_unit_config_begin(
class)
Starts the definition of a
configure_ph() method. class
should be filled-in wi th the name of
the enclosing class.
`vmm_unit_config_rand_type(
name, descr,
verbosity, attr )
Automates the configuration of rand
data member name. type can be
any of boolean, int or obj. Calls
vmm_opts::get_object_type()
to scan the option database for an
option called name applicable to the
current unit instance; if found,
populates the data member name
from that option's value and disables
randomization of that member. See
below for description of other
arguments.
`vmm_unit_config_type (
name, descr,
verbosity, attr )
Automates the configuration of non-
rand data member name. type can
be any of boolean, string, int or
obj. Calls
vmm_opts::get_object_type to
scan the option database for an
option called name applicable to the
current unit instance; if found,
populates the data member name
from that option's value.
`vmm_unit_config_end(class) Ends the definition of a
configure_ph() method in the
enclosing class.
Arguments
In the current implementation, macro arguments class and _attr are unused.
However, to ensure compatibili ty with future versions of VMM it is important that
the class argument of macros `vmm_unit_config_begin/end should be
supplied with the name of the enclosing class. Argument _attr of the other
macros should be supplied with the DO_ALL value.
Arguments _descr and _verbosity are used as the doc and verbosity
arguments in a call to vmm_opts::get_object_type(). Consequently,
_descr should be a string that wi ll be reported by help and diagnostic logs
relating to the relevant option, and _verbosity should be an integer in the
range 0 to 10 indicating the minimum help verbosi ty level for which information
on this option should be printed. A higher value of _verbosity leads to less
verbose output; set it to 0 to ensure the relevant help information will appear.
Example
A class deri ved from vmm_xactor that has some configurable data members:
class custom_bfm extends vmm_xactor;

vmm_log log;
rand bit is_active;
rand int xfr_count;
string description;
constraint count_length { xfr_count inside {[8:50]};}
...
function void build_ph(); ... // and other phase methods

// No explicit implementation of configure_ph()
// it is provided by these macros:
`vmm_unit_config_begin(custom_bfm)
`vmm_config_unit_rand_boolean(is_active, \
"Enables active behavior in a custom_unit",0,DO_ALL)
`vmm_config_unit_rand_int(xfr_count, \
"Transfer count of a custom_unit", 0, DO_ALL)
`vmm_config_unit_string(description, \
"Descriptive text for a custom_unit", 2, DO_ALL)
`vmm_trace(log, "running custom_unit::configure_ph()")
`vmm_unit_config_end(custom_bfm)

... // other methods and data members

endclass : custom_bfm

In a suitable plain-text options file, specify options:
+is_active=1
+xfr_count=100@top_env:my_subenv:that_custom_bfm
+description=CustomUnitClass@%*custom_bfm*

On the command line, specify that VMM should read that options file:
vcs ... +vmm_opts_file+my_options_file.txt ...
Tips
Use randomization, or data member initialization, to provide sui table default
values for all your unit's data members, for use in the event that no
applicable option has been specified.
The `vmm_unit_config_begin/end macros essentially construct the
start (prototype) and endfunction of the uni t's configure_ph method.
Calls to the other `vmm_unit_config_* macros, and any other
procedural code that you want to appear in the configure_ph() method,
must be inserted between the begin and end macro calls.
Gotchas
Although they directly call the vmm_opts::get_object_type methods,
these macros make it i mpossible for you to inspect the is_set result from
those methods. Consequently, you must ensure that your unit's behavior is
reasonable even if no option value has been supplied. For example, you
could default each data member to an unreasonable value, test for that
value and error-out if it has not been superseded by a supplied option.
See also
vmm_opts, vmm_unit, Phases
vmm_connect
vmm_connect is a utility class to connect certain kinds of object during the
connect phase. It may be used in one of four distinct modes: to bind channel to
channel, notification to notify observer, channel to tlm port or export, or blocking
tlm port to non-blocking export or vice versa. It is recommended to use
vmm_connect to connect channels rather than passing channels as constructor
arguments since vmm_connect works regardless of whether or not the channels
to be connected have already been instantiated.
Declaration
class vmm_connect #(type T = vmm_channel,
type N = T, type D = vmm_data);
Methods
static function channel(
ref T upstream,
ref T downstream,
input string name = "",
Connects two channels.
static function notify(
N observer,
vmm_notify ntfy,
int notification_id);
Connects the specified
notification to the notify
observer.
static function tlm_bind(
vmm_channel_typed#(D) channel,
vmm_tlm_base tlm_intf,
vmm_tlm::intf_e intf,
string fname = "",
int lineno = 0);
Connects a channel to a
TLM port or export.
See vmm_tlm for e_intf
values.
static function
tlm_transport_interconnect(
vmm_tlm_base tlm_intf_port,
vmm_tlm_base tlm_intf_export,
vmm_object parent = null,
string fname = "",
int lineno = 0);
Connects a TLM blocking
transport port to a non-
blocking export and vice
versa.
See vmm_tlm for e_intf
values.

Example
`vmm_channel(mytrans)
class my_env extends vmm_group;
mytrans_channel gen_channel;
mytrans_channel drv_channel;
my_scoreboard sb;
vmm_connect
my_monitor monitor;
my_coverage cov;

function void build_ph();
... // Build components
endfunction

function void connect_ph();
vmm_connect#(.T(mytrans_channel))::channel(
gen_channel, drv_channel, "gendrvchan",
this);

vmm_connect#(.N(my_scoreboard), .D(mytrans))::notify(
sb, monitor.notify, monitor.XACTOR_STARTED);

vmm_connect#(.D(mytrans))::tlm_bind(
cov.in_chan, monitor.b_port,
vmm_tlm::TLM_BLOCKING_EXPORT);
endfunction
endclass
Tips
Always use vmm_connect within the connect_ph method.
The vmm_connect type parameters represent the following: T = channel
type, N = notification observer type, and D = transaction data type.
With the channel method, neither, one or both of the upstream and
downstream channels may already exist. If neither, a new channel wi ll be
created.
The tlm_bind method is the only way to connect a tlm port to a
vmm_channel, or a vmm_channel to a tlm export.
The tlm_transport_interconnect method inserts an adapter that is
able to perform conversion between the blocking and non-blocking
transport methods in either direction.
See vmm_tlm for TLM connection types used with vmm_connect.
Gotchas
When binding tlm port to export, vmm_connect can only be used where
one end is blocking and the other end non-blocking. To connect blocking-
to-blocking or non-blocking to non-blocking you must use the tlm_bind
method.
vmm_connect
See also
vmm_channel, vmm_notify, TLM Interfaces

vmm_consensus
The vmm_consensus class is used to determine if a test has reached its end by
checking with the registered components for an end-of-test consensus. Several
types of components can be registered with a consensus object, and specific
registration functions are provided. End-of-test status is determined as shown in
the following table:

VMM Component Consents Opposes
vmm_channel empty non-empty
vmm_notify
(registered wi th
register_
notification)
indicated not indicated
vmm_notify
(registered wi th
register_no_
notification)
not indicated indicated
sub-consensus
object
sub-consensus reached
(or forced)
sub-consensus not
reached
vmm_voter vmm_voter::consent()
vmm_voter::forced()
vmm_voter::oppose()
vmm_xactor vmm_xactor::IS_IDLE vmm_xactor::IS_BUSY
vmm_unit /
vmm_group
vmm_unit::consent()
vmm_unit::forced()
vmm_unit::force_thru()
vmm_unit::
request_consensus()
vmm_unit::oppose()

Internal to the consensus instance, vmm_voter objects are created for each
registered component. The vmm_voter class is used to indicate consent,
opposi tion, or forced consensus. If there is only one component dissenting and
it is removed (unregistered), then the consensus is immediately reached.
Normally, a consensus object only indicates that the test can finishit does not
end the test. In such case, a testbench must use a consensus object and have it
wai ted upon (wait_for_consensus()) to determine when to stop. However,
when implicit phasing is used at the top-level, the run_test phase will only
complete if a consensus in the object hierarchy is reached. Likewise, the
vmm_consensus::request_consensus() method can be used to request a
consensus of all testbench components.
Declaration
class vmm_consensus extends vmm_object;
vmm_consensus
Methods
function new(
string name,
string inst,
vmm_log log = null);
Constructor.
function void
consensus_force_thru(
vmm_consensus vote,
bit force_through = 1);
Sets the consensus
force_thru flag of all
registered voters and triggers
a new consensus.
function void forcing(
ref string who[],
ref string why[]);
Returns an array of names of
the components currently
forcing the end-of-test and an
array of strings describing the
reason.
function bit is_forced(); Indicates if the consensus is
being forced.
Returns non-zero if forced,
and 0 if not forced.
function bit is_reached(); Indicates if a consensus has
been reached.
Returns non-zero (whether
forced or not) if consensus
reached.
function void nays(
ref string who[],
ref string why[]);
components opposing end-of-
test and their reasons why.
psdisplay(
Prints out the current status of
the consensus and the
participants consensus
reasons.
prefix is prefixed to the
returned string.
function void register_channel(
vmm_channel chan);
Registers a channel as a
participant in the consensus.
function void
register_consensus(
vmm_consensus vote,
bit force_through = 0);
Registers a sub-consensus
object with the consensus
instance.
If force_through is non-
zero, then a forced sub-
consensus forces a higher-
level consensus.
vmm_consensus
function void
register_no_notification(
vmm_notify notify,
int notification);
Registers a notification as a
participant in the consensus
with reverse polarity
participation (see table above).
function void
register_notification(
vmm_notify notify,
int notification);
Registers a notification as a
function vmm_voter
register_voter(
string name);
Returns a vmm_voter
instance.
function void register_xactor(
vmm_xactor xact);
Registers a transactor as a
task request(
string why
= "No reason specified",
vmm_consensus requestor
= null);
Requests a consensus from all
opposing registered voters in
the hierarchy.
function void unregister_all(); Removes all registered
consensus participants.
function void
unregister_channel(
vmm_channel chan);
Removes the specified
channel participant from the
consensus.
function void
unregister_consensus(
vmm_consensus vote);
Removes the specified sub-
consensus participant from the
consensus.
function void
unregister_notification(
vmm_notify notify,
int notification);
notification participant from the
consensus.
function void unregister_voter(
vmm_voter voter);
Removes the specified voter
participant from the
consensus.
function void
unregister_xactor(
vmm_xactor xact);
transactor participant from the
consensus.
task wait_for_consensus(); Blocks until all participants
consent to end-of-test.
Returns i mmediately if
consensus is already reached
(or forced).
vmm_consensus
task wait_for_no_consensus(); Blocks until a consensus is
broken.
Returns i mmediately if
consensus is not already
reached.
function void yeas(
ref string who[],
ref string why[]);
components consenting to the
end-of-test and their reasons.
Methods
this component.
typedef enum int {
NEW_VOTE,
REACHED,
REQUEST
} notifications_e;
Notification enumeration.
vmm_voter
The vmm_voter class is a helper class used by vmm_consensus. It is not
intended to be extended by users, but it can be used by any object to participate
in a consensus. A vmm_voter instance is returned by calling
vmm_consensus::register_voter().
Methods
function void consent(
string why
= "No reason specified");
Consents to an end-of-test
consensus.
This method can be invoked
repeatedly to change the
reason.
function void forced(
string why
Forces an end-of-test
consensus.
The forced consensus can be
removed with consent() or
oppose().
vmm_consensus
function void oppose(
string why
Opposes an end-of-test
consensus.
This method can be invoked
repeatedly to change the
reason.
Example
Example registering a transaction as a consensus participant
apb_xactor apb_xtor;
vmm_consensus vote = new ( "xactor vote",
...

function new;
super.new ( ... );
apb_xtor = new ( ... );
...
endfunction

// Use the environments built-in consensus object
task start();
super.start();
apb_xtor.start_xactor();

this.end_vote.register_xactor( apb_xtor );
...
endtask

task wait_for_end();

end_vote.wait_for_consensus();
$display(end_vote.psdisplay("TEST END"));
endtask
endclass
vmm_consensus
Example using a vmm_voter
program test_random;

vmm_consensus vote = new ( "consensus", "vote" );

initial begin
vmm_voter v;

v = vote.register_voter("consensus voter");
...
end
endprogram
Tips
By default, a sub-consensus wi ll not force a higher-level consensus. Set
the register_consensus() methods force_through parameter to 1
to force a higher-level consensus.
The vmm_env and vmm_subenv have a bui lt-in consensus instance for
determining end-of-test status.
Gotchas
The vmm_voter is a utility class not intended to be user-extended so its
constructor is not documented.
See also
vmm_notify
vmm_data
The vmm_data class provides the basic template for VMM transaction objects.
It encapsulates the various base members and methods required for transaction
level modelling such as copy(), print(), etc., and identifiers like stream_id
or data_id. In VMM 1.2, it is extended from vmm_object and basic scenario
objects are derived from it.
Most of the vmm_datas utility methods must be overloaded and implemented in
derived classes since only a mini mal stub is provided in the base class. An
easier and more convenient approach is to use the built-in shorthand macros,
which automatically create these methods and greatly simplifies coding (see
Shorthand macros for more details). If using the class factory, then the
copy() and allocate() methods need defined as a mini mum.
Declaration
class vmm_data extends vmm_object;
Methods
function new(
vmm_log log = null,
string name = "");
Constructor.
virtual function vmm_data
allocate();
Allocates a new instance.
(Used by the VMM factory).
virtual function int unsigned
byte_pack(
ref logic [7:0] bytes[],
input int unsigned offset= 0,
input int kind = -1);
Packs the transaction object
into the array bytes[],
starting at offset.
kind may be used to select
implementation.
byte_size(
int kind = -1);
Returns the number of bytes
required to pack object.
implementation.
vmm_data
byte_unpack(
const ref logic [7:0] bytes[],
input int unsigned offset = 0,
input int len = -1,
Unpacks bytes[] into object
starting at offset for len
bytes.
If len equals -1, the maxi mum
number of bytes is unpacked.
If bytes[] array is not large
enough to unpack into the
object, then the remaining
members are set to unknown.
implementation.
virtual function bit compare(
vmm_data to,
output string diff,
Compares this instance to
object to.
Returns true if identical;
otherwise, returns first
difference in diff.
implementation.
virtual function vmm_data copy(
vmm_data to = null);
Copies instance into object
to.
If to is null, then a new
instance is returned.
virtual protected function void
copy_data(
vmm_data to);
Copies only the base class
elements into object to.
Should be called by the
copy() method
implementation of the first
extension of the vmm_data
class. Should not be otherwise
overriden..
function void display(
Prints description of object
with each line prefixed with
prefix.
do_byte_pack(
ref logic [7:0] bytes[],
Overrides the byte_pack()
methods created by the
shorthand macros.
do_byte_size(
int kind = -1);
Overrides the byte_size()
shorthand macros.
vmm_data
do_byte_unpack(
const ref logic [7:0] bytes[],
input int len = -1,
Overrides the
byte_unpack() methods
created by the shorthand
macros.
virtual function bit
do_compare(
vmm_data to,
output string diff,
Overrides the compare()
shorthand macros.
do_copy(
Overrides the copy()
shorthand macros.
do_is_valid(
bit silent = 1,
int kind = -1);
Overrides the is_valid()
shorthand macros.
do_max_byte_size(
int kind = -1);
Overrides the
max_byte_size() methods
macros.
do_psdisplay(
Overrides the psdisplay()
shorthand macros.
virtual function bit is_valid(
bit silent = 1,
int kind = -1);
Returns true if the data object
is valid based on the optional
kind argument.
If silent is true, then no
error message is reported.
virtual function bit load(
int file);
Loads data from file into
object.
max_byte_size(
int kind = -1);
Returns the maxi mum number
of bytes required to pack the
object.
Returns 0 if maxi mum size is
unknown.
psdisplay(
Returns a string description of
object.
virtual function void save(
int file);
Appends the contents of
object to file.
function vmm_log set_log(
vmm_log log);
Replaces the message service
with the specified instance.
vmm_data
Members
int data_id; Specifies the data id.
typedef enum {
DO_NOCOPY,
REFCOPY,
DO_DEEPCOPY,
HOW_TO_COPY,
DO_NOCOMPARE,
DO_REFCOMPARE,
DO_DEEPCOMPARE,
HOW_TO_COMPARE,
DO_NONE,
DO_REF,
DO_DEEP,
DO_DUMMY
} do_how_e;
Enumeration used for the
shorthand macros.
typedef enum {
DO_PRINT,
DO_COPY,
DO_COMPARE,
DO_PACK,
DO_UNPACK,
DO_ALL
} do_what_e;
Enumeration used for the
shorthand macros.
static vmm_log log; Message service instance.
Created by the shorthand
macros.
typedef enum int {
EXECUTE,
STARTED,
ENDED
} notifications_e;
vmm_notify notify; Notification object.
int scenario_id; Specify parent scenario.
int stream_id; Specifies offset of object in a
transaction stream.
Shorthand Macros
The vmm_data shorthand macros provide a way of defining transaction objects
with automatically generated psdisplay(), is_valid(), allocate(),
copy(), compare(), byte_pack(), and byte_unpack()methods that have
a default implementation.
The macros are placed between a `vmm_data_member_begin /
`vmm_data_member_end pair. Each macro has a do_what_e field, which
vmm_data
specifies the methods to automatically generate. The enumeration values can
be OR-ed together for specific methods or DO_ALL for all methods. The default
implementation for these methods can be extended or overwritten by defining a
do_psdisplay(), do_is_valid(), do_allocate(), and so on.
In addition, there is also a special macro to automatically create byte_size()
and max_byte_size() called `vmm_data_byte_size(). The first argument
represents the value returned by max_byte_size(), and the second argument
specifies what is returned by byte_size(). Another macro is the constructor
macro `vmm_data_new(). By default, `vmm_data_member_begin() wi ll
automatically create a constructor, which can be disabled by using the
constructor macro so that a custom constructor can be defined.
Begin / end macros
`vmm_data_member_begin( class )
`vmm_data_member_end( class )
Scalar data members
`vmm_data_member_scalar( name, do )
`vmm_data_member_scalar_array( name, do )
`vmm_data_member_scalar_aa_scalar( name, do )
`vmm_data_member_scalar_aa_string( name, do )
`vmm_data_member_scalar_da( name, do )
`vmm_data_member_rand_scalar( name, do )
`vmm_data_member_rand_scalar_array( name, do )
`vmm_data_member_rand_scalar_da( name, do )
`vmm_data_member_rand_scalar_aa_scalar( name, do )
`vmm_data_member_rand_scalar_aa_string( name, do )
Enumeration data members
`vmm_data_member_enum( name, do )
`vmm_data_member_enum_array( name, do )
`vmm_data_member_enum_aa_scalar( name, do )
`vmm_data_member_enum_aa_string( name, do )
`vmm_data_member_enum_da( name, do )
`vmm_data_member_rand_enum( name, do )
`vmm_data_member_rand_enum_array( name, do )
`vmm_data_member_rand_enum_da( name, do )
`vmm_data_member_rand_enum_aa_scalar( name, do )
`vmm_data_member_rand_enum_aa_string( name, do )
String data members
`vmm_data_member_string( name, do )
`vmm_data_member_string_array( name, do )
vmm_data
`vmm_data_member_string_aa_scalar( name, do )
`vmm_data_member_string_aa_string( name, do )
`vmm_data_member_string_da( name, do )
VMM data members
`vmm_data_member_vmm_data( name, do, how )
`vmm_data_member_vmm_data_array( name, do, how )
`vmm_data_member_vmm_data_aa_scalar( name, do, how )
`vmm_data_member_vmm_data_aa_string( name, do, how )
`vmm_data_member_vmm_data_da( name, do, how )
`vmm_data_member_rand_vmm_data( name, do, how ) )
`vmm_data_member_rand_vmm_data_array( name, do, how )
`vmm_data_member_rand_vmm_data_da( name, do, how )
`vmm_data_member_rand_vmm_data_aa_scalar( name, do, how )
`vmm_data_member_rand_vmm_data_aa_string( name, do, how )
Handle data members
`vmm_data_member_handle( name, do )
`vmm_data_member_handle_array( name, do )
`vmm_data_member_handle_aa_scalar( name, do )
`vmm_data_member_handle_aa_string( name, do )
`vmm_data_member_handle_da( name, do )
`vmm_data_member_rand_handle( name, do ) )
`vmm_data_member_rand_handle_array( name, do ) )
`vmm_data_member_rand_handle_da( name, do ) )
`vmm_data_member_rand_handle_aa_scalar( name, do ) )
`vmm_data_member_rand_handle_aa_string( name, do ) )
User-defined data members
`vmm_data_member_user_defined( name )
Byte sizes
`vmm_data_byte_size( max, n )
Constructor
`vmm_data_new( name )
Example
class memory_instruction extends vmm_data;
rand int data;
rand int addr;
rand enum { READ, WRITE } kind;
vmm_data
// Automate everything but the copy() function
`vmm_data_member_begin (memory_instruction)
`vmm_data_member_scalar(data, DO_ALL DO_COPY)
`vmm_data_member_scalar(addr, DO_ALL DO_COPY)
`vmm_data_member_enum(kind, DO_ALL DO_COPY)
`vmm_data_member_end (memory_instruction)

function vmm_data do_copy(vmm_data to = null);
memory_instruction tr;

if (to != null)
if ( $cast(tr, to) ) begin
`vmm_fatal(log, "Not a memory instruction!");
return null;
end
else
tr = new;

this.copy_data(tr);
tr.data_id = my_pkg::next_id++; // Unique ID
return tr;
endfunction

endclass
Example using a class factory
class usb_trans extends vmm_data;
`vmm_typename(usb_trans)

static vmm_log log = new("usb_trans", "object");
rand int data;
...

virtual function vmm_data copy(vmm_data to = null);
usb_trans tr = new(get_object_name(), get_parent());
tr.data = this.data;
...
return tr;
endfunction

virtual function vmm_data allocate();
usb_trans tr = new(get_object_name(), get_parent());
return tr;
endfunction
vmm_data
function new(string name = "",vmm_object parent = null);
super.new(log);
set_parent_object(parent);
endfunction

`vmm_class_factory(usb_trans)

endclass
Tips
Use the copy_data() function in your custom copy method to copy of
your base class data properties.
The kind argument to many of the uti lity methods provides a way of
customizing the implementation to different scenarios.
The max_byte_size() method may be useful for allocating buffers in a
verification environment.
Take advantage of the how field wi th the
`vmm_data_member_vmm_data*() macros to accomplish a deep copy
or compare.
When defining a derived vmm_data class, be sure to make any vmm_log
instances static to mini mize memory usage due to the potentially large
number of objects.
Gotchas
When creating a copy() method, remember to implement a deep copy if
needed.
When creating your own custom utility methods, do not call the parent base
class (i.e., using super()).
The constructor macro `vmm_data_new() must precede the begin macro
`vmm_data_member_begin().
See also
Shorthand Macros, vmm_object
You can also find further information on this topic at the VMM Golden Reference
Guide's companion page at http://www.doulos.com/vmm.
vmm_env
The vmm_env class extends vmm_object and is used as the top level wrapper
around all of the testbench components. Typically, it is used to instantiate
components, connect channels or TLM ports, and configure the design under
test.
The environment also controls the progress of simulation prior to the addition of
VMM 1.2 phases. It defines a number of virtual tasks and functions, which
implement the necessary mechanisms for the proper simulation flow. The virtual
run() method executes through all of the si mulation steps, though calling most
simulation steps wi ll i mplicitly execute the preceding steps. Derived classes
from vmm_env may override the simulation step methods; however, it is crucial
that the base class methods are called first using super.method().
The vmm_env defines the following si mulation steps:
VMM Simulation Steps
Simulation Step
(in order of
execution)
3

Type Implicitly Calls Main Activity
gen_cfg function -
Generate the testcase
configuration
build function gen_cfg
Build the environment
according to the
testcase configuration
hw_reset
4
task -
Perform hardware
reset operation
power_on_reset
5
task hw_reset
Power on reset
operations. Implicitly
calls hw_reset
reset_dut task
build
power_on_reset
Reset the design
under test
power_up
2
task -
Used for power-up
configuration.
cfg_dut task
reset_dut
power_up
Configure the design
according to the
testcase configuration
start task cfg_dut
Start all transactors
and generators
wait_for_end task start Wait for the end of test

3
The typical simulation steps overridden by derived classes are in bold.
4
Primarily used by RAL vmm_ral_env environments.
5
Added in VMM 1.2. Calling these methods wi ll not cause all preceding steps to
execute.
vmm_env
Simulation Step
(in order of
execution)
3

Type Implicitly Calls Main Activity
stop task wait_for_end Stop all generators
cleanup task stop
Collect remaining data
from the design and
collect coverage
statistics
report task -
Report on the success
or failure of the
simulation run

Declaration
class vmm_env extends vmm_object;
Methods
function vmm_env::new(
string name = "Verif Env");
Constructor.
virtual function void build(); Method for building the
environment.
virtual task cfg_dut(); Method for configuring the
design.
virtual task cleanup(); Method for cleanup
operations.
do_psdisplay(
User-definable method for
overriding the default
psdisplay() method
created by the vmm_env
shorthand macros.
protected virtual task
do_reset(
vmm_env::restart_e kind);
reset() method created by
the vmm_env shorthand
macros.
do_start();
start() method created by
the vmm_env shorthand
macros.
vmm_env
do_stop();
overriding the default stop()
method created by the
vmm_env shorthand macros.
do_vote();
end_vote() method created
by the vmm_env shorthand
macros.
gen_cfg();
Method for generating the
testcase configuration.
virtual task hw_reset(); Method to perform hardware
reset.
virtual task power_on_reset(); Method for power on reset
operations.
virtual task power_up(); Method for power up
configuration.
psdisplay(
Function to print out
environment information.
virtual task report(); Method for reporting the
success or failure of a test.
virtual task reset_dut(); Method for reseting the design
under test.
reset_env(
restart_e kind);
Method for reseting the
environment.
virtual task restart(
bit reconfig = 0);
Resets the environment,
restores the RNG state, and
calls the cleanup step.
If reconfig = 1, then it kills
all sub-threads.
virtual task restart_test(); Resets the environment and
restarts the build step.
task run(); Main method that starts the
simulation steps.
virtual task start(); Method called at the start of
simulation.
virtual task stop(); Method called to terminate
environment cleanly and
collect design information.
vmm_env
virtual task wait_for_end(); Method called to wai t for the
end of the test.
Members
typedef enum {
DO_PRINT,
DO_START,
DO_STOP,
DO_RESET,
DO_VOTE,
DO_ALL } do_what_e;
Macro actions enumeration.
vmm_vote end_vote; End-of-test consensus object
that can be used by an
extended wait_for_end()
method.
this component.
GEN_CFG,
BUILD,
RESET_DUT,
CFG_DUT,
START,
RESTART,
WAIT_FOR_END,
STOP,
CLEANUP,
REPORT,
RESTARTED } notifications_e;
Predefined notifications used
to indicate the progress of
simulation.
HARD,
SOFT,
FIRM } restart_e;
Enumeration of reset types
(used by reset_env() and
do_reset()).

Shorthand Macros
The vmm_env shorthand macros are a way of defining an environment wi th
automatically generated psdisplay(), start(), stop(), reset(), and
vote()
6
methods that have a default implementation. The macros are placed
between a `vmm_env_member_begin/`vmm_env_member_end pair. Each
macro has a do_what_e field, which specifies the methods to automatically

6
Automatically registers a member with the vmm_env::end_vote consensus
instance.
vmm_env
generate. The enumeration values can be OR-ed together for specific methods
or DO_ALL for all methods. The default implementation for these methods can
be extended or overwritten by defining a do_psdisplay(), do_start(),
do_stop(), do_reset(), or do_vote() method, respecti vely.

Begin / end macros
`vmm_env_member_begin( class )
`vmm_env_member_end ( class )
Scalar data members
`vmm_env_member_scalar( name, do )
`vmm_env_member_scalar_array( name, do )
`vmm_env_member_scalar_aa_scalar( name, do )
`vmm_env_member_scalar_aa_string( name, do )
`vmm_env_member_enum( name, do )
`vmm_env_member_enum_array(name, do )
`vmm_env_member_enum_aa_scalar(name, do )
`vmm_env_member_enum_aa_string( name, do )
String data members
`vmm_env_member_string( name, do )
`vmm_env_member_string_array( name, do )
`vmm_env_member_string_aa_scalar( name, do )
`vmm_env_member_string_aa_string( name, do )
VMM data members
`vmm_env_member_vmm_data( name, do )
`vmm_env_member_vmm_data_array( name, do )
`vmm_env_member_vmm_data_aa_scalar( name, do )
`vmm_env_member_vmm_data_aa_string( name, do )
Channel data members
`vmm_env_member_channel( name, do )
vmm_env
`vmm_env_member_channel_array( name, do )
`vmm_env_member_channel_aa_scalar( name, do )
`vmm_env_member_channel_aa_string( name, do )
Transactor data members
`vmm_env_member_xactor( name, do )
`vmm_env_member_xactor_array( name, do )
`vmm_env_member_xactor_aa_scalar( name, do )
`vmm_env_member_xactor_aa_string( name, do )
Sub-environment data members
`vmm_env_member_subenv( name, do )
`vmm_env_member_subenv_array( name, do )
`vmm_env_member_subenv_aa_scalar( name, do )
`vmm_env_member_subenv_aa_string( name, do)
`vmm_env_member_user_defined( name )
Example
virtual dut_intf.tb dut_if;

mon_sb_chan m_sb_ch;
my_scoreboard sb;
my_subenv subenv;

function new ( string name,
virtual dut_intf.tb dut_if = null );
super.new ( name );
this.dut_if = dut_if;
endfunction : new

super.build(); // Must call parent method!
m_sb_ch = new ( "m_sb_ch", "m_sb_ch" );
sb = new ( "sb", m_sb_ch );
subenv = new ( "subenv", dut_if, m_sb_ch );
vmm_env
sb.build();
subenv.build();
endfunction : build

task start();
super.start(); // Call parent method!
sb.start();
subenv.start();
endtask : start

task wait_for_end();
subenv.wait_for_end();
endtask : wait_for_end

endclass : my_env

module top_tb;
ìnclude "vmm.sv"

dut_intf d_intf (); // Instantiate the interface
DUT dut_i( .* ); // Instantiate the DUT

initial begin
my_env env = new ( "my_env", d_intf.tb );

env.gen_cfg(); // Generation cfg
env.build(); // Build everything

env.run(); // Run everything
end
endmodule : top_tb
Tips
When overloading a si mulation step, always use super to call the base
class method.
Calling the run() method on the environment will kick off all the
simulation steps, but the order that they execute for each of the
components can be controlled manually. For example, suppose the
components need to be bui lt in a particular order. The build() method
can be called in the order required on the indi vidual components, and then
the run() method called on the environment.
vmm_env
Gotchas
The gen_cfg, build, restart_dut, or cfg_dut steps cannot be run
after a soft restart (see restart step) executes.
A soft restart (restart()) cannot be called unless the run step first
executes.
See also
vmm_xactor
Factory
The VMM class factory provides an object-oriented way of replacing transactors,
transactions, scenarios, and test cases with different forms wi thout testbench
modification.
It is recommended that the VMM Factory be used primarily for replacing the
factory instances in generators. Testbench functionality should be extended
using callbacks in preference to replacing testbench components using the
factory.
In VMM, each class can be configured to have its own factory. The class
factories can be swapped with new factory instances that create different forms
of the class objects. For example, suppose an atomic generator uses a default
transaction type, but different random constraints are needed for a transaction
object. An extended transaction class can be created using the new constraints,
and then a factory instance for the new type swapped in for the original
transaction type. Subsequent calls to the factory then generate the new class
type wi th the new random constraints.
Methods
static function classname
classname::this_type();
Returns an instance of
classname type.
static function classname
classname::create_instance(
vmm_object parent,
string name,
string fname = "",
int lineno = 0);
Creates an instance of
classname. Also creates a
factory instance if none has
been previously specified.
The new classname instance
is created by calling
classname::allocate()or
classname::copy() on the
factory instance specified by
the override_with_new() or
override_with_copy() method.
static function void
classname::override_with_new(
string name,
classname factory,
vmm_log log,
string fname = "",
int lineno = 0);
Set the class instance to use
by the factory. Calls the
classname::allocate() method.
classname::override_with_copy(
string name,
classname factory,
vmm_log log,
string fname = "",
int lineno = 0);
Set the class instance to use
by the factory. Calls the
classname::copy() method.
Factory
Modeling for a factory
In VMM, each class can optionally have its own factory. By default, objects
have no factory instance, which allows for backwards compatibi lity with older
testbenches. To create a factory instance, an object or unit needs to provide the
following:
(1) Use `vmm_typename(classname) this macro creates the
get_typename() function used by the factory methods.
(2) General purpose constructor, new().
(3) New object creation method, allocate().
(4) New object copy method, copy().
(5) Use `vmm_class_factory(classname).
The VMM data member macros automatically provide a constructor,
allocate() and copy() methods. However, any class can be set up for a
factory by implementing the fi ve features above. For example,
class my_trans extends vmm_object;

// (1) Typename macro
`vmm_typename(my_trans)
...
// (2) General purpose constructor
function new (string name = "",
super.new ( parent, name );
endfunction

// (3) Allocate() method
virtual function vmm_object allocate();
my_trans it;
it = new ( this.get_object_name,
get_parent_object());
allocate = it;
endfunction
Factory
// (4) Copy() method
virtual function vmm_object copy();
my_trans it;
it = new this;
copy = it;
endfunction

// (5) Factory macro
`vmm_class_factory ( my_trans )

endclass
Overriding instances and types
With the above elements in place, a unit can create an object in its bui ld phase
using the static method classname::create_instance() automatically
created by the factory macro. Subsequently, the factory instance can be
replaced by a higher level uni t or executing test using
classname::override_with_new() or
classname::override_with_copy().

The override_with_new() factory instance calls the allocate() method
when generating a class object. The override_with_copy() factory
instance calls the copy() method when generating a class object.
Test cases do not execute unti l after the environment has been constructed, so
tests can only use factories to replace dynamically created objects in the
transaction generators. Therefore, VMM recommends that test cases use
callbacks to change the behavior of testbench components. If, however, only
one test will be called for a simulation (i.e., no test concatenation), then the pre-
build method, vmm_test::set_config(), can be used to set factory
instances in the testbench environment.
Here is an example of calling a factory instance:
my_trans tr;
...
virtual task build_ph();
tr = my_trans::create_instance ( this, "my_trans1" );
...
endtask
endclass
Factory
Example
Using the factory with data objects
program P;
ìnclude "vmm.sv"
// Change the factory instance used to create data objects
class my_trans extends vmm_data;
`vmm_typename ( my_trans )
rand logic [31:0] data;
rand logic [9:0] addr;
rand enum_t rdwr;

// Use data macros to create new(), allocate(), and copy()
`vmm_data_member_begin ( my_trans )
`vmm_data_member_scalar ( data, DO_ALL )
`vmm_data_member_scalar ( addr, DO_ALL )
`vmm_data_member_enum ( rdwr, DO_ALL )
`vmm_data_member_end ( my_trans )

// Factory macro
`vmm_class_factory ( my_trans )
endclass

// Modified transaction for IO address range
class my_io_trans extends my_trans;
`vmm_typename ( my_io_trans )
contraint io_range { addr > h7FFF };

// Factory macro
`vmm_class_factory ( my_io_trans )
endclass

`vmm_typename ( my_xactor )
my_trans tr; // Base transaction type
...
virtual task build_ph();
tr = my_trans::create_instance ( this,
"my_trans", `__FILE__, `__LINE__ );
...
endtask
endclass

Factory
class test1 extends vmm_test;
`vmm_typename ( test1 )
my_io_trans tr;

virtual function void start_of_sim_ph();
// Have factory use allocate() method
my_trans::override_by_new ( "@env:gen0",
my_io_trans::this_type );

// Have factory use copy() method
my_trans::override_by_copy ( "@env:gen1,
tr );
endfunction
endclass

test1 t = new( "tests1" );
initial vmm_simulation::run_tests();

endprogram
Using the factory with parameterized classes
class my_trans #(type T = int) extends vmm_object;
rand T data;
...
`vmm_class_factory ( my_trans#(T) )
endclass

class my_io_trans #(type T = byte) extends my_trans #(T);
...
`vmm_class_factory ( my_io_trans#(T) )
endclass

typedef my_trans#(int) my_trans_i;
typedef my_io_trans#(byte) my_io_trans_b;

...
virtual task main();
tr = my_trans_i::create_instance( this,"my_trans" );
...
endfunction
endclass

Factory
initial begin
...
my_trans_i::override_by_new ( "@%*",
my_io_trans_b::this_type);
end
Tips
For a class, the most recently registered factory instance (specified by
override_by_new() or override_by_copy()) is used.
Each class has a static this_type() method, which is very useful for
registering new class factories.
The `__FILE__ and `__LINE__ are convenient SystemVerilog pre-
processor directives to use with create_instance(),
override_by_new(), and override_by_copy().
When specifying the instance name using the factory functions, a match
pattern or regular expression can be used.
Gotchas
If using factories to replace testbench instances, tests can only use the
factory to modify the testbench structure by using the
vmm_test::set_config() method, but this method is not called if more
than one test is specified to run (i.e., test concatenation).
Calls to an extended classs override_* methods do not affect
subsequent calls to its base classs create_instance method.
See also
Phases
vmm_group
The vmm_group class is used to create environments and sub-environments
with implicit phasing. The vmm_unit class serves as the base class for all
implicitly phased components; vmm_group extends vmm_unit by providing
callback capability for extending testbench component functionali ty. These
callbacks are provided by the vmm_group_callbacks class.
For implicit phasing to occur, it is important to remember to replace the vmm_env
and any vmm_subenv with vmm_group. Transactors may also use
vmm_group, but vmm_xactor is still recommend instead since it also derives
from vmm_unit, provides callbacks, and provides both i mplicit and explicit
phasing.
Declaration
class vmm_group extends vmm_unit;
Methods
function new(
string name = "",
string inst = "",
Constructor.
function void append_callback(
vmm_group_callbacks cb);
Adds callback to end of the
callback list.
function void prepend_callback(
Adds callback to the
beginning of the callback
list.
function void unregister_callback(
Unregisters the specified
callback.
vmm_group_callbacks
The vmm_group_callbacks class can be used to encapsulate functions used
in a groups implicit phases. The `vmm_callback() macro is used to
instantiate the callback and invoke the callback methods. See the examples
below for the typical usage.
Declaration
virtual class vmm_group_callbacks;
Example
class memoryload_cb extends vmm_group_callbacks;
function void preload_memory();
vmm_group
// Load in memory data
...
endfunction
endclass

class my_env extends vmm_group;
my_subenv m_sub;
my_mon m_mon;
...

m_sub = new( ... );
m_mon = new( ... );
...
endfunction : build_ph

function void configure_ph();
`vmm_callback( memoryload_cb, preload_memory());
endfunction

endclass
Tips
A vmm_group contains a consensus member (from vmm_unit) that
implicitly consents to the end of test. Each vmm_group object is registered
with their parents consensus object, implicitly creating a hierarchy of
consensus.
Use a vmm_group instead of vmm_env or vmm_subenv to create an
implicitly phased environment or sub-environment, respecti vely.
Explicitly phased transactors or sub-environments can be used within a
vmm_group as well. Use the implicit phases to invoke the components
explicit phases (e.g., start_xactor(), stop_xactor(),
configured(), etc.).
See also
vmm_unit, Phases
vmm_log
The vmm_log class defines the message service mechanism in VMM. By
default, VMM components and objects include a log instance for controlling and
issuing messages. Messages can be of different types and severities, and
filtered based on user-defined criteria. The verbosity level of messages can be
set on the command line to control which messages are issued. In addition,
message watchpoints, catchers, callbacks, and modifiers can be installed with a
message service to affect message behavior. See the article on Messaging for
more information.
Message services can be logically arranged hierarchically. The hierarchy is
defined by the under argument to the constructor or using methods like
is_above() or is_not_above(). The message services are automatically
arranged hierarchically between parent and child vmm_objects. Once the
hierarchy is defined, methods like reset() and for_each() can be used to
iterate through the instances. Likewise, the recurse argument to many of the
vmm_log functions applies the methods functionality hierarchically to all sub-
instances.
Declaration
class vmm_log;
Methods
function new(
string name,
string inst,
vmm_log under = null);
The under argument places
the message service
hierarchically underneath the
specified message service
instance.
add_watchpoint(
int watchpoint_id,
string name = "",
string inst = "",
bit recurse = 0);
Adds the watchpoint
watchpoint_id to the
message service.
The recurse option adds the
watchpoint to any message
service hierarchically
underneath.
append_callback(
vmm_log_callbacks cb);
Adds the specified callback to
the message service.
function int catch(
vmm_log_catcher catcher,
string name = "",
string inst = "",
bit recurse = 0,
int typs = ALL_TYPS,
int severity = ALL_SEVS,
string text = "");
Adds a message catcher to
the message service. Catches
message of the specified type,
severity, or text string from the
specified component instance.
By default without options,
catches all messages.
vmm_log
virtual function vmm_log copy(
vmm_log to = null);
Returns a copy of the
message service instance.
virtual function int
create_watchpoint(
string text = "",
logic issued = 1'bx);
Creates a watchpoint for the
specified type, severity, or
text.
Returns a watchpoint_id to
be used by the
add_watchpoint() method.
issued specifies whether the
watchpoint is triggered when
the message is physically
issued or not.
disable_types(
int typs,
string name = "",
string inst = "",
bit recursive = 0);
Indicates the message types
to disable for the message
service specified by name and
inst.
If the name or inst name is
embedded between forward
slashes (/), then it is treated
as a regular expression. If it
starts wi th a '@', it is treated
as a match pattern.
The recursive option
disables types in all message
services hierarchically
underneath.
virtual function void display(
Displays message service
information for this and all
message service instances
hierarchically underneath,
including message modifiers.
enable_types(
int typs,
string name = "",
string inst = "",
bit recursive = 0);
Indicates the message types
to enable for the message
service specified by name and
inst.
If the name or inst name is
embedded between forward
slashes (/), then it is treated
as a regular expression. If it
starts wi th a '@', it is treated
as a match pattern.
The recursive option
enables types in all message
services hierarchically
underneath.
vmm_log
end_msg();
Terminates and issues the
current message.
function vmm_log for_each(); Returns a reference to the
next message service
interface as specified by the
last call to reset().
get_instance();
Returns the message service
instance name.
get_message_count(
string name = "",
string inst = "",
bit recurse = 0);
Returns the number of
messages issued of the
specified severity.
The recurse option includes
all message services
hierarchically underneath.
Severity types can be
combined together using
bitwise-or or addition
operators to sum up multiple
message types.
get_name();
Returns the name of the
message service instance.
function int get_verbosity(); Returns the minimum severity
level of messages to display.
virtual function void is_above(
vmm_log log);
Specifies that the message
service is hierarchically above
the specified vmm_log
instance.
Not needed if specified
appropriately when
constructed.
is_not_above(
vmm_log log);
Removes the message service
from under the specified
vmm_log instance.
virtual function void kill(); Removes all internal
references to this message
service in preparation for
garbage collection.
virtual function void list(
string name = "/./",
string inst = "/./",
bit recurse = 0);
Lists all the message services
that match the specified
instance.
The recurse option specifies
all message services under
the matching services.
vmm_log
log_start(
int file,
string name = "",
string inst = "",
bit recurse = 0);
Appends issued messages to
a the file specified by the file
descriptor file.
The file descriptor must be a
valid integer value returned
from $fopen().
virtual function void log_stop(
int file,
string name = "",
string inst = "",
bit recurse = 0);
Stops issuing messages to the
specified file descriptor file.
The file descriptor must be a
valid integer value as returned
from $fopen().
If file is 0, then all messages
to STDOUT (simulator console)
will be stopped. If -1, then all
appending to files is stopped
except to STDOUT.
virtual function int modify(
string name = "",
string inst = "",
bit recursive = 0,
int typ = ALL_TYPS,
string text = "",
int new_typ = UNCHANGED,
int new_severity = UNCHANGED,
int handling = UNCHANGED);
Modifies the message service
to use the new type, severity,
or simulation handling.
By default, affects all
messages unless a type,
severity, text string, or
instance name is specified as
a filter.
The recurse option applies
the modification to all
message services
prepend_callback(
Prepends the specified
message callback faade to
the message service.
psdisplay(
Returns a string displaying the
message service information
for this and all message
service instances
hierarchically underneath,
including message modifiers.
remove_watchpoint(
int watchpoint_id = -1,
string name = "",
string inst = "",
bit recurse = 0);
watchpoint_id.
The recurse option applies
the modification to all
message services
vmm_log
virtual function void report(
bit recurse = 0);
Returns a failure message if
the message service has
issued an error or fatal
message.
The recurse option specifies
messages services
The message text is specified
by the vmm_log_format::
pass_or_fail() method.
function void reset(
bit recurse = 0);
Resets the message service
iterator for this instance, and
initializes it to the specified
name and instance name.
The recurse option includes
all message services
Use in conjuction with the
for_each() method.
virtual function vmm_log_format
set_format(
vmm_log_format fmt);
Sets the message formatting
to use the specified
vmm_log_format instance.
set_instance(
string inst);
Sets the instance name for
this message service.
virtual function void set_name(
string name);
Sets the name for this
message service.
set_sev_image(
int severity,
string image);
Replaces the string image
used to display the specified
severity messages.
set_typ_image(
int typ,
string image);
Replaces the string image
used to display the specified
message types.
set_verbosity(
int severity,
string name = "",
string inst = "",
bit recursive = 0);
Sets the minimum severity
level of messages to issue.
vmm_log
virtual function bit start_msg(
int typ,
int severity = DEFAULT_SEV
ìfdef VMM_LOG_FORMAT_FILE_LINE
, string fname = "",
int line = -1
èndif);
Sets up the message service
to issue a message.
Additional fname and line
arguments are added when
the
VMM_LOG_FORMAT_FILE_LI
NE is specified.
stop_after_n_errors(
int n);
Stops simulation after the
specified number of error
messages.
A zero or negati ve value
indicates no maxi mum.
By default, the message error
limi t is set to 10.
virtual function bit text(
string msg = "");
Adds the text string to the
issued message.
function bit uncatch(
int catcher_id);
Removes a specified message
catcher from this message
service.
function void uncatch_all(); Removes all message
catchers from this message
service.
virtual function void unmodify(
int modification_id = -1,
string name = "",
string inst = "",
bit recursive = 0);
Removes a specific message
modifier from the message
service.
unregister_callback(
message callback from the
message service.
function void
use_hier_inst_name();
Configures the message
service to use hierarchial
names using dot-notation.
function void
use_orig_inst_name();
Configures the message
service to use the normal flat
instance names.
function bit
uses_hier_inst_name();
Returns TRUE if hierarical
instance names are in use.
vmm_log
virtual task wait_for_msg(
string name = "",
string inst = "",
bit recurse = 0,
string text = "",
logic issued = 1'bx,
ref vmm_log_msg msg);
Creates and waits for a one-
time message watchpoint of
the specific type, severity, or
text pattern.
issued specifies if the
watchpoint is triggered
whether the message is
physically issued or not.
A message descriptor is
returned for the message that
triggers the watchpoint.
virtual task
wait_for_watchpoint(
int watchpoint_id,
ref vmm_log_msg msg);
Waits for the specific
watchpoint to trigger.
A message descriptor is
returned for the message that
triggers the watchpoint.
Members
typedef enum int {
FAILURE_TYP,
NOTE_TYP,
DEBUG_TYP,
REPORT_TYP,
NOTIFY_TYP,
TIMING_TYP,
XHANDLING_TYP,
PROTOCOL_TYP,
TRANSACTION_TYP,
COMMAND_TYP,
CYCLE_TYP,
USER_TYP_0,
USER_TYP_1,
USER_TYP_2,
INTERNAL_TYP,
DEFAULT_TYP,
ALL_TYPS
} types_e;
Message types enumeration.
vmm_log
typedef enum int {
FATAL_SEV,
ERROR_SEV,
WARNING_SEV,
NORMAL_SEV,
TRACE_SEV,
DEBUG_SEV,
VERBOSE_SEV,
HIDDEN_SEV,
IGNORE_SEV,
DEFAULT_SEV,
ALL_SEVS
} severities_e;
Message severity
enumeration.
typedef enum int {
CONTINUE,
COUNT_ERROR,
DEBUGGER,
DUMP_STACK,
STOP_PROMPT,
ABORT_SIM,
IGNORE,
DEFAULT_HANDLING
} handling_e;
Message handling
enumeration.
Macros
VMM_LOG_FORMAT_FILE_LINE If defined, causes messages
to print the file name and line
number.
Shorthand Macros
Many shorthand macros exists to simplify the writing of messages so that the
message type and severity are automatically specified. For example, to issue an
error message, the `vmm_error macro simplifies the message creation:
`vmm_error(log, "Actual not equal to expected!");
For a complete list of macros, see the section Creating Messages and Using
Macros in the Messaging article.
vmm_log
Example
program test1;
initial begin
my_env env = new ( ... );
env.log.start_msg(vmm_log::DEBUG_TYP,
vmm_log::DEFAULT_SEV);
env.log.text("Starting test case 1 ...");
env.log.end_msg();
env.build();
...
env.log.start_msg(vmm_log::DEBUG_TYP,
vmm_log::DEFAULT_SEV);
env.log.text("Finishing test case ...");
env.log.end_msg();
end
endprogram

program test2;
initial begin
...
env.log.reset();

for ( vmm_log log = env.log.for_each(); log != null;
log = env.log.for_each() ) begin
// Print out the number of messages issued
`vmm_note( env.log, $psprintf(
"Number of messages for %s = %d",
env.log.get_name,
env.log.get_message_count()));
end
end
endprogram
Tips
Message types and severities can be combined together using the bi twise-
or or addition operators.
Specify +define+VMM_LOG_FORMAT_FILE_LINE to automatically include
file and line information with all issued messages.
Use the shorthand macros like `vmm_note, `vmm_error, etc. to simplify
the issuing messages.
vmm_log
Default colors for fatal, error, and warning messages can be automatically
selected by using +define+VMM_LOG_ANSI_COLOR. Messages can be
custom color coded by specifying the ANSI escape characters wi th the
set_sev_image() or set_typ_image() methods. For example,

log.set_sev_image( vmm_log::FATAL_SEV,
"\033[41m*FATAL*\033[0m");
Gotchas
A warning is issued when attempting to unregister a callback that has not
been registered, or adding a callback more than once.
When copying a vmm_log instance using copy(), the message service
configuration is copied except for the hierarchal relationship information.
Specifying a new file with log_start() does not stop messages from
being appended to the files previously specified.
Messages issued using $display() may appear out-of-order with
messages from the message service since messages are only flushed
when end_msg() is called.
See also
Messaging, vmm_log_callbacks, vmm_log_catcher, vmm_log_format,
vmm_log_msg
vmm_log_callbacks
Message callbacks are installed with the VMM message service and invoked
when certain message handling actions occur. For example, when a message
has the handling of type ABORT, the pre_abort() and pre_finish()
callback methods are called. By default, the callback methods are declared as
empty functions. When creating a callback, these methods are overloaded in
the extended class.
Callbacks are added to the message service as a whole (not indi vidually to a
particular instance) by using vmm_log::append_callback() or
vmm_log::prepend_callback(). Conversely, they are removed from a
message service by calling vmm_log::unregister_callback().
Callbacks are invoked for the following message handling types:

Message Handling Type Callback method
ABORT
COUNT_ERROR
pre_abort()
pre_finish()
STOP_PROMPT pre_stop()
DEBUGGER
DUMP_STACK
pre_debug()

See the article on Messaging for more information on message handling and
how callbacks fit into the message issuing flow.
Declaration
class vmm_log_callbacks;
Methods
virtual function void pre_abort(
vmm_log log);
Callback method invoked
when a message is
encountered wi th a
message handling of ABORT
or COUNT_ERROR and the
error limit has been
reached.
virtual function void pre_debug(
vmm_log log);
when a message is
encountered wi th a
message handling of
DEBUGGER or DUMP_STACK.
vmm_log_callbacks
virtual function void pre_finish(
vmm_log log,
ref bit finished);
after the pre_abort()
method and before
$finish.
If finished equals 1, then
vmm_log::report and
$finish will not be called.
virtual function void pre_stop(
vmm_log log);
when a message is
encountered wi th a
message handling of
STOP_PROMPT.
Example
class my_cb extends vmm_log_callbacks;
vmm_consensus end_vote; // Synchronize end of sim

virtual function void pre_debug(vmm_log log);
`vmm_note(log,
"Simulation is stopping for debug...");

// Prepare to stop si mulation
`vmm_note(log,
"Saving assertion coverage information... ");
$coverage_save(SV_COV_ASSERTION, "debug.cov");
endfunction

// Callback that delays finishing until everything is one
virtual function void pre_finish(vmm_log log,
ref bit finished);
fork
begin
end_vote.wait_for_consensus();
log.report; // Report si mulation status
$finish;
end
join_none

finished = 1; // Tell the message service to not call $finish
endfunction
endclass

vmm_log_callbacks
function new();
super.new(...);
my_cb cb = new();
cb.end_vote = this.end_vote;
this.log.append_callback( cb );
endfunction
endclass
Tips
Use pre_finish() to delay the finishing of simulation once an abort
condition occurs.
The vmm_log input can be used to issue further messages once inside the
callback method.
Gotchas
Setting the finished argument to 1 inside pre_finish() places the
burden of calling $finish on the user.
See also
Messaging, vmm_log
vmm_log_catcher
The vmm_log_catcher class is used for handling messages and deciding if the
messages should be issued or ignored. A message catcher defines one
overloadable function: caught(), and two utili ty functions: throw() and
issue(). When a message is caught, it is passed into the caught() method.
The message is then handled by the catcher, which can modify the message or
use it as a trigger to perform other actions. If the message needs to be issued,
then the catcher must pass it on to the issue() method or it will be ignored. If
a catcher wishes to pass it on for further handling, then it can pass it into the
throw() method.
Message catchers work in conjunction wi th the VMM message service. The
vmm_log::catch() method installs a message catcher for specific message
types, text patterns, path names, or severities. Message catchers are
uninstalled by either vmm_log::uncatch() or vmm_log::uncatch_all().
See the article on Messaging for more information.
Declaration
class vmm_log_catcher;
Methods
virtual function void caught(
vmm_log_msg msg);
Method called to handle a
message.
issue(
vmm_log_msg msg);
Issues a message inside the
caught()method.
throw(
vmm_log_msg msg);
Throws the message to other
installed message catchers
from inside the
caught()method.
Tip
Format setting should be done in the top-level environment.
Example
class error_catcher extends vmm_log_catcher;

// Modifies the message severity when a testbench injected error message
// is detected. (Note, the text message is searched using vmm_log::catch()
// so it does not need to be done in the caught() method).
vmm_log_catcher
virtual function void caught( vmm_log_msg msg );
msg.effective_severity = vmm_log::WARNING_SEV;
issue(msg);
endfunction
endclass

program testcase;

initial
begin
int catcher_id;
error_catcher catcher = new();


// Install the message catcher to catch the error injected messages.
catcher_id = env.log.catch(catcher,
.text("/Error injected/"));
...
end

endprogram
Tips
Simply define an empty caught() method to ignore a message.
A message is caught by the first catcher that can handle the message. The
message catchers are considered in the reverse order that they are
installed; in other words, the last installed catcher is considered first.
Gotchas
Message watchpoints are triggered after message catchers. If a message
is modified in a catcher, it may trigger a subsequent watchpoint.
See also
Messaging, vmm_log, vmm_log_msg
vmm_log_format
The vmm_log_format class is used by the message service to format a
message string. The format_msg() and continue_msg() are called
whenever messages are issued. The abort_on_error() and
pass_or_fail() methods are called upon aborting or ending si mulation. To
change the default way messages are formatted, simply override the
format_msg() or continue_msg() methods.
Declaration
class vmm_log_format;
Methods
abort_on_error(
int count,
int limit);
Returns a string describing the
cause of simulation aborting.
Called when the error limit is
reached.
continue_msg(
string name,
string inst,
string msg_typ,
string severity,
string fname,
int line,
èndif
ref string lines[$]);
Returns a formatted string of a
message as specified by the
inputs for the
vmm_log::text() or
vmm_log::end_msg()
methods.
format_msg(
string name,
string inst,
string msg_typ,
string severity,
string fname,
int line,
èndif
Returns a formated string of a
message as specified by the
inputs when a message is
started with
vmm_log::start_msg().
vmm_log_format
pass_or_fail(
bit pass,
string name,
string inst,
int fatals,
int errors,
int warnings,
int dem_errs,
int dem_warns);
Returns a formated pass or fail
string for the end of simulation
based on the specified inputs.
Arguments fatals, errors,
and warnings indicate the
number of different severity
messages issued.
Arguments dem_errs and
dem_warns indicate the
number error or warning
messages demoted,
respecti vely.
Example
Change the default way that messages are formatted
class my_log_fmt extends vmm_log_format;
function string format_msg(
string name = "",
string instance = "",
string msg_type,
string severity,
// Append the lines to the formatted string
for(int i = 0; i < lines.size; i++)
format_msg = { format_msg,
$psprintf( "#%0t [%0s] (%s.%s): %s\n",
$time, severity, name, instance, lines[i] ) };
endfunction : format_msg
endclass

my_log_fmt my_fmt = new();

function new();
this.log.set_format( my_fmt );
...
endfunction
...
endclass
See also
Messaging, vmm_log
vmm_log_msg
A vmm_log_msg instance is used to describe a message that was issued by the
message service. It is returned by the vmm_log::wait_for_watchpoint()
and vmm_log::wait_for_msg() methods upon a watchpoint trigger.
Likewise, it is used by the vmm_log_catcher for catching, throwing, and
issuing messages.
Declaration
class vmm_log_msg;
Members
int effective_severity; Severity of the message after any
modifiers.
int effective_typ; Type of the message after any
modifiers.
string fname; Specifies the filename the message
is issued from if
VMM_LOG_FORMAT_FILE_LINE is
defined.
int handling; The message handling used on the
message.
bit invalid; Set if message is not issued.
logic issued; Indicates if the message has been
issued.
int line; Specifies the line the message is
issued from if
VMM_LOG_FORMAT_FILE_LINE is
defined.
vmm_log log; Messaging service instance
int original_severity; Severity of message when the
message was created.
int original_typ; Type of message when the
message was created.
string text[$]; Text of the message.
time timestamp; Simulation ti me when the message
was issued.

vmm_log_msg
Example
fork
begin
vmm_log_msg msg;
env.log.wait_for_msg(.text("Monitor ABC"),
.msg(msg));

$display("Triggered on monitor ABC message:"
foreach ( msg.text[i] )
$display( msg.text[i] );
end
join_none
See also
Messaging, vmm_log, vmm_log_catcher
Messaging
The VMM messaging service is a very flexible and extensible logging facility.
Messages are assigned a type and severity, which can be filtered by setting the
verbosity level or acted upon by the message handler.
Messages can also be acted upon by message modifiers. Messages modifiers
can change a messages type, severity, or handling. For further message
modifications, a message catcher can be defined to act upon the message.
The message facility also provides a means to watch for messages called
watchpoints. Watchpoints trigger on matched messages, which are then
passed back to waiting processes.
The messaging service provides hooks for user-defined message handling.
Messages are defined with default handling behavi or that can be changed with a
function call or further extended wi th message callbacks. Message callbacks
trigger upon certain handler actions and provide reacti ve control over simulation
execution based on testbench messages.
Message Types & Severities
VMM messages have both a type and severity. The message types are defined
as follows:
FAILURE_TYP Error detected.
NOTE_TYP Normal message.
DEBUG_TYP Debug or diagnositic message.
(Used by `vmm_debug() macro).
REPORT_TYP Available for transactors.
(Used by `vmm_report() macro).
TIMING_TYP Ti ming error message.
XHANDLING_TYP Unknown / high impedance detected.
PROTOCOL_TYP Available for transactors.
(Used by `vmm_protocol() macro).
TRANSACTION_TYP Available for transactors. (Used by
`vmm_transaction() macro).
COMMAND_TYP Available for transactors.
(Used by `vmm_command() macro).
CYCLE_TYP Available for transactors.
(Used by `vmm_cycle() macro).
USER_TYP_0 User available type.

Messaging
The VMM message severities are defined as:

NORMAL_SEV Normal message.
WARNING_SEV Warning message.
ERROR_SEV Error message.
Simulation continues.
FATAL_SEV Fatal error message.
Simulation will be aborted.
TRACE_SEV Internal information message.
DEBUG_SEV Debug or diagnositic message.
VERBOSE_SEV Detai led information not usually
issued.
IGNORE_SEV Ignore message. Message not
issued.

Since the message type are severity enumerations are defined as one-hot
values, multiple types and severities can be combined together by either a
bitwise-OR or addi tion operation.
Message Issuing
Whether or not a message is issued during simulation is determined by the
simulations verbosity level. By default, if a messages severity level is below the
simulations verbosity level, then it is not issued.
A VMM simulations verbosity level is determined by both a messages type and
severity. When using the messaging macros, the message severity is
automatically set, but in the absence of a severity type then a default severity is
selected base on the message type.
There are several command line arguments (or VMM options) that can be used
to set the simulations severity level:
+vmm_log_default=<level>

VMM option:
log_default
Sets the default verbosity
level, where level is defined
as:
error
warning
normal
trace
debug
verbose

Messaging
+vmm_force_verbosity=<level>

VMM option:
force_verbosity

Same as above.

Message Handling
Once a message is issued, the VMM message handler may act upon the
message if it has a special handling type. Special handling behavi ors are
defined as follows:

ABORT_SIM Calls the pre_abort() and
pre_finish() callbacks and
then aborts si mulation.
CONTINUE No extra action.
COUNT_ERROR Counts the message as an error.
If the max error count is reached
(specified by
stop_after_n_errors()), then
the si mulation is aborted, calling
the pre_abort() and
pre_finish() callbacks.
DEBUGGER Calls the pre_debug() callback
and stops si mulation.
DUMP_STACK Dumps the call stack (VCS only),
calls the pre_debug() callback,
IGNORE Ignores the message.
STOP_PROMPT Calls the pre_stop() callback

A messages handling type may be changed from the default behavi or by
invoking the vmm_log::modify() method. The default message handling
behaviors are defined as follows:

Severity Handling
FATAL_SEV ABORT_SIM
ERROR_SEV COUNT_ERROR
All others CONTINUE
Messaging
Message Catching
Message handling more advanced than the built-in handler types can be
performed by catching messages and invoking a user-defined handler. A user-
defined handler can be created by overloading the vmm_log_catcher::
caught()method.
Once the message catcher is defined, it is registered with the message service
by using the vmm_log::catch() method. As messages are written, the
catcher intercepts them and decides on whether to issue them
(vmm_log_catcher::issue()), throw them back to the message service to
be intercepted by other catchers (vmm_log_catcher::throw()), or simply
ignore them.
Message Watchpoints
Message watchpoints provide a way to trigger actions when certain message
types are issued via the vmm_log_watchpoint class. Testbench components
can use these watchpoints as blocking conditions or triggers to coordinate
testbench activi ties.
Message watchpoints are setup by using the
vmm_log::create_watchpoint() method that specifies the specific
message attributes to trigger upon. These watchpoints can then be added
(add_watchpoint()) or removed (remove_watchpoint()), or waited upon
by the testbench components (wait_for_watchpoint() and
wait_for_msg()).
Message Formatting
Before a message is finally issued, it wi ll be formatted according the defaults
defined by VMM. Generally, VMM messages take the following form:
severity[type] on name(instance) at time time:\n
message...
These defaults can be overridden by creating a vmm_log_format object,
overriding its format_msg() method, and registering it with the specific
vmm_log instance.
In addition, two macros wi ll also affect the default formatting of messages:

+define+VMM_LOG_FORMAT_FILE_LINE

Includes the file name and line
number whenever a message
is issued.
+define+VMM_LOG_ANSI_COLOR

Adds different colors to the
fatal, error, and warning
messages.
Messaging
Message Callbacks
As with other VMM services, messages can also have user-specified callbacks
associated wi th specific handler types. Message callbacks are defined by using
the vmm_log_callbacks class and overriding one of four methods:

pre_abort() Called when: (1) a message of
handling type ABORT_SIM is
issued, or (2) the error count is
reached and the handling type
is COUNT_ERROR.
pre_debug() Called before $stop when a
message of handling type
DEBUGGER or DUMP_STACK is
issued.
pre_finish() Same as above. Called
before $finish.
pre_stop() Called before $stop when a
message of handling type
STOP_PROMPT is issued.

Callbacks are appended (append_callback()) or prepended
(prepend_callback()) to the registered callback list and invoked in the order
registered. Note that callbacks are invoked after a message is already issued.
Creating Messages and Using Macros
Messages are created by using a combination of the start_msg(), text(),
and end_msg() methods. The start_msg() method sets up the message
services severity and type, applies any modifiers, and does a preliminary
filtering. The text message is then formatted by calling text() one or more
times, and end_msg() issues the message, calls any catchers, watchpoints,
and handler callbacks. For example, a message is issued in VMM as follows:
log.start_msg( vmm_log::NOTE_TYP,
vmm_log::DEFAULT_SEV,
`__FILE__, `__LINE__ );
log.text( "Building testbench environment ..." );
...
log.text( "Created subenvironment ..." );
log.text( "Done ..." );
log.end_msg();

The message macros simplify creating messages by calling these 3 methods
automatically. Messages can be issued wi th different types and severities by
simply picking the appropriate macro as shown in the following table:

Messaging
Macro Type Severity
`vmm_command(log, msg) COMMAND_TYP DEFAULT_SEV
`vmm_cycle(log, msg) CYCLE_TYP DEFAULT_SEV
`vmm_debug(log, msg) DEBUG_TYP DEBUG_SEV
`vmm_error(log, msg) FAILURE_TYP ERROR_SEV
`vmm_fatal(log, msg) FAILURE_TYP FATAL_SEV
`vmm_note(log, msg) NOTE_TYP DEFAULT_SEV
`vmm_protocol(log, msg) PROTOCOL_TYP DEFAULT_SEV
`vmm_report(log, msg) REPORT_TYP DEFAULT_SEV
`vmm_trace(log, msg) DEBUG_TYP TRACE_SEV
`vmm_transaction(log,msg) TRANSACTION_TYP DEFAULT_SEV
`vmm_user(n, log, msg) USER_TYP_N DEFAULT_SEV
`vmm_verbose(log, msg) DEBUG_TYP VERBOSE_SEV
`vmm_warning(log, msg) FAILURE_TYP WARNING_SEV

Each macro requires a vmm_log instance, which all VMM objects have as a
default member. Therefore, these macros can usually be used anywhere as-is
by just supplying a the text message. For example,

`vmm_note( log, "Building monitor ... " );
...
if (actual_data != expected_data) `vmm_error( log,
$psprintf("Actual data [%d] != expected [%d] !!!",
actual_data, expected_data) );
Message Service Flow
The following flowchart illustrates the message service mechanism and how the
components function together.

Macros
`vmm_trace( log, msg )
`vmm_note( log, msg )
`vmm_debug( log, msg )
...

Messaging

Quick Filter
vmm_log

Severity / verbosity level OK?
Disabled?

Message Modifier
vmm_log_modifier

Change type, severity, or
handling
vmm_log::modify()

Message Filtering
vmm_log

Severity/verbosity level OK?
Enabled/disabled?
IGNORE_
SEV?

Message Catcher
vmm_log_catcher

User-defined handler
vmm_log::catch( )
vmm_log_catcher::caught()
vmm_log_catcher::issue()
vmm_log_catcher::throw()

other catchers
Message Watchpoints
vmm_log_watchpoint

Watchpoint
vmm_log::create_watchpoint()
vmm_log::add_watchpoint()
vmm_log::remove_watchpoint()
vmm_log::wait_for_watchpoint()
vmm_log::wait_for_msg()

Messaging

Format & Issue Message
vmm_log_format

Format and issue message log to file

Message Handler
vmm_log

Respond to message based
on handling type:
ABORT_SIM
COUNT_ERROR
STOP_PROMPT
DEBUGGER
DUMP_STACK
DEFAULT

Message Callbacks
vmm_log_callbacks

pre_abort()
pre_finish()
pre_stop() pre_debug()

End simulation
report()
$finish

Done
(no extra action)

Tips
Use the message macros instead of $display so that messages can be
handled and filtered all in the same way. Macros of particular use are
`vmm_note, `vmm_warning, `vmm_error, and `vmm_fatal.
SystemVerilog allows strings to be concatenated together using braces { }.
This is a convenient way to bui ld text strings with the message macros.
Remember, however, to build a formatted string the $psprintf()or
$sformat() function is more suitable. (VMM aliases $psprintf() to
`vmm_sformatf()).
Messaging
See also
vmm_log, vmm_log_callbacks, vmm_log_catcher, vmm_log_format,
vmm_log_msg
vmm_ms_scenario
The vmm_ms_scenario class defines a basic multi-stream scenario. It extends
the basic vmm_scenario to include an execute() method, which is called by
a multi-stream generator. In the execute() method, transaction instances are
created and placed into an output channel. Other single or multi -stream
scenarios may be called as well to create a hierarchical scenario.
Multi-stream scenarios also have the advantage that they can interact with
multiple channels or invoke scenarios registered with other generators. Multi -
stream scenario generators provide the necessary methods to register and
retrieve references to other scenarios and channels. See the articles on
Scenarios and vmm_ms_scenario_gen for more details.
Declaration
class vmm_ms_scenario extends vmm_scenario;
Methods
function new(
vmm_scenario parent = null);
Constructor.
copy(
Copy method.
Returns a reference to a copy of
a multi-stream scenario. Must
be implemented.
virtual function vmm_channel
get_channel(
string name);
channel name registered wi th
the same generator as the
scenario.
Returns null if the channel
does not exist.
virtual function
vmm_ms_scenario_gen
get_context_gen();
Returns the generator executing
this scenario.
Returns null if the scenario is
not registered with a generator.
virtual function
vmm_ms_scenario
get_ms_scenario(
string scenario,
string gen = "");
Returns a copy of a scenario
registered as scenario under
the generator registered as gen.
Returns null if no such
scenario exists.
If gen is null, then assumes
the generator currently
executing the scenario.
vmm_ms_scenario
virtual task grab_channels(
ref vmm_channel
channels[$]);
Grabs exclusi ve access on
multiple channels specified by
channels[].
psdisplay(
string prefix="");
the multi-stream scenario.
function void
redefine_scenario(
int unsigned scenario_kind,
string name,
int unsigned max_len = 0);
Inherited from vmm_scenario.
Redefines a scenarios name or
maxi mum length.
function string scenario_name(
int unsigned
scenario_kind = 0);
scenario specified by the
scenario_kind.
Members
static vmm_log log; Class-wide available message
service.
int scenario_id; Inherited from vmm_scenario.
Generators scenario count
assigned before randomization
used to identify scenarios in a
stream or for random
constraints.
int stream_id; Inherited from vmm_scenario.
Generators stream ID assigned
before randomization used by
other components (like a
scoreboard) to differentiate
transactions.
Example
// Simple multi-stream scenario
class usb_scenario extends vmm_ms_scenario;
usb_channel usb_chan;
int usb_scn = define_scenario("USB_SCN", 0);

`vmm_scenario_member_begin( usb_scenario )
`vmm_scenario_member_scalar( usb_scn, DO_ALL )
`vmm_scenario_member_end( usb_scenario )

vmm_ms_scenario
virtual task execute( ref int n );
if ( usb_chan == null )
$cast( usb_chan, get_channel("USB_CHANNEL"));

repeat (10) begin
usb_trans tr = new;
tr.randomize();
usb_chan.put( tr );
n++;
end
endtask
endclass

// Hierarchical multi-stream scenario
class stress_scenario extends vmm_ms_scenario;
int stress_scn = define_scenario("STRESS_SCN", 0);

`vmm_scenario_member_begin( stress_scenario )
`vmm_scenario_member_scalar( stress_scn )
`vmm_scenario_member_end( stress_scenario )

task execute( ref int n );
vmm_ms_scenario scn1, scn2, scn3;

scn1 = get_ms_scenario("USB_SCN", "USB_GEN");
scn2 = get_ms_scenario("SPI_SCN", "SPI_GEN");
scn3 = get_ms_scenario("MCBSP_SCN", "MCBSP_GEN");

fork
scn1.execute( n );
scn2.execute( n );
scn3.execute( n );
join
endtask
endclass
Tips
While a multi-stream scenario inherits from vmm_scenario several
properties li ke repeated, they are never used by the multi-stream
generator.
The name used to register a multi-stream scenario is the same name used
to override it wi th the factory interface.
vmm_ms_scenario
Gotchas
Remember to overload the execute() method instead of apply() as
with single-stream scenarios.
See also
Scenarios, vmm_scenario, vmm_ms_scenario_gen, vmm_ss_scenario
vmm_ms_scenario_gen
The vmm_ms_scenario_gen class defines the functionali ty for a multi-stream
scenario generator used to execute multi-stream scenarios. Multi-stream
generators have all the basic functionality of a single-stream generator, but they
also provide the abili ty to define more than one output streams. Therefore, they
include addi tional channel methods for registering and using channels for the
multi-stream scenarios.
In contrast to single-stream scenarios, multi-stream scenarios use an
execute() method instead of apply(). Likewise, multi-stream scenarios are
not repeated by the generator nor is the post_scenario_gen() callback
invoked.
Multi-stream generators may be registered under other generators to form a
hierarchy, which allows scenarios to call other scenarios registered with other
generators. See the articles on Scenarios and vmm_scenario_gen more
detai ls.
Declaration
class vmm_gen_scenario_gen extends vmm_xactor;
Methods
function new(
string inst,
int stream_id = -1,
Constructor.
virtual function bit channel_exists(
string name);
Returns true if the
channel is registered
under name.
get_all_channel_names(
ref string name[$]);
Returns an array of all
registered channel
names.
get_all_ms_scenario_gen_names(
registered sub-
generators.
get_all_ms_scenario_names(
registered scenario
names.
get_channel(
string name);
Returns a reference to
the channel registered
under name.
Returns null if the
channel does not exist.
vmm_ms_scenario_gen
get_channel_name(
vmm_channel chan);
Returns the registered
name for the channel
chan.
Returns "" if the channel
is not registered.
virtual function vmm_ms_scenario
get_ms_scenario(
string name);
the specified registered
multi-stream scenario.
Returns null if the
scenario does not exist.
virtual function vmm_ms_scenario_gen
get_ms_scenario_gen(
string name);
the sub-generator
registered under name.
Returns null if
generator does not exist.
get_ms_scenario_gen_name(
vmm_ms_scenario_gen scenario_gen);
registered sub-
generator.
Returns "" if the sub-
generator does not exist.
get_ms_scenario_index(
vmm_ms_scenario scenario);
Returns the scenarios
index into the
scenario_set[]
array.
Returns -1 if the
scenario is not
registered.
get_ms_scenario_name(
Returns the scenarios
registered name.
Returns "" if the scenario
is not registered.
function int unsigned get_n_insts(); Returns the number of
transaction instances
generated.
get_n_scenarios();
scenarios generated.
get_names_by_channel(
vmm_channel chan,
Returns an array of
names for the registered
channel.
vmm_ms_scenario_gen
get_names_by_ms_scenario(
vmm_ms_scenario scenario,
ref string name[$])
Returns an array of
scenario.
get_names_by_ms_scenario_gen(
vmm_ms_scenario_gen scenario_gen,
Returns an array of
generator.
ms_scenario_exists(
string name);
Returns true if the
scenario name is
registered.
ms_scenario_gen_exists(
string name);
Returns true if the sub-
generator name is
registered.
virtual function string psdisplay(
Returns a string
description of the
generator.
register_channel(
string name,
vmm_channel chan);
Registers a channel
under name with the
generator.
register_ms_scenario(
string name,
Registers a multi-stream
scenario under name
with the generator.
register_ms_scenario_gen(
string name,
Registers a sub-
generator under name
with the generator.
replace_channel(
string name,
vmm_channel chan);
Replaces the registered
channel with a new
channel.

replace_ms_scenario(
string name,
multi-stream scenario
with a new scenario.
replace_ms_scenario_gen(
string name,
multi-stream generator
with a new generator.
vmm_ms_scenario_gen
virtual function void reset_xactor(
= SOFT_RST);
Resets the generator.
SOFT_RST clears the
scenario and instance
counts.
HARD_RST clears the
stop limi ts and creates a
new election instance.
unregister_channel(
vmm_channel chan);
Unregisters the
registered channel.
Returns true if the entry
exists.
unregister_channel_by_name(
string name);
Unregisters the
registered channel.
channel exi sts.
unregister_ms_scenario(
Unregisters the
registered scenario.
exists.
virtual function vmm_ms_scenario
unregister_ms_scenario_by_name(
string name);
Unregisters the
registered scenario.
scenario exists.
unregister_ms_scenario_gen(
Unregisters the
registered sub-
generator.
exists.
virtual function vmm_ms_scenario_gen
unregister_ms_scenario_gen_by_name(
string name);
Unregisters the
registered sub-
generator.
sub-generator exists.
Members
protected int inst_count; Number of transaction
instances generated by
the generator.
protected int scenario_count; Number of scenarios
generated by the
generator.
vmm_ms_scenario_gen
vmm_ms_scenario scenario_set[$]; Set of registered multi-
stream scenarios.
vmm_ms_scenario_election
select_scenario;
Selection instanced
used to pick the next
scenario to generate.
int unsigned stop_after_n_insts; Maxi mum number of
transaction instances to
generate.
int unsigned stop_after_n_scenarios; Maxi mum number of
scenarios to generate.
typedef enum int {
GENERATED,
DONE
} symbols_e;
Notification
enumeration.
Example
class system _scenario extends vmm_ms_scenario;
...
endclass

program test1;
vmm_ms_scenario_gen gen = new("Multi-stream gen", 1);

system_scenario sys_scn = new;

cpu_channel cpu_chan = new( "CPU Chan", "test1" );
eth_channel eth_chan = new( "Ethernet Chan", "test1" );

initial
begin
gen.register_channel( "CPU_CHANNEL", cpu_chan );
gen.register_channel( "ETH_CHANNEL", eth_chan );
gen.register_ms_scenario( "SYS_SCN", sys_scn );

gen.stop_after_n_scenarios = 5;

fork
forever begin
eth_trans tr;
eth_chan.get( tr );
tr.display( "Eth: " );
end
vmm_ms_scenario_gen
forever begin
cpu_inst op;
cpu_chan.get( op );
op.display( "CPU: " );
end
join_none

gen.start_xactor();
gen.notify.wait_for( vmm_ms_scenario_gen::DONE );

end
endprogram
Tips
When the maxi mum scenario or instance li mit is reached, the generator
must be reset before it can be restarted.
A scenario may be registered under different names to create aliases of the
scenario.
Sub-generators must not be started using start_xactor()only the top
scenario generator.
Gotchas
It is an error to try and register a channel, scenario, or generator that is
already registered. Use the replace methods to change the registration.
Sub-scenarios executed as part of a higher-level scenario are not counted
as part of scenario_count or towards the stop_after_n_scenarios
limi t.
More transaction instances may be generated than the
stop_after_n_insts limit since scenarios will finish execution once
started.
See also
Scenarios, vmm_scenario_gen, vmm_scenario, vmm_ms_scenario,
vmm_*_scenario_gen_callbacks, vmm_*_scenario_election
Name Matching
VMM uses a consistent mechanism to find and match the names of units in the
instance hierarchy. Whenever you need to specify the name of a unit instance
as a string, you can use a name pattern.
Where
Setting options of an instance or set of instances from the command line or from
an options file:
... +vmm_opts+option=value@NAME_PATTERN...
Setting configuration options at run ti me:
vmm_opts::set_type("NAME_PATTERN:option_name", value,
...);
Finding the instance whose name matches a pattern:
vmm_object obj = find_object_by_name("NAME_PATTERN");
obj = find_child_by_name("NAME_PATTERN");
Syntax
There are three distinct forms of name pattern string: hierarchy name patterns,
regular expressions, and literal strings. Most operations that require a name
pattern string can accept any one of the three forms. Of the three forms,
hierarchy name patterns are preferred for almost all purposes; they include literal
strings as a subset, and are designed to work well with the VMM hierarchy
naming conventions and typical testbench architectures.
Option values (see vmm_opts) can include a pattern specifying the object or
objects to which the option should apply. This pattern must be an hierarchy
name pattern, beginning wi th an at-sign @ (see below); the other forms of pattern
are not acceptable within an option value.
Hierarchy name pattern matching
A pattern whose first character is an at-sign @ is an hierarchy name pattern.
The leading @ character does not form part of the pattern. In the remainder of
the pattern, each character is interpreted as follows:
. (period) Matches any single character except the hierarchy path
separator character :.
* (asterisk) Matches any string of zero or more characters not including
the hierarchy path separator character :.
? (query) Matches an optional character, not including the hierarchy
path separator character :. For example, the match pattern
"A?A" will match the names "AA" or "ABA", but not "A:A".
% (percent) Matches any hierarchical path name. The match may include
Name Matching
any number of colon (:) separator characters. It must end
with a separator character :.
Any other
character
Any character, other than the four special characters listed
above, stands for itself and matches only a single occurrence
of that same character. Matching is case sensiti ve.

If the pattern begins with one of the special characters .*?%, or if it contains no
special characters at all, then it is taken to be an absolute pattern and must
match the entire pathname from beginning to end. Otherwise it is taken to be a
suffix pattern, i.e. it must match up to the end of the pathname, but it is not
necessary to match the beginning of the pathname.
Regular expression matching
A pattern whose first and last characters are both / (forward-slash) is a regular
expression. The leading and trailing forward-slash characters will be stripped
away, and do not form part of the regular expression. The remainder of the
pattern is used as a regular expression for matching, and generally follows
conventional POSIX-style regular expression syntax.
Literal string matching
Any other pattern is a simple literal string, and matches only an identical string
using case-sensi ti ve string equality comparison.
Examples
Pattern Examples that match Examples that do not match
@A%B AB
A:B
ABC:B
A:C:B
ab (case sensiti ve)
ABC (% match must end in :)
ABD (must match to end)
anythingA:B
(would need @%*A:B)
@A:*:B A:any_simple_name:B
prefixA:name:B
A:C:B:B (* does not match :)
@%.B AB
P:Q:R:aB
A:B (. does not match nothing)
ABC (% match must end in :)

Tips
If you know the instance name of a leaf object, but dont know (or dont
want to know) precisely where it appears in the hierarchy, you can find it
using the hierarchy name pattern @%name.
Name Matching
The previous Tip works only for leaf objects, i.e. those that have no child
objects. If you wish to find an object that may have children, you can use
the hierarchy name pattern @name%*. Note the trailing asterisk on this
pattern see the first Gotcha below!
Choose object instance names carefully so that you can use a simple
hierarchical match pattern to identify them regardless of their precise
location in the hierarchy.
Gotchas
Hierarchy name patterns should never end with the % character, since that
could match only names ending in : which is impossible.
The syntax of regular expressions gi ves special meaning to many
characters, including these: .+*|[]()?^${}
If you wish to match any of these characters in a regular expression, you
must escape each occurrence with a backslash \. Alternati vely you can
use character sets enclosed in square brackets.
The preceding Gotcha! applies only to regular expressions, and does not
apply to the other forms of match pattern! Beware, though, that in any
literal (quoted) Verilog string you need two successive backslashes to
create a single backslash in the string, because backslash acts as an
escape character in Verilog string literals.
See also
vmm_object, vmm_opts
vmm_notify
The vmm_notify class provides a mechanism for communication between
independent execution threads. Specific notifications are defined by a
notification ID (most VMM components define this as an enumeration such as
vmm_xactor::XACTOR_IDLE, vmm_env::GEN_CFG, etc). Associated with the
notification ID is a vmm_notification instance, which defines an overloadable
indicate() method used to autonomously determine when the event (that is,
the notification) has occurred. If no vmm_notification is specified, then
calling the vmm_notify::indicate() method indicates the notification.
Blocking wait methods are defined by vmm_notify in order to wait for
notifications to occur.
Once a notification is indicated, a user-defined callback routine can be invoked.
Callbacks are defined by extending the vmm_notify_callbacks class to
overload the indicated()method. A vmm_data object is used as a status
descriptor that is set by the vmm_notify::indicate() method. Status
descriptors are then passed into the
vmm_notify_callbacks::indicated() functions.

Notification classes Description
vmm_notify Base class that defines the
notification service.
Uses the
vmm_notification and
vmm_notify_callbacks
classes.

Defines a callback routine to
be invoked when a notification
occurs.

In addition to callbacks, each notification ID can have an associated
synchronization type. The synchronization type is set by vmm_notify::
Indication
Notification
Service
vmm_notify
vmm_notify::indicate( id, status )
Notification
vmm_notification
Callback
vmm_notify::set_notification( id, ntfy )
vmm_notification:indicate( status )
vmm_notify_callbacks::indicated( status )
vmm_notify
configure() and can have one of the following values:

Synchronization mode Operation
ONE_SHOT Only the threads already
wai ting for the event will be
notified.
BLAST All threads waiting for an event
in the same ti me step wi ll be
notified.
ON_OFF Notification is level-sensiti ve
(on or off), and the event
remains in effect unti l the
nofication is reset.
Declaration
class vmm_notify extends vmm_object;
Methods
function new(
vmm_log log);
Constructor.
int notification_id,
vmm_notify_callbacks cbs);
Adds the specified callback
routine to invoke when
notification id occurs.
virtual function int configure(
int notification_id = -1,
sync_e sync = ONE_SHOT);
Defines a notification
associated wi th a notification
ID.
Returns the assigned
notifcation ID.
If notification_id is
negati ve, a unique ID greater
than 1,000,000 is returned. If
passed a posi ti ve
notification_id, then it
must be less than the reserved
numbers starting at 1,000,000.
Synchronization type must be
ONE_SHOT, BLAST, or
ON_OFF.
vmm_notify
virtual function vmm_notify
copy(
vmm_notify to = null);
Copies configuration of
vmm_notify instance into
new instance specified by to.
Copied information overwrites
any duplicate notification
identifiers in the destination
instance.
Ti mestamp and status are not
copied.
Prints out notification instance
detai ls.
virtual function void indicate(
vmm_data status = null);
Indicates the specific
notification has occurred.
Status argument is optional.
is_configured(
Returns 0 if not configured.
Returns current configuration
(ONE_SHOT, BLAST, or
ON_OFF) if configured.
virtual function bit is_on(
Returns 1 if notification is on
(in the notify state) and wi ll not
cause wait_for() to block.
is_waited_for(
Returns 1 if a thread is waiting
for the specified notification (or
a notification reset).
psdisplay(
Returns a string of the current
state of the notification.
function void
register_vmm_sb_ds(
vmm_sb_ds_base sb,
Registers a data stream
scoreboard with a specific
notification.
kind is INPUT, EXPECT, or
EITHER.
order is IN_ORDER,
WITH_LOSSES, or
OUT_ORDER.
See VMM Scoreboarding User
Guide for details.
vmm_notify
virtual function void reset(
int notification_id = -1,
reset_e rst_typ = SOFT);
Resets the specified
notification.
Reset type:
SOFT
Clears ON_OFF notification.
Restarts vmm_notifications
indicate() and reset()
methods.

HARD
Clears all status information
and attached notifications.
status(
Returns the status descriptor
of the last specified
notification.
terminated(
Indicates that a thread waiting
for the specified notification
has terminated.
virtual function time
timestamp(
Returns the ti mestamp of the
last specified notification.
function void
vmm_notify_callbacks cbs);
Unregister specified callback.
Generates an error if specified
callback is not registered.
function void
vmm_sb_ds sb);
Unregister specified
scoreboard.
Generates an error if specified
scoreboard is not registered.
virtual task wait_for(
Blocks thread execution until
the specified notification
occurs.
virtual task wait_for_off(
Blocks thread execution until
the specified ON_OFF
notification is reset.
Members
this component.
vmm_notify
enum int {
ONE_SHOT,
BLAST,
ON_OFF
} sync_e;
Synchronization mode
enumeration.
enum bit {
SOFT,
HARD
} reset_e;
Reset type enumeration.
The vmm_notify_callbacks class defines a callback method
indicated()that is called when the associated notification occurs. The
callback is registered wi th the notification service using the
vmm_notify::append_callbacks() method. Using a callback has the
advantage of catching multiple indications in the same timestep, whereas the
wait_for() method misses concurrent indications.
Declaration
virtual class vmm_notify_callbacks;
Methods
virtual task indicated(
vmm_data status);
User-definable callback
method.
vmm_notify_observer
A vmm_notify_observer is provided to more easily create a notification
callback. It is a parameterized version of the vmm_notify_callbacks class,
and combined wi th the `vmm_notify_observer() macro, provides a
simplified means of subscribing a callback notification. See below for an
example.
Declaration
class vmm_notify_observer #(type T=vmm_channel,
type D=vmm_data)
extends vmm_notify_callbacks;
vmm_notify
Methods
function void indicated(
vmm_data trans);
User-definable callback
method.
Example
Example using the xactors notify instance
class abc_subenv extends `VMM_SUBENV;
abc_xactor xact;
...

function void stop();
super.stop();

// Wait for the transactor to stop
xact.notify.wait_for( vmm_xactor::XACTOR_IS_STOPPED );
...
endfunction
endclass : custom_subenv
Example creating a custom notification
typedef enum { XYZ_IDLE, XYZ_STARTED, XYZ_STOPPED,
XYZ_RESET } xyz_ntfy_t;

class comp_xyz extends vmm_object;
vmm_log log;
vmm_notify ntfy;

function new( vmm_object parent = null, ... );
super.new( parent, ... );
log = new( "Comp XYZ", "" );
ntfy = new ( log );

// Configure notifications
ntfy.configure( XYZ_IDLE, vmm_notify::ON_OFF );
ntfy.configure( XYZ_STARTED, vmm_notify::ON_OFF );
ntfy.configure( XYZ_STOPPED, vmm_notify::ON_OFF );
ntfy.configure( XYZ_RESET, vmm_notify::ON_OFF );
endfunction

vmm_notify
task start();
...
ntfy.indicate( XYZ_STARTED );
endtask

task stop();
...
ntfy.indicate( XYZ_STOPPED );
endtask

task restart();
...
ntfy.reset( XYZ_RESET, vmm_notify::SOFT );
endtask
endclass : comp_xyz
Example using a notification callback
// Callback to collect coverage upon notification
class bus_cov_cb extends vmm_notify_callbacks;
int rx_count = 0;
int tx_count = 0;

covergroup bus_cov;
coverpoint rx_count;
coverpoint tx_count;
endgroup

task indicated( vmm_data status );
if ( status.type == RX ) rx_count++;
if ( status.type == TX ) tx_count++;
bus_cov.sample(); // Collect the coverage
endtask
endclass : bus_cov_cb

class bus_monitor extends vmm_xactor;

typedef enum { BUS_TRANSFER } bus_op_e;
notification_rx_or_tx notification;

function new ( ... );
...

bus_cov_cb = new;
super.notify.configure( BUS_TRANSFER );
vmm_notify
// Collect coverage with the callback when a BUS_TRANSFER occurs
super.notify.append_callback( BUS_TRANSFER,
bus_cov_cb );
endfunction
...
endclass : bus_monitor
Example using the vmm_notify_observer
class cov_recorder;
covergroup cg;
coverpoint data;
endgroup
...
function void record_cov( my_trans tr );
// Setup covergroup values
data = tr.data;
...
cg.sample();
endfunction
endclass
`vmm_notify_observer( cov_recorder, my_trans )

cov_recorder cr = new();
cov_recorder_notify_observer( my_trans )
observe = new( cov_recorder, mon.notify,
my_monitor::RECORD_TRANS );
Tips
Once a notification occurs, use vmm_notify::status() to retrieve its
status information.
Most VMM components and the VMM data object have a built-in notify
instance that can be used for notifications.
When a thread is externally terminated by disable, the notification service
has no way of knowing that the thread is no longer waiting. Use
terminated() to indicate that this has occurred.
Use a vmm_notify_observer to simplify setting up a notification
callback.
Gotchas
When a HARD reset occurs, the wait for thread count is cleared.
vmm_notify
A warning is issued when a notification is configured more than once.
It is an error to call status(), timestamp(), wait_for(), or
is_waited_for() on an unconfigured notification. It is also an error to
call is_on()or wait_for_off() on a notification not configured
ON_OFF, or try to unregister a notification that was not registered.
See also
vmm_consensus
vmm_object
The vmm_object class is the abstract base class of most other VMM classes.
Instances of classes deri ved from vmm_object (objects) may form an object
hierarchy. Every object in the hierarchy stores a reference to its parent object
and maintains a list of references to child objects. A child object is usually a
member of a parent object and is typically created by it. An object at the top of
the hierarchy has no parent and is known as a root object.
The objects at every level within the hierarchy each have a unique hierarchical
name. The vmm_object class provides methods to access the hierarchical
name of an object, to search for named objects and to access parent and child
objects.
Although it is often useful to create a hierarchy of related objects, it is not
mandatory to specify a parent object or a unique name when creating an
instance of a class deri ved from vmm_object..
Objects may optionally be accessed as members of a namespace each name
within a namespace acts as an alias to the hierarchical name of a particular
object.
A common vmm_log interface to the message service named "Global" is created
by vmm_object. This acts as the default message service for all instances of
classes derived from vmm_object that do not define their own local message
service.
VMM 1.1 provided an alternati ve optional implementation of the vmm_object
class. Its methods are deprecated in VMM 1.2 and are not listed here.
Declaration
virtual class vmm_object;
Methods
function new(
string name="[anonymous]");
Constructor. If parent object is
specified, adds this to the
parents list of child objects.
pure virtual function string
get_typename();
Returns the type of the object
as a string. The macro
`vmm_typename(class)
should be called in each
derived class to define this
function.
static function bit
create_namespace(
string name,
namespace_typ_e
= OUT_BY_DEFAULT);
Creates a namespace with the
specified inclusion policy.
Returns 1'b0 if create fails
vmm_object
get_namespaces(
output string name[]);
Returns an associati ve array
containing all exi sting
namespace names
function void set_object_name(
string name,
string space = "");
Sets the object name and
namespace (2
nd
argument). If
namespace is not specified, it
defaults to the object name.
function void
set_parent_object(
vmm_object parent);
Sets the parent object. If a
new parent is specified,
deletes this from the old
parents list of child objects.
kill_object();
Get ready to delete the object.
function vmm_object
get_parent_object();
objects parent.
function vmm_object
get_root_object(
string space = "");
parent object that is at the root
of the specified namespace.
Returns root of this object
hierarchy if namespace not
specified.
function int
get_num_children();
Returns the number of child
objects (objects having this
as their parent)
function vmm_object
get_nth_child(int n);
indexed child object. Index
follows the order objects were
added to child list (by new or
set_parent_object). First
index is 0. Returns null if
child does not exist.
static function int
get_num_roots(
string space = "");
Returns the number of root
objects in the namespace.
Returns total number of root
objects if namespace not
specified.
static function vmm_object
get_nth_root(
int n,
string space = "");
indexed root object in the
namespace. Returns
reference from global list of
root objects if namespace not
specified. Returns null if root
not found.
vmm_object
function string
get_object_name(
string space = "");
Returns local name of object
in namespace. Returns actual
name if namespace not
specified.
function string
get_object_hiername(
vmm_object root = null,
string space = "");
Returns hierarchical name of
object in namespace, relati ve
to root object. If namespace
not specified, returns actual
hierarchical name relati ve to
root. If root not specified,
returns full hierarchical name.
function vmm_object
find_child_by_name(
string name,
string space = "");
Returns reference to child
object. The name argument
may be a relati ve hierarchical
name, a matching pattern or a
regular expression. Search is
within namespace if specified,
otherwise in current hierarchy.
Returns null if child not
found.
static function vmm_object
find_object_by_name(
string name,
string space = "");
Returns reference to the
named object. The name
argument may be an absolute
hierarchical name, a matching
pattern or a regular
expression. Search is within
namespace if specified,
otherwise applied to all
objects. Returns null if child
not found.
psdisplay(
Returns a string describing the
object's content. Should be
overridden in derived classes
to reflect addi tional members.
display_hierarchy(
vmm_object root = null);
Prints the object hierarchy,
starting from the specified
root. Prints all object
hierarchies if root not
specified.
virtual function vmm_log
get_log();
vmm_log for this object.
implicit_phasing(bit is_on);
Turns off automatic running of
all phases if is_on = 1'b0
is_implicitly_phased();
Returns 1'b1 if implicit
phasing enabled
vmm_object
Members
typedef enum {
IN_BY_DEFAULT,
OUT_BY_DEFAULT
} namespace_typ_e;
Name space enumeration
Macros
`vmm_typename(name)
This macro defines the virtual get_typename function to return a string
containing the object type. It should be called wi thin the declaration of every
class deri ved from vmm_object.
Example
program P;
ìnclude "vmm_sv"

class A extends vmm_object;
`vmm_typename(A)
function new(string name, vmm_object parent=null);
super.new(parent,name);
endfunction: new
endclass: A
class B extends vmm_object;
`vmm_typename(B)
A child;
function new(string name, vmm_object parent=null);
super.new(parent,name);
child = new("child",this); //create a child of B
endfunction: new
endclass: B
A parent = new("parent");

initial
vmm_object::display_hierarchy(); // [parent]
// |--[child]
endprogram: P

vmm_object
Tips
Remember to call super.new in the constructor of derived classes or the
name and parent object reference will not be stored.
For structural components such as transactors, you should use the
appropriate base class rather than vmm_object:
o For transactors, vmm_xactor
o For an env or subenv wi th explicit phasing, vmm_env or
vmm_subenv
o For an env or subenv wi th implicit phasing, vmm_group
o For transactions, vmm_data.
Name the object the same as the instance variable name so the
hierarchical name wi ll match in a Verilog cross-module reference.
Gotchas
Calling set_object_name wi thout specifying a namespace wi ll rename
the object.
Take care when calling set_parent_object since it changes the
hierarchy it is possible to set an object's parent to be a different object
from the one that instantiates it!
See also
vmm_object_iter, vmm_uni t
vmm_object_iter
The vmm_object_iter class supports iteration (scanning) over objects in the
hierarchy whose names match some pattern.
Convenience macros `foreach_vmm_object and
`foreach_vmm_object_in_namespace packages the most common
applications of object iteration in an easy-to-use form. In the majority of cases,
user code will invoke this macro in preference to using the iterator class
explicitly.
The iterator visi ts objects using a breadth-first scan. All root objects are scanned
first, then all children of each root object in turn, then all grandchildren and so
on. Scanned objects are filtered based on their hierarchical name (and, in the
case of `foreach_vmm_object, by class type); objects that do not match the
filter criteria are not visited by `foreach_vmm_object and are not returned by
the iterator class's first() and next() methods. However, the scan
continues to all children of a scanned object whether or not it meets the filter
criteria.
Legacy mechanisms vmm_xactor_iter and `foreach_vmm_xactor
continue to be avai lable. They are used to visi t only transactors, whereas
vmm_object_iter and `foreach_vmm_object can visit any and all objects
in the hierarchy.
Declaration
class vmm_object_iter; ...
`define foreach_vmm_object(object, name, root) ...
Methods
function new (
string name = "",
string space = "" );
Creates and initializes the
iterator. name is a name
pattern; only objects whose
hierarchy name matches the
pattern will be visited. root
specifies the root object from
which the scan should begin. It
also specifies the root of the
relati ve object names. If it is
null, all parts of the hierarchy
will be scanned.
function vmm_object first(); Reset the iterator to the first
object to be visi ted, and return
a handle to that object (or
null if no object under the
specified root has a name that
matches the pattern).
vmm_object_iter
function vmm_object next(); Returns a handle to the next
object to be visi ted.
Members
vmm_object_iter has no user-accessible data members.
Macros
`foreach_vmm_object (
objtype, name, root ) begin
// user code here
end
Creates a loop that
iterates over all objects
under root that match
name. Only objects of,
or derived from, class
objtype are visited.
Declares a variable
obj of type objtype
to hold a reference to
the visi ted object on
each iteration.
`foreach_vmm_object_in_namespace (
objtype, name, space, root ) begin
// user code here
end
Like
`foreach_vmm_object
but iterates over all
objects in the specified
namespace.
Example
function void display_all_units();
begin // see Gotchas!
`foreach_vmm_object(vmm_unit, "@%*", null) begin
// Scan the entire hierarchy (all roots, all names) but visit only objects
// derived from vmm_uni t.
// "obj" is a variable of type vmm_unit, declared by the macro.
`vmm_note(log, $sformatf(
"Found unit %s", obj.get_object_hiername()));
end
end
endfunction
Tips
The name argument to vmm_object_iter::new and
`foreach_vmm_object can have any of the three forms acceptable for
hierarchy name match patterns see Name matching.
vmm_object_iter
Use `foreach_vmm_object for flexibili ty and convenience. As well as
simplifying your code, it adds the abili ty to filter objects by data type.
Gotchas
The expansion of macro `foreach_vmm_object starts by declaring a
variable named obj. Consequently, an invocation of this macro must be
the first executable code in any begin...end or other procedural block;
and there must not be any other identifier named obj in the same scope.
To avoid surprises, enclose the entire `foreach_vmm_object loop in its
own begin...end block.
The `foreach_vmm_object macro, like other procedural control
constructs in Verilog, controls only one procedural statement. Use
begin...end, as in our example, to encapsulate the body of the loop.
Never add a semicolon after the closing parenthesi s of the macro!
See also
Name Matching, vmm_object
vmm_opts
This class implements the options service. It manages a centralized database of
option values that can configure and control the testbench. Options can be set
from the command line, from a control file, and by method calls in SystemVerilog
code. Once set, the options can be queried by other method calls. Options can
also be used to support automatic configuration of values of specific data
members of vmm_unit objects in the testbench see Configuration macros.
The vmm_opts class contains only static members and methods. User code
should never attempt to construct an instance of vmm_opts. Likewise, you
should never create a class deri ved from vmm_opts.
Specifying options
There are three distinct ways to specify options and their values in a VMM
testbench: software control, command line or options file.
Software control of options is done by calling the vmm_opts::set_xxx
methods at any time. In practice these methods would probably be called in the
configure_ph method to propagate option values hierarchically, so that all
necessary option values are in place ready to be queried during later phases.
Software controlled options have the lowest priority; they can be overridden by
options specified on the command line or in an options file.
Options can be specified on the command line using standard Verilog plusargs.
Command line options have the highest priority, and can override options
specified any other way. Command line option specifications must be in one of
the following three forms:
A single +vmm_opts string, which can specify more than one option
separated by + signs:
+vmm_opts+optionA+optionB...
Each option is of the form
optname=value@pattern
where optname is the simple name by which the option is known in the
options database, value is the value of the option and @pattern is a
hierarchy match pattern (see Name matching) specifying the set of objects
to which the option is applicable. The =value and @pattern components
are both optional; either can be omitted.
One or more test-specific options of the form +vmm_option. This is
equi valent to +vmm_opts+option and can accept =value and @pattern
components in the same way.
A single +vmm_opts_file option, specifying one or more options files
(see below). in the form +vmm_opts_file+file1+file2.
An options file is a plain-text file containing option specifications, in the form
descriptive_text+optname=value@pattern, in which the optname,
value and pattern components are handled just as for command-line options.
These option specifications must be separated by whitespace, and it is
preferable for each to appear on a line of its own. Options specified in a file can
vmm_opts
override same-named options set under software control, but can be overridden
by command-line options. The descripti ve text must not include any + character.
Range-valued options
Option values can have bit, int, string or object data type. However, VMM
also provides an additional range option type. When specifying a range-valued
option in a file or on the command line, the value should be written as an integer
range in square brackets, such as +vmm_opts+data_range=[5:10]. The
lower value must appear first. When specifying a range value through a method
call, and when retrieving the range using a method call, two int arguments min
and max are used.
Object-valued options
Options whose value is an object cannot be set using the command line or an
options file. They must be set using the vmm_opts::set_object() method.
The option stores an object handle of vmm_object type; the object itself should
already have been created before set_object is called.
Methods
Note that all the methods described here are static and should be called using
the vmm_opts:: prefix.
Methods to set an option
All these methods have name and (optional) root arguments. Taken together,
these arguments specify both the unique name of the option and the hierarchical
location or search path specifying to which object(s) the option is applicable. The
fname and lineno arguments can be filled in wi th information that is used by
the get_help method (see below) and other diagnostics.
function void set_bit (
string name,
bit val,
vmm_unit root = null,
string fname = "",
int lineno = 0 );
Set the bit-valued option name, in
the hierarchy context specified by
root, to have the value val.
function void set_int (
string name,
int val,
string fname = "",
int lineno = 0 );
As set_bit, but the option is
int-valued.
vmm_opts
function void set_string (
string name,
string val,
string fname = "",
int lineno = 0 );
As set_bit, but the option is
string-valued.
function void set_object (
string name,
vmm_object obj,
string fname = "",
int lineno = 0 );
As set_bit, but the option's
value is a vmm_object handle.
function void set_range (
string name,
int min, max,
string fname = "",
int lineno = 0 );
As set_bit, but the option's
value is a pair of ints
representing a range.

Methods to retrieve an option for a given object
These methods should be called with a si mple option name as their name
argument (no hierarchy in the name). They retrieve the opti on database
associated wi th that name, and use it to find the highest-priority option value
applicable to the specified object.
The verbosity, fname and lineno arguments can be filled in with information
that is used by the get_help method (see below) and other diagnostics.
function bit
get_object_bit (
output bit is_set,
input vmm_object obj,
string name,
string doc = "",
int verbosity = 0,
string fname = "",
int lineno = 0 );
Inquire about any bit-valued
option name applicable to
object obj. Output is_set
indicates whether there is any
such option. Returns the
option value if it exists, zero if
not.
function string
get_object_string (
output bit is_set,
string name,
string dflt,
string doc = "",
int verbosity = 0,
string fname = "",
int lineno = 0 );
Inquire about any string-
valued option name applicable
to object obj. Output is_set
option value if it exists; returns
the dflt argument if not.
vmm_opts
function int
get_object_int (
output bit is_set,
string name,
int dflt = 0,
string doc = "",
int verbosity = 0,
string fname = "",
int lineno = 0 );
Inquire about any int-valued
option name applicable to
object obj. Output is_set
function void
get_object_range (
output bit is_set,
string name,
output int min, max,
input int dflt_min, dflt_max,
string doc = "",
int verbosity = 0,
string fname = "",
int lineno = 0 );
Inquire about any range-
valued option name applicable
to object obj. Output is_set
such option. Fills in min and
max with the option value if it
exists; or with the dflt_*
arguments if not.
function vmm_object
get_object_obj (
output bit is_set,
string name,
vmm_object dflt = null,
string fname = "",
int lineno = 0 );
Inquire about any
vmm_object-valued option
name applicable to object obj.
Output is_set indicates
whether there is any such
option. Returns the option
value if it exists; returns the
dflt argument if not.

Methods to retrieve a global option
These methods are typically used to retrieve system-wide options that have
been set from the command line or an options file, but they can equally well
retrieve global options that have been set using the set_* methods with a null
root argument.
The verbosity, fname and lineno arguments can be filled in with information
that is used by the get_help method (see below) and other diagnostics.
function bit
get_bit (
string name,
string doc = "",
int verbosity = 0,
string fname = "",
int lineno = 0 );
Inquire about option name.
Result indicates whether there
is any such option. Returns
TRUE (1) if the option has
been set, FALSE (0) if not.
vmm_opts
function string
get_string (
string name,
string dflt,
string doc = "",
int verbosity = 0,
string fname = "",
int lineno = 0 );
Get the string value of
option name. Output is_set
option's string representation if
it exists; returns the dflt
argument if not.
function int
get_int (
string name,
int dflt = 0,
string doc = "",
int verbosity = 0,
string fname = "",
int lineno = 0 );
Inquire about int-valued
option name. Output is_set
function void
get_range (
string name,
output int min, max,
input int dflt_min, dflt_max,
string doc = "",
int verbosity = 0,
string fname = "",
int lineno = 0 );
Inquire about range-valued
option name. Fills in min and
max with the option value if it
exists; or with the dflt_*
arguments if not.
function vmm_object
get_obj (
output bit is_set,
input string name,
vmm_object dflt = null
input string doc = "",
input int verbosity = 0,
string fname = "",
int lineno = 0 );
Inquire about vmm_object-
valued option name. Output
is_set indicates whether
there is any such option.
Returns the option value if it
exists; returns the dflt
argument if not.

Obtaining information about options
The get_help method can be called at any time to report information not only
on options that have been set, but on options that have been requested (whether
successfully or not) by the specified object. For requested options,
documentation as supplied in the most recent get_xxx call is reported.
If the +vmm_opts+help or +vmm_help option is specified, the top-level
vmm_env will report this automatically during the reset_dut() phase and then
invoke $finish so that the test does not run. This is a simple way to debug the
interaction between requested and specified options in your testbench.
vmm_opts
function void
get_help(
int verbosity = 0);
Use the option database's vmm_log
instance to report information on the
options applicable to the specified
vmm_object, or global options if no
object is specified.
Members
static vmm_log log; Log instance used by the options service
to report errors and help text.
Example
A transactor picking up a configuration feature from an option:
class DDR2_monitor extends vmm_xactor;
...
bit cfg_MobileDDR2_mode = 0;
...
function void configure_ph();
bit is_set, tmp;
`vmm_note(log, "Configuring DDR2_monitor");
tmp = vmm_opts::get_object_bit (
is_set, this, "MobileDDR2",
"Enable DDR2 Mobile features", 0, // doc, verbosi ty
`__FILE__, `__LINE__); // debug support
if (is_set) // keep default if not set
cfg_MobileDDR2_mode = tmp;
...
end : configure_ph

Create an instance, mem_mon, of this transactor in a subenv:
class DDR2_interface_env extends vmm_subenv;
...
DDR2_monitor mem_mon;
...
...
mem_mon = new("DDR2_mon", "mem_mon");

vmm_opts
In an options file optsfile.txt, reconfigure this option:
...
+MobileDDR2=1@%mem_mon
...

On the command line, specify this option file:
vcs +vmm_opts_file+optsfile.txt ...
Tips
Options can be used to control the configuration of the testbench, to choose
which test to run (see vmm_test) and to pass any user-specified
information to any part of the testbench. Typically, a testbench
component's configure_ph or build_ph method should search the
options database for any applicable options, and use their values to
determine how it should proceed.
It is safe to use get_string to query the value of any option. You wi ll get
a string representation of the option's value (although this is the empty
string for object-valued options).
When calling the option get/set methods, use Verilog's built-in macros
`__FILE__ and `__LINE__ to fill in the fname and lineno arguments
respecti vely. This allows VMM to provide diagnostic and report messages
that meaningfully describe the place in your source code where options are
set and used, making debugging much easier.
Option-related diagnostic and trace information is written through the option
service's own log instance, vmm_opts::log. Configure this log instance
to control how option-related messages appear in your simulation.
In the set_type*() methods, the name argument can include a hierarchy
match pattern using the form "PATTERN:name" (see Name Matching)
Gotchas
Detection of the presence or absence of an option works differently for
different ways of querying the option. The get_bit() method returns a
flag indicating whether the option has been set; if you wish to check the
value of a bit-valued option, you should use the get_int() method.
Global get_xxx methods mostly use a default value for an option that has
not been specified, whereas the get_object_xxx methods have an
output argument that indicates whether the option was set for that particular
object.
If you try to query an option for a value type other than a string when the
option has been set to a different type (e.g. calling get_range on an
vmm_opts
option that was set using set_object) the results are undefined, and
there may even be a fatal runti me error.
In calls to get_help(), higher values of verbosity give rise to more
verbose output. In calls to the set/get methods, higher values of
verbosity make it less likely that help on the chosen option will appear.
Help on an option wi ll be displayed only if the verbosity specified in your
call to get_help() is numerically greater than or equal to the value
specified in the most recent get/set operation on that option.
On the command line, there can be only one +vmm_opts argument
(although it can specify many options separated by +). If it appears more
than once, only the first occurrence is taken into account. Similarly, after an
option of the form +vmm_something has appeared once on the command
line, any subsequent appearance of the same option wi ll be ignored. This
is a limitation of the Verilog $plusargs mechanism. It can be worked
around by using an options file specified using the +vmm_opts_file
command-line option; within the options file, a given option can appear
multiple times and all its occurrences will take effect.
The get_xxx methods search for applicable options in their order of
appearance; the first applicable option is used. Consequently it is important
to ensure that the most specific options (those that apply to a particular
object) are listed first, and more general options are specified later. Given
this specification:
+vmm_opts+choice=stress+choice=special@%driver
any object, even if it matches the name pattern @%driver, will see the
value stress for option choice.
See also
Configuration Macros, vmm_object, vmm_test
Phases
The steps or sequence of events that a si mulation progresses through during a
testcase si mulation are referred to as phases. Phases provide a synchronisation
mechanism between acti vities across the various testbench components.
VMM offers two types of phasing: (1) explicit and (2) implicit. Explicit phasing
means that the user must explicitly invoke the corresponding methods for the
desired phase. For example, calling the build() method on vmm_xactors
explicitly starts the bui ld phase.
Implicit phasing is accomplished automatically using a vmm_unit or
vmm_group. When a test is started by calling
vmm_simulation::run_tests, the simulation proceeds by calling a
predefined sequence of functions and tasks on every component. During each
phase, the corresponding callback function or task in each unit in the hierarchy is
invoked in either a top-down, forked, or bottom-up order (depending on the
phase). It is also possible for users to create custom phases which can be
inserted into the standard VMM phase sequence.
Both explicit and implicit phasing can be mi xed together in the same
environment. Whether to use one or another is a matter of preference, but the
VMM User Guide offers the following practical guidelines:

Explicit Phasing Implicit Phasing
Reuse Reusable, but phases
must be manually
invoked at the right
place in the environment
Easy vertical reuse
Ease of Use Well-defined, but need
to know transactor
controls
Easy to use with little
know-how required
Fine grain control Full user control Call order controlled
automatically so less
user control

In addition to phases, VMM uses the notion of timelines to control the order of its
phase execution. By default, there are three main ti melines, which execute in
sequential order: (1) pre-test, (2) top-level test, and (3) post-test. Each timeline
contains a subset of the overall VMM phases. All vmm_units or vmm_groups
execute the different phases and ti melines, except for vmm_test, which only
executes the top-test ti meline. Moreover, the top-test ti meline may execute
multiple times if multiple tests are specified for a given simulation run.
Phases
Standard VMM Phases
Pre-Test Timeline
Explicit
Phase
Implicit
Phase
Type Order Method Main Activity
gen_
config
rtl_config function top-
down
rtl_config_ph Create or read
RTL config-
uration
build build function top-
down
build_ph Instantiate
environment
components
configure function top-
down
configure_ph Configure
components
connect function top-
down
connect_ph Make TLM and
channel
connections

Top-Test Timeline
Explicit
Phase
Implicit
Phase
- configure_
test
function top-
down
config_
test_ph
Test-specific
configurations
- start of
sim
function top-
down
start_of_
sim_ph
Initialization of
components
reset reset task forked reset_ph
(if unit
enabled)
disable_ph
(if unit
disabled)
Perform DUT
reset
training task forked training_ph Phase for
training
interfaces and
components
cfg_dut config_dut task forked config_
dut_ph
DUT
configuration
sequences or
multi-stream
scenarios.

Phases
start start task forked start_ph Start of
generators,
transactors, etc.
start_of_
test
function top-
down
start_of_
test_ph
Initial test
actions.
wait_for
_end
run_test task forked run_ph Test execution.
stop shutdown task forked shutdown_
ph
Stop all
transactors.
cleanup cleanup task forked cleanup_ph Any test cleanup
or state restore
for next test
execution.
report report function top-
down
report_ph Custom report
messages on
test status.

Post-Test Timeline
Explicit
Phase
Implicit
Phase
- final function top-
down
final_ph Final summary
report and
cleanup.
See also
vmm_ti meline
vmm_phase
The vmm_phase class provides methods that allow a program to extract
information about the state of a specified simulation phase as it is executed.
Member events are provided that can be used to wait until the phase begins or
ends.
A vmm_phase object is accessed by calling the get_phase function of a
timeline, gi ving the name of the phase as an argument.
Declaration
virtual class vmm_phase extends vmm_object;
Methods
get_typename();
Returns the string
"vmm_phase"
function string get_name(); Returns the name of the
associated phase
function vmm_timeline
get_timeline();
timeline containing this phase
function vmm_phase
previous_phase();
phase in this timeline
function vmm_phase
next_phase();
phase that will run next in this
timeline
function bit is_running(); Returns 1b1 if the phase is
currently running
function int is_done(); Returns the number of times
that the phase has completed
function int is_aborted(); Returns the number of times
that the phase has been
aborted
function int is_skipped(); Returns the number of times
that the phase has been
skipped.
Members
event started; Triggered when execution of
the phase starts
event completed; Triggered when execution of
the phase is complete

vmm_phase
Example
initial begin
vmm_timeline pretest_tl;
vmm_phase ph;

pretest_tl = vmm_simulation::get_pre_timeline();
ph = pretest_tl.get_phase("start_of_sim");

fork
@(ph.started)
`vmm_note(log,"start_of_sim");
join_none;
...
end
Tips
Get a handle to a vmm_phase by calling get_phase of a timeline (as
above)
For basic interactions with phases, consider using the member functions of
vmm_timeline instead
Gotchas
Make sure the phase name is spelt correctly when calling get_phase.
See also
vmm_*_phase_def, Phases, vmm_ti meline, vmm_si mulation
vmm_*_phase_def
VMM 1.2 includes several pre-defined classes deri ved from vmm_phase_def
that implement the behaviour required by commonly-used phases. These
should be used as base classes for user-defined phase definition classes in
preference to vmm_phase_def (where appropriate). There are 3 particular pre-
defined phases of interest: (1) vmm_topdown_function_phase_def, (2)
vmm_bottomup_function_phase_def, and (3) vmm_fork_task_phase_def. A top-
down phase is one that is invoked on components from the top of the hierarchy
downwards. The bottom-up phase works in the reverse direction. Lastly, the
forked task phase is used when a phase needs to be a task and be forked off
separately (e.g., to consume time).
Declaration
virtual class vmm_topdown_function_phase_def
#(type T = int) extends vmm_phase_def;
Methods
get_typename();
Returns "
vmm_topdown_function_phas
e_def"
pure virtual function void
do_function_phase(
T obj);
Must override to call
appropriate member function
of obj
Declaration
virtual class vmm_bottomup_function_phase_def
#(type T = int) extends vmm_phase_def;
Methods
get_typename();
Returns "
vmm_bottomup_function_phas
e_def"
do_function_phase(
T obj);
appropriate member function
of obj

vmm_*_phase_def
Declaration
virtual class vmm_fork_task_phase_def #(type T = int)
extends vmm_phase_def;
Methods
get_typename();
Returns "
vmm_fork_task_phase_def"
pure virtual task void
do_task_phase(
T obj);
appropriate member task of
obj
Declarations
class vmm_null_phase_def #(type T = int)
class vmm_start_xactor_phase_def #(
type T = vmm_xactor, string name = "/./",
string inst = "/./") extends vmm_xactor_phase_def;
class vmm_stop_xactor_phase_def #(
type T = vmm_xactor, string name = "/./",
string inst = "/./")
class vmm_reset_xactor_phase_def #(
type T = vmm_xactor, string name ="/./",
string inst = "/./")
Example
// class with extra phase
class my_unit extends vmm_env;
`vmm_typename(my_exp)
...
// method for phase
virtual task my_ph();
#10 `vmm_note(log,"my_phase");
endtask
endclass
vmm_*_phase_def
// create a user-defined phase definition class
class my_ph_def extends vmm_fork_task_phase_def #(my_unit);
`vmm_typename(my_ph_def)
virtual task do_task_phase(my_unit obj);
if(obj.is_enabled())
obj.my_ph();
endtask
endclass
See also
vmm_phase, vmm_ti meline, Phases
Register Abstraction Layer (RAL)
The Register Abstraction Layer (RAL) is a VMM application package for
describing design registers at a high-level so that they may be automatically
generated. RAL provides a rich set of built-in register methods and features and
provides a suite of standard register tests. For complete detai ls on RAL, refer to
Synopsys VMM Register Abstraction User Guide or VMM Primer: Using the
Register Abstraction Layer in VMM Primers.
RAL has its own register definition syntax called RALF that is based on the Tcl
scripting language. Standard Tcl commands may be used and multiple RALF
files can be included using Tcls source command. The following provides a
summary of the RALF syntax.
Common Tcl Syntax
# Comment Comment
set name value Sets variable name to value
source filename Reads in the specified Tcl file
for {set i 0} {$i < n} {incr i}
...
}
For loop
if ( $var ) {
...
}
If statement

RALF Syntax
field defines a register field
field name {
properties
}
Properties
bits n; Number of bits.
access
rw|ro|wo|w1|ru|w1c|rc|a1|a0|oth
er|user0|user1|user2|user3|dc;
Writeable (rw), read-only (ro),
write-only (wo), write-once
(w1), read-only with design
update (ru), write 1 to clear
(w1c), clear on read (rc), auto-
set by design (a1), auto-
cleared by design (a0), other
(other), user-defined (user0-3),
dont care (dc).
reset|hard_reset value; Hard reset value.
soft_reset value; Soft reset value.
constraint name [{
expression
}]
Sets a constraint on field
values.
Use value to refer to a field
value.
Must be valid SystemVerilog
syntax.
enum { name[=val], ... } Symbolic name for field values
cover +|- b|f Turns on/off field coverage.
+ | - Include / exclude:

b = bits from register-bit
coverage
f = fields value is a coverage
goal
coverpoint {
bins name [[[n]]] = {
n|[n:n], ... } | default
}
Defines bins for field value
coverage.
syntax.

register defines a register
register name {
properties
}
Properties
attributes {
name value [, ...]
}
List of name-value pairs
specifying user-defined
attributes
bytes n; Number of bytes in the register
constraint name [{
expression
}]
values.
Use fieldname.value to
refer to a field value.
syntax.
cover +|- a|b|f Turns on/off register coverage.
+ | - Include / exclude:

a = address from address map
b = bits from register-bit
coverage
f = fields from field value
coverage
cross name, [{
label name
}]
Cross-coverage point.
Label required if used in
another cross-coverage point.
field name[=rename]
[(hdl_path)] [@bit_offset];
OR
field name [(hdl_path)]
[@bit_offset] {
field properties
}
Defines a specific register
field.
Use name of unused or
reserved to skip bits.
hdl_path represents
hierarchical path to register for
backdoor access.
bit_offset direction relati ve
to left_to_right value.
left_to_right; Concatenate fields from left to
right (the default is reverse).
shared [(hdl_path)]; Register is physically shared
wherever it is instantiated.
hdl_path represents
backdoor access.

regfile register file to define a group of registers
regfile name {
properties
}
Properties
constraint name [{
expression
}]
values.
syntax.
cover +|- a|b|f Turns on/off register file
coverage.
+ | - Include / exclude registers
from:
a = address map coverage
b = register bits coverage
f = field value coverage
register name[=rename] [[n]]
[(hdl_path)] [@offset]
[read|write];
OR
register name[[n]] [(hdl_path)]
[@offset] {
field properties
}
Instances of a previously
defined register.
name must be unique.
An index [n] indicates a
register array.
hdl_path represents
backdoor access. Register
arrays must contain the %d
placeholder for the index.
offset may be specified as
@none.
Cannot contain the shared
property.

memory defines a memory
memory name {
properties
}
Properties
attributes {
name value [, ...]
}
attributes
access rw|ro; RAM (rw) or ROM (ro).
bits n; Number of bits in each
memory location.
Required property.
cover +|- a Turns on/off memory addres
coverage.
doc {
text
}
HTML comment for the
memory.
initial x|0|1|addr|literal[++|-
-];
Initial memory contents:
x = unknowns (default)
0 = zeros
1 = ones
addr = physical address value
literal = constant value ( ++
incrementing or --
decrementing)
Initialized by vmm_ral_mem::
initialize().
shared [(hdl_path)];

virtual register register across memory locations by combining virtual fields
virtual register name {
properties
}
Properties
bits n; Number of bits in each
memory location.
field name[=rename]
[@bit_offset];
OR
field name [@bit_offset] {
bit n;
[doc {
text
}]
}
Virtual field of the specified bits
at bit offset.

At least one field property is
required.
left_to_right; Concatenate fields from left to
right (the default is reverse).

block define a set of registers and memories
block name {
properties
}
OR

block name {
domain name {
properties
}
domain name {
properties
}
[doc {
text
}]
}
Properties
attributes {
name value [, ...]
}
attributes
bytes n;

Number of concurrent byte
accesses through physical
interface.
Required property.
constraint name [{
expression
}]
values.
syntax.
Cannot constraint memory or
virtual register contents.
cover +|- a|b|f Turns on/off register and
memory coverage in this block
(in this domain).
+ | - Include / exclude from:
endian
little|big|fifo_ls|fifo_ms;
Register endianess.
Default little endian.
memory name[=rename]
[read|write];
OR
memory name [(hdl_path)]
[@offset] {
properties
}
Previously defined memory.
hdl_path represents
property.
register name[=rename] [[n]]
[read|write];
OR
register name[[n]] [(hdl_path)]
[@offset] {
properties
}
Instances of a previously
defined register.
An index [n] indicates a
register array.
hdl_path same as above.
offset may be specified as
@none.
property.
regfile name[=rename] [[n]]
[(hdl_path)] [@offset] [+incr];
OR
regfile name[[n]] [(hdl_path)]
[@offset] [+incr] {
properties
}
Previously defined register file.
+incr represents the
increment amount.
Other options same as above.

virtual register name[=rename]
[[n] mem@offset [+incr]];
OR
virtual register name[[n]
mem@offset [+incr]] {
properties
}
Previously defined virtual
register.
Options same as above.

system define a set of blocks or subsystems
system name {
properties
}
OR

system name {
domain name {
properties
}
domain name {
properties
}
[doc {
text
}]
}
Properties
attributes {
name value [, ...]
}
attributes
bytes n;

Number of concurrent byte
accesses through physical
interface.
Required property.
constraint name [{
expression
}]
values.
syntax.
Cannot constrain memory or
virtual register contents.
cover +|- a|b|f Turns on/off register and
memory coverage in this block
(in this domain).
+ | - Include / exclude from:
endian
little|big|fifo_ls|fifo_ms;
Register endianess.
Default little endian.
block
name[[.domain]=rename][[n]]
[(hdl_path)] @offset [+incr];
OR
block name[[n]] [(hdl_path)]
@offset [+incr] {
properties
}
Previously defined register file.
An index [n] indicates a block
array.
hdl_path represents
+incr represents the
increment amount.
system
name[[.domain]=rename][[n]]
[(hdl_path)] @offset [+incr];
OR
system name[[n]] [(hdl_path)]
@offset [+incr] {
properties
}
Previously defined virtual
register.
Options same as above.
RALF Example
register ctrl {
left_to_right;
field SOFT_RST;
field ENDIANESS;
field MODE {
bits 3;
reset 0x0;

constraint my_lmt {
value < 3h7;
}
}
field RDY;
attributes {
NO_RAL_TESTS 1,
RETAIN 1
}
...
}
memory memsys {
size 256;
bits 32;
}
block sub_system {
bytes 4;
endian little;

register ctrl ( subregs.ctrl1.DataOut,
subregs.ctrl2.DataOut ) {
field SOFT_RST { access w1c }
...
}
...
memory RAM ( sys.memsys ) @ 0x0100;
}
RAL Classes
RAL provides many classes to implement register abstraction layer. While it is
beyond the scope of this book to document the numerous classes in detai l, the
function prototypes and data members are listed here as a reference.
vmm_mam
typedef enum {
GREEDY,
THRIFTY
} alloc_mode_e;
typedef enum {
BROAD,
NEARBY
} locality_e;
vmm_mam_allocator default_alloc;
vmm_log log;
function vmm_mam_region for_each(
bit reset = 0);
function vmm_ral_mem get_memory();
function new(
string name,
vmm_mam_cfg cfg,
vmm_ral_mem mem = null);
function vmm_mam_cfg reconfigure(
vmm_mam_cfg cfg = null);
function void release_all_regions();
function void release_region(
vmm_mam_region region);
function vmm_mam_region request_region(
int unsigned n_bytes,
vmm_mam_allocator alloc = null,
string fname = "",
int lineno = 0);
function vmm_mam_region reserve_region(
bit [63:0] start_offset,
string fname = "",
int lineno = 0);

vmm_mam_allocator
int unsigned len;
vmm_mam_region in_use[$];
bit [63:0] min_offset;
bit [63:0] max_offset;
rand bit [63:0] start_offset;
constraint vmam_mam_allocator_valid;
constraint vmam_mam_allocator_no_overlap;
vmm_mam_cfg
rand bit [63:0] end_offset;
rand vmm_mam::locality_e locality;
rand vmm_mam::alloc_mode_e mode;
rand int unsigned n_bytes;
rand bit [63:0] start_offset;
constraint vmm_mam_cfg_valid;

vmm_mam_region
function new(
bit [63:0] start_offset,
bit [63:0] end_offset,
int unsigned len,
vmm_mam parent);
task burst_read(
output vmm_rw::status_e status,
input vmm_ral_mem_burst burst,
output bit [`VMM_RAL_DATA_WIDTH-1:0] value[],
input vmm_ral::path_e path = vmm_ral::DEFAULT,
input string domain = "",
input int data_id = -1,
input int scenario_id = -1,
input int stream_id = -1,
input string fname = "",
input int lineno = 0);
task burst_write(
input bit [`VMM_RAL_DATA_WIDTH-1:0] value[],
function bit [63:0] get_end_offset();
function int unsigned get_len();
function vmm_ral_mem get_memory();
function int unsigned get_n_bytes();
function bit [63:0] get_start_offset();
function vmm_ral_vreg get_virtual_registers();
task peek(
input bit [`VMM_RAL_ADDR_WIDTH-1:0] offset,
output bit [`VMM_RAL_DATA_WIDTH-1:0] value,
task poke(
input bit [`VMM_RAL_DATA_WIDTH-1:0] value,
task read(
function void release_region();
task write(
vmm_ral
typedef enum {
BFM,
BACKDOOR,
DEFAULT
} path_e;
typedef enum {
RW,
RO,
WO,
W1,
RU,
RC,
W1C,
A0,
A1,
DC,
OTHER,
USER0,
USER1,
USER2,
USER3
} access_e;
typedef enum {
QUIET,
VERB
} check_e;
typedef enum {
NO_ENDIAN,
LITTLE_ENDIAN,
BIG_ENDIAN,
LITTLE_FIFO,
BIG_FIFO
} endianness_e;
typedef enum {
HARD,
SOFT
} reset_e;
typedef enum {
NO_COVERAGE,
REG_BITS,
ADDR_MAP,
FIELD_VALS,
ALL_COVERAGE
} coverage_model_e;

vmm_ral_access
function new();
function void add_xactor(
vmm_rw_xactor xact,
string domain = "");
task burst_read(
input bit [`VMM_RAL_ADDR_WIDTH-1:0] start,
input bit [`VMM_RAL_ADDR_WIDTH-1:0] incr,
input bit [`VMM_RAL_ADDR_WIDTH-1:0] max,
input int n_beats,
output bit [`VMM_RAL_DATA_WIDTH-1:0] data[],
input vmm_data user = null,
input int n_bits = `VMM_RAL_DATA_WIDTH,
task burst_write(
input bit [`VMM_RAL_ADDR_WIDTH-1:0] start,
input bit [`VMM_RAL_ADDR_WIDTH-1:0] incr,
input bit [`VMM_RAL_ADDR_WIDTH-1:0] max,
input bit [`VMM_RAL_DATA_WIDTH-1:0] data[],
input vmm_data user = null,
virtual function bit get_by_name(
input string name,
output bit [`VMM_RAL_DATA_WIDTH-1:0] value);
function vmm_ral_block_or_sys get_model();
task read(
input bit [`VMM_RAL_ADDR_WIDTH-1:0] addr,
output bit [`VMM_RAL_DATA_WIDTH-1:0] data,
task read_by_name(
input string name,
virtual function bit set_by_name(
input string name,
input bit [`VMM_RAL_DATA_WIDTH-1:0] value);
function void set_model(
vmm_ral_block_or_sys model);
task write(
input bit [`VMM_RAL_ADDR_WIDTH-1:0] addr,
input bit [`VMM_RAL_DATA_WIDTH-1:0] data,
task write_by_name(
input string name,
task write_mem_by_name(
input string name,
vmm_ral_block
function int unsigned get_block_ID();
function new(
vmm_ral_sys parent,
string name,
string typename,
vmm_ral::endianness_e endian,
bit [`VMM_RAL_ADDR_WIDTH-1:0] base_addr,
string domain = "",
int cover_on = vmm_ral::NO_COVERAGE,
int has_cover = vmm_ral::NO_COVERAGE);
virtual function int unsigned get_block_or_sys_size(
virtual function void get_constraints(
ref string names[]);
virtual function vmm_ral_field get_field_by_name(
string name);
virtual function void get_fields(
ref vmm_ral_field fields[],
input string domain = "");
virtual function vmm_ral_mem get_mem_by_name(
string name);
virtual function vmm_ral_mem get_mem_by_offset(
bit [`VMM_RAL_ADDR_WIDTH-1:0] offset,
virtual function void get_memories(
ref vmm_ral_mem mems[],
virtual function vmm_ral_reg get_reg_by_name(
string name);
virtual function vmm_ral_reg get_reg_by_offset(
virtual function void get_registers(
ref vmm_ral_reg regs[],
virtual function vmm_ral_vfield
get_virtual_field_by_name(
string name);
virtual function void get_virtual_fields(
ref vmm_ral_vfield fields[],
virtual function void get_virtual_registers(
ref vmm_ral_vreg vregs[],
virtual function vmm_ral_vreg get_vreg_by_name(
string name);
virtual task mirror(
input vmm_ral::check_e check = vmm_ral::QUIET,
virtual function bit needs_update();
virtual function string psdisplay_domain(
string prefix = "",
virtual function void ral_power_down(
bit retain = 0);
virtual function void ral_power_up(
string power_domains = "");
virtual task readmemh(
string filename);
string domain = "",
vmm_ral::reset_e kind = vmm_ral::HARD);
protected virtual function void sample(
bit [`VMM_RAL_ADDR_WIDTH-1:0] addr,
int domain);
virtual function int set_cover(
int is_on);
virtual function bit set_offset(
virtual task update(
virtual task writememh(
string filename);
vmm_ral_block_or_sys
static vmm_log log;
vmm_ral::path_e default_access = vmm_ral::DEFAULT;
function new(
vmm_ral_sys parent,
string block_or_sys,
string name,
string typename,
string domain = "",
function int C_addr_of();
virtual function bit Xset_base_addrX(
vmm_ral_callbacks cbs);
virtual function bit can_cover(
int models);
virtual function void display_domain(
string prefix = "",
protected virtual function void domain_coverage(
string domain,
int idx);
virtual function void get_all_attributes(
ref string names[],
input bit inherited = 1);
virtual function string get_attribute(
string name,
bit inherited = 1);
virtual function bit [`VMM_RAL_ADDR_WIDTH-1:0]
get_base_addr(
function int unsigned get_block_or_sys_ID();
virtual function vmm_ral::path_e get_default_access();
protected function int get_domain_index(
string domain);
function void get_domains(
virtual function vmm_ral::endianness_e get_endian(
virtual function string get_external_domain(
string name);
virtual function string get_fullname();
string name);
virtual function int unsigned get_n_bytes(
static function int get_n_tops();
virtual function string get_name();
virtual function vmm_ral_sys get_parent();
virtual function string get_parent_domain(
string name);
static function vmm_ral_block_or_sys get_top(
int n = 0);
virtual function string get_type();
virtual function bit is_cover_on(
int is_on = vmm_ral::ALL_COVERAGE);
string prefix = "",
bit retain = 0);
string filename);
string domain = "",
virtual function void set_attribute(
string name,
string value);
int is_on);
string filename);

vmm_ral_env
vmm_ral_access ral;
function new(
string name = "RAL-Based Verif Env");
virtual task hw_reset();
(Inherited from vmm_env)
virtual task reset_dut();
(Inherited from vmm_env)
virtual task sw_reset(

vmm_ral_field
static vmm_log log;
constraint vmm_ral_field_valid;
function new(
vmm_ral_reg parent,
string name,
int unsigned size,
vmm_ral::access_e access,
bit [`VMM_RAL_DATA_WIDTH-1:0] reset,
logic [`VMM_RAL_DATA_WIDTH-1:0] soft_reset,
int unsigned lsb_pos,
bit is_rand = 0,
bit cover_on = vmm_ral::NO_COVERAGE);
vmm_ral_field_callbacks cb,
string fname = "",
int lineno = 0);
virtual function bit[`VMM_RAL_DATA_WIDTH-1:0] get(
string fname = "",
int lineno = 0);
virtual function vmm_ral::access_e get_access(
virtual function int unsigned get_lsb_pos_in_register();
virtual function int unsigned get_n_bits();
virtual function vmm_ral_reg get_register();
virtual function logic [`VMM_RAL_DATA_WIDTH-1:0]
get_reset(
virtual task peek(
output bit[`VMM_RAL_DATA_WIDTH-1:0] value,
virtual task poke(
input int scenario_id =- 1,
function void post_randomize();
virtual task post_read(
vmm_ral_field field,
ref bit [`VMM_RAL_DATA_WIDTH-1:0] rdat,
vmm_ral::path_e path,
string domain,
ref vmm_rw::status_e status);
virtual task post_write(
bit [`VMM_RAL_DATA_WIDTH-1:0] wdat,
string domain,
function void pre_randomize();
virtual task pre_read(
ref vmm_ral::path_e path,
ref string domain);
virtual task pre_write(
ref bit [`VMM_RAL_DATA_WIDTH-1:0] wdat,
ref string domain);
virtual function bit predict(
bit [`VMM_RAL_DATA_WIDTH-1:0] value,
string fname = "",
int lineno = 0);
vmm_ral_field_callbacks cb,
string fname = "",
int lineno = 0);
virtual task read(
extern virtual function logic [`VMM_RAL_DATA_WIDTH-1:0]
virtual function void set(
bit[`VMM_RAL_DATA_WIDTH-1:0] value,
string fname = "",
int lineno = 0);
virtual function vmm_ral::access_e set_access(
vmm_ral::access_e mode);
set_reset(
logic [`VMM_RAL_DATA_WIDTH-1:0] value,
vmm_ral_field_callbacks cb);
virtual task write(

vmm_ral_field_callbacks
string domain,
string domain,
ref string domain);
ref string domain);
vmm_ral_mem
typedef enum {
UNKNOWNS,
ZEROES,
ONES,
ADDRESS,
VALUE,
INCR,
DECR
} init_e;
static vmm_log log;
vmm_mam mam;
function new(
vmm_ral_block parent,
string name,
vmm_ral::access_e access,
longint unsigned size,
int unsigned n_bits,
string domain = "",
bit [1:0] rights = 2'b11,
bit unmapped = 0,
vmm_ral_mem_callbacks cb,
string fname = "",
int lineno = 0);
virtual task burst_read(
output bit [`VMM_RAL_DATA_WIDTH-1:0] value[],
virtual task burst_write(
input bit [`VMM_RAL_DATA_WIDTH-1:0] value[],
int models);
string prefix = "",
get_address_in_system(
bit [`VMM_RAL_ADDR_WIDTH-1:0] mem_addr = 0,
ref string names[],
string name,
bit inherited = 1);
function vmm_ral_mem_backdoor get_backdoor();
virtual function vmm_ral_block get_block();
virtual function void get_domains(
ref string domains[]);
function vmm_ral_mem_frontdoor get_frontdoor(
function int unsigned get_mem_ID();
function int unsigned get_n_bytes();
virtual function int get_n_domains();
get_offset_in_block(
bit [`VMM_RAL_ADDR_WIDTH-1:0] mem_addr = 0,
virtual function vmm_ral::access_e get_rights(
virtual function longint unsigned get_size();
string name);
ref vmm_ral_vfield fields[]);
ref vmm_ral_vreg regs[]);
string name);
virtual function vmm_ral_vreg get_vreg_by_offset(
bit [63:0] offset,
virtual task init(
output bit is_ok,
input init_e pattern,
input bit [`VMM_RAL_DATA_WIDTH-1:0] data);
int is_on = vmm_ral::ALL_COVERAGE);
virtual task peek(
input bit [`VMM_RAL_ADDR_WIDTH-1:0] mem_addr,
virtual task poke(
vmm_ral_mem_callbacks cb,
string fname = "",
int lineno = 0);
string prefix = "",
virtual function void ral_power_down();
virtual function void ral_power_up();
virtual task read(
string filename);
string name,
string value);
function void set_backdoor(
vmm_ral_mem_backdoor bkdr,
string fname = "",
int lineno = 0);
int is_on);
function void set_frontdoor(
vmm_ral_mem_frontdoor ftdr,
string domain = "",
string fname = "",
int lineno = 0);
vmm_ral_mem_callbacks cb);
virtual task write(
string filename);

vmm_ral_mem_backdoor
static vmm_log log;
virtual task read(
input int data_id,
input int scenario_id,
input int stream_id);
virtual task write(
input int data_id,

vmm_ral_mem_burst
rand bit [`VMM_RW_ADDR_WIDTH-1:0] incr_offset;
rand bit [`VMM_RW_ADDR_WIDTH-1:0] max_offset;
rand int unsigned n_beats;
rand bit [`VMM_RW_ADDR_WIDTH-1:0] start_offset;
vmm_data user_data;
vmm_ral_mem_callbacks
virtual task post_burst(
input vmm_ral_mem mem,
input vmm_rw::kind_e kind,
ref bit [`VMM_RAL_DATA_WIDTH-1:0] data[],
input vmm_ral::path_e path,
input string domain,
input vmm_ral_mem mem,
vmm_ral_mem mem,
string domain,
virtual task pre_burst(
vmm_ral_mem mem,
vmm_rw::kind_e kind,
vmm_ral_mem_burst burst,
ref bit [`VMM_RAL_DATA_WIDTH-1:0] wdat[],
ref string domain);
vmm_ral_mem mem,
ref bit [`VMM_RAL_ADDR_WIDTH-1:0] offset,
ref string domain);
vmm_ral_mem mem,
ref bit [`VMM_RAL_ADDR_WIDTH-1:0] offset,
ref string domain);

vmm_ral_mem_frontdoor
static vmm_log log;
virtual task burst_read(
output bit [`VMM_RAL_DATA_WIDTH-1:0] data[],
input int stream_id = -1);
virtual task burst_write(
input bit [`VMM_RAL_DATA_WIDTH-1:0] data[],
virtual task read(
virtual task write(

vmm_ral_reg
static vmm_log log;
function new(
string name,
string domain = "",
bit [1:0] rights = 2'b11,
bit unmapped = 0,
vmm_ral_reg_callbacks cb,
string fname = "",
int lineno = 0);
int models);
string prefix = "",
virtual function bit[`VMM_RAL_DATA_WIDTH-1:0] get(
string fname = "",
int lineno = 0);
ref string names[],
string name,
bit inherited = 1);
function vmm_ral_reg_backdoor get_backdoor();
string name);
ref vmm_ral_field fields[]);
function vmm_ral_reg_frontdoor get_frontdoor(
virtual function int unsigned get_n_bytes();
get_offset_in_block(
function int unsigned get_reg_ID();
get_reset(
int is_on);
virtual task peek(
virtual task poke(
input bit[`VMM_RAL_DATA_WIDTH-1:0] value,
vmm_ral_reg rg,
vmm_ral_reg rg,
string domain,
vmm_ral_reg rg,
ref string domain);
vmm_ral_reg rg,
ref string domain);
virtual function bit predict(
string fname = "",
int lineno = 0);
vmm_ral_reg_callbacks cb,
string fname = "",
int lineno = 0);
string prefix = "",
virtual task read(
virtual function void set(
string fname = "",
int lineno = 0);
string name,
string value);
function void set_backdoor(
vmm_ral_reg_backdoor bkdr,
string fname = "",
int lineno = 0);
int is_on);
function void set_frontdoor(
vmm_ral_reg_frontdoor ftdr,
string domain = "",
string fname = "",
int lineno = 0);
vmm_ral_reg_callbacks cb);
virtual task write(

vmm_ral_reg_backdoor
static vmm_log log;
virtual task read(
input int data_id,
virtual task write(
input int data_id,

vmm_ral_reg_callbacks
vmm_ral_reg rg,
vmm_ral_reg rg,
string domain,
vmm_ral_reg rg,
ref string domain);
vmm_ral_reg rg,
ref string domain);

vmm_ral_reg_frontdoor
static vmm_log log;
virtual task read(
virtual task write(

vmm_ral_sys
function new(
vmm_ral_sys parent = null,
string name,
string typename,
bit [`VMM_RAL_ADDR_WIDTH-1:0] base_addr = 0,
string domain = "",
virtual function void get_all_blocks(
ref vmm_ral_block blocks[],
ref string domains[],
virtual function void get_all_subsys(
ref vmm_ral_sys subsys[],
virtual function vmm_ral_block get_block_by_name(
string name);
virtual function vmm_ral_block get_block_by_offset(
virtual function void get_blocks(
ref vmm_ral_block blocks[],
string name);
string name);
string name);
virtual function void get_subsys(
ref vmm_ral_sys subsys[],
virtual function vmm_ral_sys get_subsys_by_name(
string name);
virtual function vmm_ral_sys get_subsys_by_offset(
function int unsigned get_sys_ID();
string name);
ref vmm_ral_vfield fields[],
string name);
virtual function vmm_ral_vreg get_vreg_by_offset(
string prefix = "",
bit retain = 0);
string filename);
string domain = "",
function int set_cover(
int is_on);
string filename);

vmm_ral_tests
`VMM_STATIC_M task bit_bash(
vmm_ral_block blk,
string domain,
vmm_log log);
`VMM_STATIC_M task hw_reset(
vmm_ral_block blk,
string domain,
vmm_log log);
`VMM_STATIC_M task mem_access(
vmm_ral_block blk,
vmm_log log);
`VMM_STATIC_M task mem_walk(
vmm_ral_block blk,
string domain,
vmm_log log);
`VMM_STATIC_M task reg_access(
vmm_ral_block blk,
vmm_log log);
`VMM_STATIC_M task shared_access(
vmm_ral_block blk,
vmm_log log);

vmm_ral_version
function int major();
function int minor();
function int patch();
function string vendor();

vmm_ral_vfield
static vmm_log log;
function new(
vmm_ral_vreg parent,
string name,
int unsigned size,
int unsigned lsb_pos);
vmm_ral_vfield_callbacks cb);
virtual function int unsigned get_lsb_pos_in_register();
virtual function vmm_ral_vreg get_register();
virtual task peek(
input longint unsigned idx,
virtual task poke(
vmm_ral_vfield field,
longint unsigned idx,
string domain,
string domain,
ref string domain);
ref string domain);
virtual task read(
virtual task write(

vmm_ral_vfield_callbacks
string domain,
string domain,
ref string domain);
ref string domain);

vmm_ral_vreg
static vmm_log log;
function new(
string name,
bit [`VMM_RAL_ADDR_WIDTH-1:0] offset = 0,
vmm_ral_mem mem = null,
longint unsigned size = 0,
int unsigned incr = 0);
virtual function vmm_mam_region allocate(
longint unsigned n,
vmm_mam mam);
vmm_ral_vreg_callbacks cb);
string prefix = "",
virtual function vmm_ral_vfield get_field_by_name(
string name);
ref vmm_ral_vfield fields[]);
virtual function int unsigned get_incr();
virtual function vmm_ral_mem get_memory();
virtual function int unsigned get_n_bytes();
virtual function int unsigned get_n_memlocs();
get_offset_in_memory(
longint unsigned idx);
virtual function vmm_mam_region get_region();
virtual function int unsigned get_size();
virtual function bit implement(
longint unsigned n,
vmm_ral_mem mem = null,
bit [`VMM_RAL_ADDR_WIDTH-1:0] offset = 0,
int unsigned incr = 0);
virtual task peek(
virtual task poke(
vmm_ral_vreg rg,
vmm_ral_vreg rg,
string domain,
vmm_ral_vreg rg,
ref string domain);
vmm_ral_vreg rg,
ref string domain);
string prefix = "",
virtual task read(
virtual function void release_region();
function void reset(
virtual task write(
input int lineno = 0;
vmm_ral_vreg_callbacks
vmm_ral_vreg rg,
vmm_ral_vreg rg,
string domain,
vmm_ral_vreg rg,
ref string domain);
vmm_ral_vreg rg,
ref string domain);

vmm_rw
typedef enum {
READ,
WRITE,
EXPECT
} kind_e;
typedef enum {
IS_OK,
ERROR,
RETRY,
TIMEOUT,
HAS_X
} status_e;

vmm_rw_access
rand vmm_rw::kind_e kind;
rand bit [`VMM_RW_ADDR_WIDTH-1:0] addr;
rand logic [`VMM_RW_DATA_WIDTH-1:0] data;
static vmm_log log;
rand int n_bits = `VMM_RW_DATA_WIDTH;
vmm_rw::status_e status;
constraint valid_vmm_rw_access;
function new(
vmm_object parent,
string name);

vmm_rw_burst
rand int unsigned n_beats;
rand bit [`VMM_RW_ADDR_WIDTH-1:0] incr_addr;
rand bit [`VMM_RW_ADDR_WIDTH-1:0] max_addr;
rand logic [`VMM_RW_DATA_WIDTH-1:0] data[];
vmm_data user_data;
constraint fifo;
constraint linear;
constraint reasonable;
constraint vmm_rw_burst_valid;
constraint wrap;
function new(
vmm_object parent,
string name);

vmm_rw_xactor
typedef enum {
BURST_DONE = 99990,
SINGLE_DONE
} notifications_e;
vmm_rw_access_channel exec_chan;
function new(
string name,
string inst,
int stream_id = -1,
vmm_rw_access_channel exec_chan = null);
protected virtual task execute_burst(
vmm_rw_burst tr);
protected virtual task execute_single(
vmm_rw_access tr);
protected virtual task main();
vmm_rw_xactor xactor,
vmm_rw_burst tr);
virtual task post_single(
vmm_rw_access tr);
vmm_rw_burst tr);
virtual task pre_single(
vmm_rw_access tr);
function void reset_xactor(
vmm_xactor::reset_e rst_typ = SOFT_RST);

vmm_rw_xactor_callbacks
vmm_rw_burst tr);
virtual task post_single(
vmm_rw_access tr);
vmm_rw_burst tr);
virtual task pre_single(
vmm_rw_access tr);
See also
Synopsys VMM Register Abstraction User Guide and VMM Primer
RTL configuration
Classes and macros to support configuration of your testbench to match the
parameters (bus width, number of ports etc) of the specific RTL hierarchy
currently under test.
This article outlines the relevant base classes, and indicates the steps you must
take to implement RTL configuration on your project. For details on the base
classes and how to extend them, see the indi vidual articles on vmm_rtl_config
and vmm_rtl_config_file_format.
Classes
class custom_config extends vmm_rtl_config;
class custom_format extends vmm_rtl_config_file_format;
Aims
Typical RTL designs under test have various bui ld options, set by conditional
compilation or by parameters. It is necessary to configure your VMM testbench
so that it matches the RTL configuration, which may have been randomized by a
build script, set by a configuration file or command line options, or determined by
some IP configuration mechanism such as DesignWare
TM
Implementation IP or
Accellera IP-XACT
TM
. vmm_rtl_config and associated classes provide a
customizable mechanism to support thi s requirement.
Key aims of the mechanism are:
Automate the synchronization between a set of RTL configuration control
files, which continue to exist outside the simulation, and the contents of
vmm_rtl_config configuration objects whose data members can be read
during the testbench's configuration phase.
Support both user-specified and industry-standard RTL configuration
control file formats through extensions of the file reader-writer class
vmm_rtl_config_file_format.
Usage
Supporting your chosen RTL configuration file format
vmm_rtl_config_file_format is a virtual class containing pure virtual
methods to open and close a configuration data file, and to read and write
named data items stored in that file. Example implementations are available
with the VMM1.2 distribution. The vmm_rtl_config class has a static data
member default_file_fmt of this type. You must define a class deri ved
from vmm_rtl_config_file_format to support your default file format, and
set vmm_rtl_config::default_file_fmt to be an instance of this class.
All configuration objects will use this file format by default.
RTL configuration
However, some vmm_rtl_config objects in the hierarchy may need to use a
different file format to read and write their configuration. This is supported by
providing a different derived class for each special file format. Any
vmm_rtl_config object that needs a custom file reader should have its data
member file_fmt set to an instance of the appropriate derived
vmm_rtl_config_file_format class.
Creating an RTL configuration object for each vmm_unit that needs it
For each command-level transactor (or other class derived from vmm_unit) that
must be configured to match the RTL, deri ve a configuration class from
vmm_rtl_config. This derived class should contain a rand data member to
represent each RTL-related configuration value required by the associated
component. It should also contain invocations of appropriate
`vmm_rtl_config_* macros for all these data members.
To compose multiple RTL configurations into an hierarchy corresponding to your
RTL and/or testbench component hierarchy, create parent configuration classes
derived from vmm_rtl_config and implement their build_config_ph()
method so that they construct and name the necessary child configuration
objects. RTL configuration objects are assembled into a distinct hierarchy,
separate from the main tree of vmm_unit instances. Parent configuration
objects can set their children's names in this hierarchy using the map_to_name
method. The resulting names are used to identify configuration objects in the
hierarchy, and to construct the filename of the configuration file read and written
by each object.
Specifying a set of RTL configuration files for a simulation run
RTL configuration is enabled by specifying a filename prefix using the command-
line option +vmm_opts+rtl_config=PREFIX or the alternati ve equi valent
+vmm_rtl_config=PREFIX. The vmm_rtl_config_file_format class
can use this prefix in any way it chooses, but conventionally the filename for a
vmm_rtl_config object's configuration is formed by concatenating this prefi x,
the object's name and some file extension string. Alternati vely the prefix could
be used to construct the name of a directory in which to find the configuration
files.
Respecting RTL configuration at the testbench configuration phase
In the configure_ph() method of each transactor or vmm_unit that needs
RTL configuration, use static method vmm_rtl_config::get_config() to
locate the configuration object that is appropriate to your transactor. The
transactor can then use values from this configuration object, just as it might
from any other configuration object. Its values have been automatically
populated from the RTL configuration file during the rtl_configure phase.
RTL configuration
Creating a set of RTL configuration files
Clearly the RTL configuration must be applied both to the RTL device under test
and to the VMM testbench. However, VMM can also create an RTL
configuration, by running the testbench with the +vmm_gen_rtl_config option
enabled. The RTL configuration files thus created can then be applied to both
RTL and testbench in the usual way.
Using the testbench to create RTL configuration means that the full power of
SystemVerilog randomization can be used. The +vmm_gen_rtl_config
option causes your VMM testbench to create and randomize all
vmm_rtl_config objects and then to write their contents to the appropriate
configuration files. If this option were not specified, randomization does not take
place and values are specified in your configuration files before simulation
proceeded to run the VMM test(s).
Tips
rtl_configure_ph is the first phase run by any component.
Consequently, all other phase methods can assume that RTL configuration
objects and data have been fully populated.
Running your testbench with the +vmm_gen_rtl_config option will write
a complete set of RTL configuration files reflecting the default or
constrained-random values of all your RTL configuration parameters.
These configuration files can then be edited to create alternati ve
configurations for future runs.
With appropriate random constraints on the configuration values, running
your testbench with +vmm_gen_rtl_config can be a useful way to
create randomi zed RTL configurations that can then be implemented in a
sample device under test.
Gotchas
Despite its flexibi lity and extensi ve automation, the RTL Configuration
mechanism cannot automate the synchronization of your testbench to the
actual RTL parameters used to construct the device under test. You are
strongly recommended to use a configuration file format (such as
IP-XACT
TM
, or perhaps simply a file containing a collection of Verilog
parameter declarations) that can also be used to control construction of the
RTL code.
The VMM 1.2 standard library distribution will include two concrete
implementations of the vmm_rtl_config_file_format virtual base
class. One is a si mple format reader-writer and the other supports XML
files (not yet implemented), including IP-XACT. You can either provide an
implementation to support your chosen file format, or else use one of the
sample implementations.
RTL configuration
See also
Phases, vmm_rtl_config, vmm_rtl_config_file_format
vmm_rtl_config
Base class for objects containing information about the parameterization of all or
part of the RTL design under test. General usage of vmm_rtl_config is
described in the article on RTL Configuration. This article describes how to
extend the base class for your specific application.
Declaration
class vmm_rtl_config extends vmm_object;
Methods
function new(
string name="",
vmm_rtl_config parent=null);
The base class constructor
adds the new instance to the
vmm_object hierarchy, and
creates a log instance.
function void map_to_name(
string name);
Aliases this object, with the
specified name. The
configuration object wi ll be
known by its new name when
another object searches the
hierarchy for its applicable
RTL configuration object (see
get_config method below)
build_config_ph();
Sub-phase method,
automatically executed as part
of the main rtl_configuration
phase. Override this method
to allow a config object to
create and name its children.
static function vmm_rtl_config
get_config(
vmm_object uobj,
string fname = "",
int lineno = 0 );
Get a handle to the RTL config
object whose name (in the
configuration namespace) is
identical to the specified
object's name.
get_config_ph();
Sub-phase methods,
automatically executed as part
of the main rtl_configuration
phase. These methods are
automatically implemented by
the macros (see below) and
there is no need to override
them in user code.
save_config_ph();
vmm_rtl_config
Members
vmm_log log; Log instance for this object.
user code might write to this
log instance in an overridden
build_config_ph method.
static
vmm_rtl_config_file_format
default_file_fmt;
The default config file
reader/writer, used by a
vmm_rtl_config object if its
own file_fmt member is null
protected
file_fmt;
Instance-specific config file
reader/writer instance.
Needed only for config
instances that use a non-
standard file format.
typedef
enum {LOAD, SAVE} mode_e;
This enum type is used in
macro-automated calls to
methods of the vmm_rtl_-
config_file_format class,
and is used only when
overriding virtual methods of
that class.
Macros
`vmm_rtl_config_begin
(classname)
`vmm_rtl_config_end
(classname)
Introduce/close the automation
macro block. The classname
argument should be exactly
the name of the deri ved class.
Used correctly, these and the
following macros completely
automate the i mplementation
of all methods of a derived
class except the constructor
and build_config_ph.
`vmm_rtl_config_boolean
(name, fname)
`vmm_rtl_config_int
(name, fname)
` vmm_rtl_config_obj
(name)
`vmm_rtl_config_string
(name, fname)
Automate the management of
data member name in the RTL
configuration file. Within that
file, the corresponding
parameter is known by the
name fname.
vmm_rtl_config
Example
RTL configuration for a leaf instance having just one parameter. The
parameter's name, as it appears in the external configuration text file, is
COUNT_LIMIT. Within the configuration object its data member name is limit.
class simple_xactor_rtlcfg extends vmm_rtl_config;
rand int limit;
constraint default_limit { limit == 1023; }
function new (string name = "",
super.new(name, parent);
endfunction
// no custom build method needed
`vmm_rtl_config_begin(simple_xactor_rtlcfg)
`vmm_rtl_config_int(limit, COUNT_LIMIT)
`vmm_rtl_config_end(simple_xactor_rtlcfg)
endclass
Tips
Create a hierarchy of vmm_rtl_config-derived objects that shadows (but
is not necessarily identical to) the hierarchy of vmm_unit-derived objects
that form the testbench structure. Choose mapped names for the RTL
configuration objects that match the corresponding part of the uni t
hierarchy, so that any unit can locate its configuration object by name.
Gotchas
In a parent configuration object, dont forget to use map_to_name() so
that each child configuration object gets a name matching the complete
relati ve path from the parent configuration's corresponding unit to the child
configuration's unit. This cannot be automated, because configuration
objects li ve in a distinct hierarchy that is not necessarily identical to the unit
hierarchy.
See also
RTL Configuration, vmm_object, vmm_unit
Virtual base class for a custom RTL configuration file reader/writer. General
usage of vmm_rtl_config is described in the article on RTL Configuration.
This article describes how to extend the file reader/writer base class to support a
specific text file format.
Declaration
virtual class vmm_rtl_config_file_format;
Methods
pure virtual function
bit fopen (
vmm_rtl_config cfg,
string mode,
string fname = "",
int lineno = 0);
Override this method to gain access to
the appropriate RTL configuration file
for the specified object cfg, using the
mode string to choose whether to open
for reading or writing. Arguments
fname and lineno can be expected
to contain the source file and line
number of the call, for debug
purposes. Return 1 or 0 to indicate
success or failure respectively.
pure virtual function bit
read_bit (
string name,
output bit value );
read_int (
string name,
output int value );
read_string (
string name,
output string value );
Override these methods to read
named parameter values from the
already-opened file. Implementations
can assume that the file has already
been opened for reading by a
successful call to fopen.
write_bit (
string name,
bit value );
write_int (
string name,
int value );
write_string (
string name,
string value );
Override these methods to write
named parameter values to the
already-opened file. Implementations
can assume that the file has already
been opened for writing by a
successful call to fopen.
fclose();
Override this method to close the
already-opened configuration file and
clean up any cached data maintained
by this class.
Members
The virtual base class vmm_rtl_config_file_format has no data members.
Derived classes are free to add data members to support caching of file data or
for other purposes.
Tips
There is a sample implementation of a file reader/writer in the examples
supplied with the VMM 1.2 distribution.
Implementations can assume that, once a file has been opened, it wi ll be
read or written and then closed before any other RTL configuration file is
opened.
Gotchas
The vmm_rtl_config class has a static data member file_ptr that
should be used by any vmm_rtl_config_file_format object to store
its Verilog file identifier; the automation macros in vmm_rtl_config
depend on this variable being used correctly. Consequently, any
implementation of vmm_rtl_config_file_format should use this
variable to store the currently active file identifier.
There is only one instance of the default file format, held in the static handle
vmm_rtl_config::default_file_fmt. This instance is shared by all
vmm_rtl_config objects that use the default.
See also
RTL Configuration, vmm_rtl_config
vmm_sb_ds
A vmm_sb_ds class constructs the data stream scoreboard object used for
checking in a VMM environment. By default, a data stream scoreboard receives
a single stream of transaction (or packet) input and the corresponding data is
sent for comparison. Data sent to the scoreboard is automatically placed in the
expected queue, and comparisons are performed in one of three ways: (1) in-
order, (2) in-order with losses, and (3) out-of-order.

In-order comparison means that the expected and actual data should be in the
same order when making a match. When losses are expected, bad or bogus
data may be sent to the scoreboard with the comparison happening by
traversing through the queue, discarding bad data until a match is found. With
out-of-order comparison, data in the input stream can be in any order and the
queue is search for the first match. Matching is accomplished by using the
macro or user-defined compare() method of the transaction objects. When
comparing with losses, a match()method is also used before compare().

Type Packet order
Compare
method
Scoreboard method
In-order Same order compare() expect_in_order()
With Losses
Same order
with extra
loss data
match()
compare()
expect_with_losses()
Out-of-order Any order compare() expect_out_of_order()

A data stream scoreboard can also handle multiple streams of expected input or
actual data output from a design. With multiple streams, the three methods of
comparisons can be performed, but now multiple queues or streams are used.
Users must extend the scoreboard and explicitly specify a stream_id()
method for identifying the appropriate stream to store or compare the data.
Likewise, the additional stream id arguments of the expect methods should be
used. (Note that the input stream id may be different than the expected queue
id).
Navi gating through the various scoreboard queues is accomplished by using the
stream and scoreboard iterators (see vmm_sb_ds_*iter).). These are
Scoreboard(vmm_sb_ds)
compare()
Packet
inp_stream_id
exp_stream_id
kind
insert( )
INPUT
EXPECT
transform()
pkt pkt
pkt pkt pkt
pkt
exp_stream_id
Expected Queue(s)
Single stream
expect_*( )
Packet
inp_stream_id
exp_stream_id
Search
Match
& remove
vmm_sb_ds
particularly useful when trying to locate, insert, or discard a packet within the
various queues. Packets can also be transformed using the transform()
method. For example, packets can be expanded, compressed, or translated
from one protocol to the next. Furthermore, scoreboard callbacks can be
registered to extend the scoreboards functionali ty (see
vmm_sb_ds_callbacks).
Scoreboards are typically integrated within an environment using callbacks or by
forking off a thread in the environment to sink channel packets into the
scoreboard. They may also be used to listen to analysis ports. Integration of
scoreboards wi th environments, channels, or notify objects is simplified by
defining the compile time macro, `VMM_SB_DS_IN_STDLIB. . This macro
enables the scoreboard registration functions.
For more examples, detai ls, and descriptions, please see the Synopsys VMM
Scoreboarding User Guide deli vered with the VMM Scoreboard Package
Declaration
class vmm_sb_ds_typed #(type INP = vmm_data , type EXP =
INP) extends vmm_sb_ds_base;

class vmm_sb_ds extends vmm_sb_ds_typed #(vmm_data);;
Methods
function new(
string name);
Constructor.
vmm_sb_ds_callbacks
#(INP,EXP) cb);
Adds the specified callback to
the scoreboard.
virtual function bit compare(
EXP actual,
EXP expected);
Compares two transaction
objects.
Returns TRUE if a match.
function void define_stream(
int stream_id,
string descr = "",
vmm_sb_ds::kind_e kind
= EITHER);
Pre-defines a data stream wi th
the specified stream ID.
kind can be INPUT, EXPECT,
or EITHER.
describe();
Displays any defined
scoreboard streams.
Displays the scoreboard's
contents.
vmm_sb_ds
expect_in_order(
EXP pkt,
int exp_stream_id = -1,
int inp_stream_id = -1,
bit silent = 0);
Compares expected packet
pkt with first input stream
packet.
Removes and returns packet if
matched.
Error message is not issued if
silent specified.
expect_out_of_order(
EXP pkt,
int inp_stream_id = -1,
bit silent = 0);
pkt with all packets in a
stream.
Removes and returns packet if
matched.
silent specified.
expect_with_losses(
input EXP pkt,
output EXP matched,
output EXP lost[],
input int exp_stream_id = -1,
input int inp_stream_id = -1,
input bit silent = 0);
pkt with next packet in
stream, removi ng unmatched
packets as losses.
Returns packet if matched.
silent specified.
Requires the
quick_compare() method.
virtual function void flush(); Resets and flushes all
contents of the scoreboard.
function int get_n_dropped(
int inp_stream_id = -1);
dropped packets for the
specified stream(s).
function int get_n_inserted(
expected packets inserted into
the specified stream(s).
function int get_n_matched(
matched expected packets.
function int get_n_mismatched(
Returns the number of lost
mismatched expected
packets.
function int get_n_not_found(
expected packets not found in
the scoreboard.
vmm_sb_ds
function int get_n_orphaned(
Returns the number of leftover
packets in the scoreboard.
function int get_n_pending(
expected packets sti ll in the
scoreboard.
virtual function bit insert(
vmm_data pkt,
= INPUT,
Inserts packet into the
scoreboard in the specified
stream(s).
Returns TRUE if successful.
kind can be INPUT, EXPECT,
or EITHER.
virtual function bit match(
EXP actual,
EXP expected);
Performs a quick compare to
see if the data packets match.
Returns TRUE if matched.
function vmm_sb_ds_iter
new_sb_iter(
Creates and returns a
scoreboard iterator for
traversing across all the
scoreboard streams.
function vmm_sb_ds_stream_iter
new_stream_iter(
Creates and returns a stream
iterator for traversing a stream
for a particular packet.
vmm_sb_ds_callbacks
#(INP,EXP) cb);
callback to the registered
callbacks.
quick_compare(
EXP actual,
EXP expected);
Performs a quick compare to
see if two packets match.
Returns TRUE if matched.
By default, returns TRUE.
virtual function bit remove(
vmm_data pkt,
= INPUT,
Removes the specified packet
from the specified stream(s).
Returns TRUE if successful.
All packets created by
transform() are also
removed.
kind can be INPUT or
EXPECT.
virtual function void report(
Displays the scoreboard
statistics.
vmm_sb_ds
virtual function int stream_id(
vmm_data pkt,
= EITHER);
User-definable function for
determining a packets stream
id.
Returns stream id.
virtual function bit transform(
input EXP in_pkt,
output EXP out_pkts[]);
Recei ves a data packet and
transforms it into one or more
packets.
Returns an array of packets.
function void
vmm_sb_ds_callbacks
#(INP,EXP) cb);
Unregisters a scoreboard
callback.
Members
vmm_tlm_analysis_export_exp#(vm
m_sb_ds_typed#(INP,EXP),EXP)
exp_ap;
Expect analysis export.
typedef enum {
EITHER,
INPUT,
EXPECT
} kind_e;
Stream kind enumeration.
vmm_tlm_analysis_export_inp#(vm
m_sb_ds_typed#(INP,EXP),INP)
inp_ap
Input analysis export.
vmm_log log; Message service instance.
typedef enum {
INSERTED = 999_000,
EMPTY,
MATCHED,
MISMATCHED,
DROPPED,
NOT_FOUND,
ORPHANED
} notifications_e;
vmm_notify notify; Notification service instance.
typedef enum {
IN_ORDER,
WITH_LOSSES,
OUT_ORDER
} ordering_e;
Scoreboard ordering
enumeration.
vmm_sb_ds
Macros
`VMM_SB_DS_IN_STDLIB Enables scoreboard
integration methods.
Example
class usb_scoreboard extends vmm_sb_ds;
function new();
super.new( "USB Scoreboard" );
define_stream( 0, "CPU", INPUT );
define_stream( 1, "USB1", EXPECT );
define_stream( 2, "USB2", EXPECT );
endfunction

virtual function bit compare( vmm_data actual,
vmm_data expected );
usb_trans act, exp;
string text;

$cast( act, actual );

$cast( exp, expected );

return act.compare( exp, text );
endfunction

virtual function bit transform(
input vmm_data in_pkt,
output vmm_data out_pkts[]);
usb_trans tr;

$cast( tr, in_pkt.copy() );
tr.data = { << byte{ tr.data }}; // Reverse bytes
out_pkts = new[1]; // Add to the output
out_pkts[0] = tr;
return 0;
endfunction
endclass

vmm_sb_ds
class usb_to_sb extends usb_callbacks;
usb_scoreboard sb;

function new( usb_scoreboard sb );
this.sb = sb;
endfunction

virtual task post_tr( usb_master xactor, usb_trans tr );
vmm_data cpy = tr.copy();
sb.insert( cpy ); // Insert into scoreboard
endtask
endclass

usb_scoreboard sb;
usb_xactor usb;

virtual function build();
super.build();

this.sb = new();
this.usb = new ( ... );
begin
usb_to_sb cb = new( this.sb );
this.usb.append_callback( cb );
end
endfunction
endclass
Tips
Transaction packets must be an ancestor of vmm_data in order to work
with the vmm_sb_ds base class.
Single stream scoreboards do not need to define stream identifiers. Multi -
stream scoreboards do.
Define VMM_SB_DS_IN_STDLIB when compiling to turn on the scoreboard
registration methods.
For faster performance, define a simple quick_compare() method for
finding those easy matches.
When using expect_with_losses(), be sure to define the match()
method, which is required.
vmm_sb_ds
Gotchas
Normally, streams are automatically created when packets are received
with different stream IDs. Defining a stream with define_stream()
means that streams will no longer be automatic and an error message will
be issued if an undefined stream ID is encountered.
If a stream is defined as EITHER kind by define_stream(), then all
streams must be of EITHER kind.
The insert() method does not accept packet kinds of EITHER (must be
either INPUT or EXPECTED).
Be aware that multiple indications may be issued by the scoreboard since it
operates without delays. Create an extended
vmm_notify_callbacks::indicated() method if indications need to
be caught.
Calling get_n_orphaned() causes the remaining packets in the
scoreboard to be orphaned. Therefore, only call this method at the end of
simulation or use get_n_pending() during simulation.
The report() function may report more packets not found than shown in
the indi vidual streams. This happens when packets do not include stream
IDs so they do not show up in any streams statistics.
See also
vmm_sb_ds_*iter, vmm_sb_ds_callbacks
vmm_sb_ds_callbacks
The functionality of the data stream scoreboard can easily be extended by using
scoreboard callbacks, provided by extending the vmm_sb_ds_callbacks base
class. Callbacks are registered wi th the scoreboard using the scoreboard
methods append_callback() or prepend_callback(). The following table
summarizes the avai lable callbacks and when they are invoked by the
scoreboard:

Callback Invoking Scoreboard
Method
Description
dropped() expect_with_losses()
Invoked when a match is
not found at the beginning
of the stream; i.e., lost or
dropped packets preceded
the match.
matched() expect_in_order()
expect_out_of_order()
Invoked when compare()
indicates a matched
packet.
mismatched() expect_with_losses()
Invoked when compare()
indicates a mismatched
packet.
not_found() expect_in_order()
expect_out_of_order()
Invoked when a packet
cannot be found.
orphaned() get_n_orphaned()
Allows cleanup or
processing of orphaned
packets.
pre_insert() insert()
Invoked before the packet
is inserted into a stream.
post_insert() insert()
Invoked after the packet is
inserted into a stream.
Declaration
class vmm_sb_ds_callbacks #(type INP=vmm_data, EXP=INP);
vmm_sb_ds_callbacks
Methods
virtual function void dropped(
input vmm_sb_ds sb,
input vmm_data pkts[],
input int exp_stream_id,
input int inp_stream_id,
ref int count);
Called when packets are
considered lost and removed.
Lost packets are passed in
data_pkts[].
count used to increment the
scoreboards dropped counter.
virtual function void matched(
input vmm_sb_ds sb,
input vmm_data pkt,
ref int count);
Called when a packet is
matched and removed from
the scoreboard.
pkt contains matched packet.
count is used to increment
the scoreboards match
counter.
mismatched(
input vmm_sb_ds sb,
input vmm_data pkt,
ref int count);
Called when a packet
mismatches and is removed
from the scoreboard.
pkt contains matched packet.
the scoreboards mismatched
counter.
not_found(
input vmm_sb_ds sb,
input vmm_data pkt,
ref int count);
Called after packet was not
found in the scoreboard.
pkt contains unmatched
packet.
the scoreboards not found
counter.
virtual function void orphaned(
input vmm_sb_ds sb,
input vmm_data pkts[],
ref int count);
Called when packets are left
orphaned in the scoreboard.
Orphaned packets are passed
in data_pkts[].
count used to increment the
scoreboards orphaned
counter.
post_insert(
vmm_sb_ds sb,
vmm_data pkt,
int exp_stream_id,
int inp_stream_id);
Called after a packet is
inserted into the expected
queue.
pkt contains inserted packet.
vmm_sb_ds_callbacks
pre_insert(
input vmm_sb_ds sb,
input vmm_data pkt,
input vmm_sb_ds::kind_e kind,
ref int exp_stream_id,
ref int inp_stream_id,
ref bit drop);
Called before a packet is
inserted into the scoreboard.
pkt contains packet.
If kind is INPUT, then called
before the packet is
transformed and
exp_stream_id is invalid.
If kind is EXPECT, then called
before the packet is placed in
the expected queue.
If callback sets the drop field
to 1, then the packet is not
inserted.
Example
class my_cb extends vmm_sb_ds_callbacks;
virtual function void mismatched(
input vmm_sb_ds sb,
input vmm_data pkt,
ref int count );

`vmm_note( log,
$psprintf( "Packet mismatch! Count = %d", count );
endfunction
endclass

usb_scoreboard sb;
...
...
begin
my_cb cb = new();
sb.append_callback( cb ); // Add the callback
end
endfunction
endclass
vmm_sb_ds_callbacks
Tips
Any user-defined scoreboard expect function should invoke at least the
following callbacks: mismatched(), dropped(), matched(), and
not_found().
Gotchas
With the pre_insert() callback, modifying the stream identifiers wi ll
cause the packet to be inserted differently wi thin the scoreboard.
The pre/post_insert() callbacks are called only for the scoreboards
insert() method, not using the stream iterators prepend() and
append() methods.
See also
vmm_sb_ds
vmm_sb_ds_*iter
Scoreboard iterators are used to traverse through the transaction packets and
streams within a scoreboard. The vmm_sb_ds_iter iterator provides access to
the scoreboards streams, and vmm_sb_ds_stream_iter enables traversal
within the stream itself to find specific packets. Neither are intended to be
created directly via the constructor; rather, they are created and initialized by the
vmm_sb_ds::new_sb_iter() and new_stream_iter() methods,
respecti vely. Iterators are created in the invalid state, which means that they
point to nothing particular until a call to first() or next() is made. .
Declaration
class vmm_sb_ds_iter #(type INP=vmm_data , type EXP=INP);
class vmm_sb_ds_stream_iter #(type INP=vmm_data,
type EXP=INP);
Methods
vmm_sb_ds_iter
function
vmm_sb_ds_iter #(INP,EXP)
copy();
Returns a copy of the stream
currently pointed to by the
iterator.
function int delete(); Flushes current stream and
removes it from the
scoreboard.
function string describe(); Returns a string description of
the stream.
Displays the contents of the
iterator.
function int exp_stream_id(); Returns the expected stream
ID of the current stream.
function bit first(); Resets iterator to first stream.
function int get_n_dropped(); Returns the number of
dropped packets.
function int get_n_inserted(); Returns the number of
expected packets inserted.
function int get_n_matched(); Returns the number of
matched expected packets.
vmm_sb_ds_*iter
function int
get_n_mismatched();
mismatched packets.
Determined by
scoreboard method.
function int get_n_not_found(); Returns the number of packets
not found in the stream.
function int get_n_orphaned(); Returns the number of packets
orphaned in the stream.
function int get_n_pending(); Returns the number of packets
remaining in the stream.
function int incr_n_dropped(
int delta);
Modifies the number of
dropped packets.
function int incr_n_inserted(
int delta);
inserted packets.
function int incr_n_matched(
int delta);
matched packets.
function int incr_n_mismatched(
int delta);
mismatched packets.
function int incr_n_not_found(
int delta);
Modifies the number of not
found packets.
function int incr_n_orphaned(
int delta);
orphaned packets.
function int incr_n_pending(
int delta);
pending packets.
function int inp_stream_id(); Returns the input stream ID of
the current stream.
function bit is_ok(); Returns TRUE if the iterator is
pointing to a valid stream.
function bit last(); Resets iterator to last stream.
function int length(); Returns the number of
streams.
function
vmm_sb_ds_stream_iter#(INP,EXP)
new_stream_iter();
Creates and returns a new
stream iterator.
function bit next(); Sets iterator to the next
stream.
vmm_sb_ds_*iter
function int pos(); Returns current iterator
position.
Returns -1 if iterator does not
point to a valid stream.
function bit prev(); Changes iterator to previous
stream.
vmm_ds_sb_stream_iter
function void append(
EXP pkt);
Append specific packet after
current iterator position.
Iterator posi tion remains
unchanged.
function vmm_sb_ds_stream_iter
copy();
Copies iterator.
Returns an iterator at the
same current stream posi tion.
function vmm_data data(); Returns current stream
packet.
Returns null for invalid
packets.
function vmm_data delete(); Removes packet from stream
at current the iterator posi tion.
Returns removed packet, or
null if packet is invalid.
function string describe(); Returns a string description of
the stream.
function int exp_stream_id(); Returns the expected stream
ID.
function bit find(
EXP pkt);
Finds the specified packet in
the stream.
Returns TRUE and repositions
iterator if packet exists;
otherwise, iterator remains
unchanged.
function bit first(); Resets iterator position to the
beginning of the stream.
function int flush(); Flushes current stream.
Returns the number of flushed
packets.
function int inp_stream_id(); Returns the input stream ID.
vmm_sb_ds_*iter
function bit is_ok(); Returns TRUE if iterator points
to a valid expected packet.
function bit last(); Sets the iterator to the last
stream packet.
function int length(); Returns the number of packets
in the stream.
function bit next(); Changes iterator to the next
stream packet.
function int pos(); Returns the position of the
iterator in the stream.
Returns 0 for first position, and
-1 if last packet or empty
stream.
function int postflush(); Flushes packets in the stream
after current iterator position.
Returns number of flushed
packets or -1 if iterator points
to an invalid packet.
function int preflush(); Flushes packets in the stream
before current iterator position.
Returns number of flushed
packets or -1 if iterator points
to an invalid packet.
function void prepend(
EXP pkt);
Inserts the specific packet
before the iterator pointer in
the stream.
Iterator posi tion remains
unchanged.
function bit prev(); Changes iterator to previous
packet.
Example
Finding a packet throughout the scoreboard
class my_scoreboard extends vmm_sb_ds;
function vmm_data find( vmm_data pkt );
vmm_sb_ds_iter iter;
vmm_data current;

// Iterate through all the streams
iter = new_sb_iter();
while ( iter.next() ) begin
vmm_sb_ds_*iter

// Get a stream iterator
vmm_sb_ds_stream_iter s_iter;
s_iter = iter.new_stream_iter();

// Iterate through all the stream packets
while ( s_iter.next() ) begin
string text;
current = s_iter.data(); // Get a packet

// Does it match?
if ( current.compare( pkt, text ) )
return current; // Found it!
end
end
return null; // No match!
endfunction
...
endclass
Tips
When an iterator is first created, the next() method works just as well as
first().
The incr_n_*() methods can decrement the total number amounts by
specifying negati ve deltas (though the count will never go below 0).
Gotchas
Iterators are always created in the invalid state so be sure to call first()
or next() before using.
See also
vmm_sb_ds
Scenarios
Digital designs require more than just random transactions to test and configure.
A series of constrained random transactions are needed to properly test a
designs functionali ty. VMM provides this capabili ty through the use of
scenarios.
A simple scenario represents a constrained random stream of transactions. By
building one scenario upon another, a sense of order is superimposed on top of
the transaction stream. For example, a bus protocol can be described using two
basic scenariosread and write. A reset scenario builds upon these scenarios
by invoking both the read and write scenarios in a specific order. In such a way,
scenarios build and create sophisticated sti mulus for the design under test.
While scenarios define the way sti mulus wi ll be generated, a scenario generator
executes the scenarios and generates the actual transactions. These
transactions are then directed to one or more output channels, feeding other
scenarios or components (e.g., vmm_xactors) downstream. A scenario
generator is itself a vmm_xactor and multiple generators can be coordinated
together to create hierarchal sti mulus like what is required in a protocol stack.
Scenarios may be associated (registered) wi th one or more scenario generators.
Scenario generators repeatedly select an avai lable scenario, randomize it, and
then execute it. There are two types of scenario generators(1) single-stream
and (2) multi-stream. Single-stream generators have one output channel called
out_chan (similar to the vmm_atomic_gen). These are usually used to feed
the input of a single device interface.
In contrast, multi-stream scenario generators may drive transactions on any
number of channels. Channels are registered with the generator and scenarios
select the channel on which to drive. Thi s allows a multi-stream generator at a
high level to coordinate scenarios across many device interfaces.
Single-Stream Scenarios
Single-stream scenarios are executed on single-stream generators and their
transactions are funnelled through a single output channel. They are created
from vmm_ss_scenario automatically when using the
`vmm_scenario_gen() macro. There are three kinds of single-stream
scenarios: random, procedural, and hierarchical.

Single-Stream
Scenario
Generator
vmm_scenario_gen
Scenario
Scenario
Scenario
Scenario
Scenario
Scenario
out_chan
H
i
e
r
a
r
c
h
i
c
a
l

/

p
r
o
c
e
d
u
r
a
l

a
p
p
l
y
(
)
random
Scenario
items[]
vmm_ss_scenario #(T)
Scenarios
Random
By default, a generator wi ll automatically generate a random stream of
transactions. Each single-stream scenario contains a rand array member called
items[] that holds the created random transactions. When a scenario is
selected, the generator randomizes it, determining the number of transactions to
create using the following constraint:
constraint T_scenario_valid {
items.size == length;
}
The method define_scenario()is used to register the scenario name
(scenario_kind) and set its length (i.e., the number of transactions to
generate). User-defined constraints may also be added to control randomization
of the transactions. For example, the following constraints could be used for a
read-modify-write scenario:
class APB_RMW_scenario extends APB_data_scenario;
...
constraint read_modify_write {
if ( scenario_kind == APB_RMW ) {
length == 2;
items[0].kind == apb_data::READ;
items[1].kind == apb_data::WRITE;
items[0].address == items[1].address;
}
}
endclass
Once the transactions are randomized, the scenarios apply() method is
automatically invoked to copy the generated transactions into the output
channel, out_chan.
Procedural
For greater control over transaction generation, the default apply() procedure
may be overwritten. Inside apply(), different transaction types may be
instantiated, randomized, and then applied to the output channel in any random
or directed order. The number of transactions inserted into the output channel
must be returned by incrementing the argument n_inst. For example, the
following illustrates a procedurally defined reset scenario:
// Create plcp_packet_scenario and channel with macro
`vmm_scenario_gen( plcp_packet, "PLCP Packets" )

class reset_scenario extends plcp_packet_scenario;
int cfg_reg[ string ] = '{ "CFG1" : 'h10, ... };

function new();
define_scenario( "Reset", 1 );
endfunction
Scenarios
// Overwrite the apply() method
virtual task apply( plcp_packet_channel channel,
ref int unsigned n_inst );
plcp_packet pk;

// Write to all config registers to reset
foreach ( cfg_reg[name] ) begin
pk.addr = cfg_reg[name];
...
channel.put( pk );
end
n_inst += cfg_reg.num;
endtask
endclass
Hierarchical
Hierarchical scenarios are built by instantiating and invoking other scenarios. By
their nature, they are procedural and the apply() method must be overridden.
For example, the above reset scenario could be written as follows:
class write_scenario extends plcp_packet_scenario;
rand int addr, data;

function new();
define_scenario( "WRITE Scenario", 0 );
endfunction

plcp_packet pk = new();

// Random values used unless constrained
pk.addr = addr;
pk.data = data;
pk.kind = WRITE;
channel.put ( pk );
n_inst++;
endtask
endclass
class hier_reset_scenario extends plcp_packet_scenario;
write_scenario wr_scn;

function new();
wr_scn = new();
define_scenario( "Hier Reset Scenario", 0 );
endfunction

Scenarios

wr_scn.randomize with { addr=h10; data=...; };
wr_scn.apply( channel, n_inst );
...
endtask
endclass
Multi-Stream Scenarios
Multi-stream scenarios offer the functionali ty of a single-stream scenario, but
with the capability of reading or writing to multiple channels. This typically allows
multi-stream scenarios to act as high-level scenarios, feeding controls or data to
lower-level single or multi-stream scenarios.
Multi-stream scenarios are defined as two types: contained and distributed. A
contained scenario is one that is associated wi th a particular scenario generator
and uses only channels or scenarios also associated with that generator. A
distributed scenario may use channels or scenarios across many generators.
Multi-stream scenarios are innately procedural and hierarchical, and may invoke
single-stream scenarios as well as other multi-stream ones.
Multi-stream scenarios are derived from the class vmm_ms_scenario. Since
multi-stream scenarios can use multiple channels across many generators, each
channel must be registered using register_channel(). References to
channels are obtained using get_channel(). Instead of using the apply()
contained scenarios
vmm_ms_scenario_gen
Multi-Stream
Scenario
Generator
channel 0
channel 1
channel n
MS
Scenario
Scenario
Scenario
Multi-Stream
Scenario
Generator
vmm_ms_scenario_gen
vmm_ms_scenario_gen
Multi-Stream
Scenario
Generator
channel 0
channel 1
channel n
Scenario
Scenario
MS
Scenario
Scenario MS
Scenario
MS
Scenario
d
i
s
t
r
i
b
u
t
e
d

s
c
e
n
a
r
i
o
s
execute()
execute()
vmm_ms_scenario
Scenarios
method, multi-stream scenarios use an execute() method, which must be
overloaded when a multi-stream scenario is defined. Like apply(), the
execute()method must increment the transaction count argument, similarly
named as n.
The following is an example of a multi-stream scenario:
class video_conferencing_scenario extends vmm_ms_scenario;
camera_input cam_scn; // Single-stream scenario
lcd_trans lcd_tr; // LCD transaction
rand int picture_size;

constraint pic_size { picture_size > 10; }

function new( vmm_ms_scenario parent = null );
super.new( parent );
cam_scn = new;
lcd_tr = new;
endfunction

virtual task execute( ref int n );
vmm_channel cam_chan = get_channel( "CAM" );
vmm_channel lcd_chan = get_channel( "LCD" );

fork
// Send the image through the camera
begin
cam_scn.randomize() with
{ length == picture_size; };
cam_scn.apply ( cam_chan, n );
end

// Wait for the image to appear on the LCD
begin
for (int i = 0; i < picture_size; i++)
begin
lcd_chan.get( lcd_tr );

// Check that the same thing went through
assert ( lcd_tr.data ==
cam_scn.items[i].data) else
`vmm_error( log, "Sent != Received");
end
end
join
endtask
endclass
Scenarios
Hierarchical multi-stream scenarios
Multi-stream scenarios have the advantage that they can call scenarios from
other multi-stream scenario generators. This is accomplished by creating a
hierarchy through registering generators as sub-components of other generators
using register_ms_scenario_gen(). Once registered, multi-stream
scenarios can obtain a reference to other registered scenarios using
get_ms_scenario(). For example,
class high_level_scenario extends vmm_ms_scenario;
int scn_id = define_scenario( "high_level", 0 );

task execute( ref int n );
vmm_ms_scenario dma_scn
= get_ms_scenario("dma", "AHB_GEN");
vmm_ms_scenario rand_mem_scn
= get_ms_scenario("rand_mem", "DDR_GEN");

dma_scn.randomize();
rand_mem_scn.randomize();

fork
dma_scn.execute();
rand_mem_scn.execute();
join
endtask
endclass
program test1;
dma_cfg_scenario dma_scn = new;
rand_mem_scenario rmem_scn = new;

vmm_ms_scenario_gen ahb_gen = new( "AHB_GEN" );
vmm_ms_scenario_gen ddr_gen = new( "DDR_GEN" );
vmm_ms_scenario_gen top_gen = new( "TOP_GEN" );

initial
begin
ahb_gen.register_ms_scenario( "AHB_GEN", dma_scn );
ddr_gen.register_ms_scenario( "DDR_GEN", rmem_scn );

top_gen.register_ms_scenario_gen( "AHB_GEN", ahb_gen);
top_gen.register_ms_scenario_gen( "DDR_GEN", ddr_gen);

top_gen.start_xactor(); // Only on the top generator!
...
end
endprogram
Scenarios
Creating Scenarios
When creating single-stream scenarios, VMM defines two macros to si mplify
declaring the parameterized classes employed. These macros are:
`vmm_scenario_gen( class-name, text )
`vmm_scenario_gen_using( class_name, channel_type, text )
7

where class-name is the transaction type of the scenario, text is a class
description, and channel_type refers to the output channel type compatible
with class_name.
For example, the following macro statement:
`vmm_scenario_gen( APB, "APB" )
creates the following 5 user-defined class types:

Class Definition
APB_scenario_gen vmm_scenario_gen #( APB, "APB" )
APB_scenario vmm_ss_scenario #( APB, "APB" )
APB_atomic_scenario
8
vmm_atomic_scenario #(APB, "APB")
APB_scenario_gen_call
backs
vmm_scenario_gen_callbacks
#( APB, "APB" )
APB_scenario_election vmm_scenario_election
#( APB, "APB" )

These classes become the base classes for all derived scenario and generator
classes. With multi-stream scenarios, the multi-stream bases classes are
extended to create new scenarios and components. For example,
class ethernet_scenario extends vmm_ms_scenario;
class ocp_generator extends vmm_ms_scenario_gen;
Registering Scenarios
Both single and multi-stream scenarios require registering scenarios with their
respecti ve scenario generators. Registering a scenario is done by using
register_scenario() / register_ms_scenario(). Likewise, scenarios

7
In VMM 1.2, this macro is redundant and functionally equi valent to
`vmm_scenario_gen().
8
An atomic scenario is a single-stream scenario wi th a length of 1.
Scenarios
can be unregistered or replaced. An easy way to register scenarios is to use the
`foreach_vmm_xactor() macro. For example,
`foreach_vmm_xactor ( axi_scenario_gen, "/./", "/./" )
begin
axi_scenario scn = new;
xact.register_scenario( scn );
end
Scenario Selection
For both single and multi-stream scenario generators, scenarios are randomly
selected from all those registered in the scenario_set[$] array. The specific
scenario to pick is determined by randomizing a vmm_scenario_election /
vmm_ms_scenario_election instance (select_scenario) that contains a
field member select. By default, the election instance uses a round-robin
algorithm that can be disabled as follows:
env.gen.select_scenario.round_robin.constraint_mode( 0 );
Changing the selection algorithm involves nothing more than extending the
election class with user-defined constraints and assigning the instance to the
generators select_scenario variable.
Scenario Constraints
In addition to the length property, several other scenario properties can be
used to control the generation of scenario transactions. Scenarios contain a
repeated and repeat_thresh (threshold) field that specifies the number of
times to repeat the scenario. The actual number of transactions created by a
scenario will be (length * (repeated + 1)). The repeated field is hard
coded in a vmm_scenario to be equal to 0. In order to override this value, the
repetition constraint must be overwritten:
class my_apb_scenario extends apb_scenario;
constraint repetition {
repeated < 20;
}
endclass
By default, repeat_thresh is set to 100, which sets an upper maxi mum
number of repeats.
With single-stream scenarios, modifying constraints across all transactions is
easily accomplished by assigning a factory instance to a scenarios using
property. For example, the following uses a factory template to generate
scenario transactions:
trans_template tr = new;
foreach ( env.gen.scenario_set[i] ) begin
Scenarios
env.gen.scenario_set[i].using = tr;
end
The new factory replacement service also provides another easy alternati ve.
For example,
trans_template::override_with_new("@%*", tr, log);
Controlling indi vidual transaction randomization may be accomplished by either
specifying random constraints that constrain the items[] array or by manually
assigning values. For example, the fill_scenario() method will allocate
transactions in the items[] array without randomizing them (use
allocate_scenario() to generate using the factory pattern assigned to
using). Therefore, the following could replace the constraints on an indi vidual
transaction object:
ocp_trans tr = new;
ocp_scenario scn;

scn = env.gen.get_scenario( "Random" );
scn.fill_scenario();
scn.items[2] = tr;
Now when the generator randomizes the transactions, the new constraints for
items[2] will be used.
Scenario Callbacks
In addition to defining constraints in a scenario, callbacks may also be used to
configure or customize a scenario. Callbacks have the advantage that they can
configure a scenario at run-time, which allows testcases to customize scenario
behavior, or they can control timing relationships across multiple child scenarios.
VMM defines two callbacks as part of vmm_scenario_gen_callbacks:
pre_scenario_randomize() and post_scenario_gen(). As their names
imply, the first is invoked before randomization and the second afterwards;
however, both are called before a scenario injects a transaction into a channel.
The post_scenario_gen() callback includes a dropped bit so that a
transaction can be discarded instead of placed in the channel.
Configuring the Generator
A scenario generator continues to execute unti l either a certain number of
transactions have been generated or a specific number of scenarios have been
selected. These values are set by setting the generators
stop_after_n_insts to the maxi mum desired transactions or
stop_after_n_scenarios to the maxi mum number of scenarios.
Scenarios
VMM 1.2 uses a factory mechanism that can also configure scenarios and
generators. For example, a scenario can be defined using the class factory
macro:
class bus_scenario extends bus_trans_scenario;
function new(); ...
function vmm_data allocate(); ...
function vmm_data copy (vmm_data to = null ); ...

`vmm_class_factory( bus_scenario )
endclass
Then gi ven the following environment:
class env extends vmm_env;
`vmm_typename( env );
bus_scenario_gen gen;
bus_scenario scn;
...
virtual function void build ();
gen = new( "gen", 0 );
scn = new;
gen.register_scenario( "bus_scenario", scn );
endfunction
endclass
The following testcase can configure the generator using calls to the factory:
...
// Swap bus_scenario wi th pci_scenario
virtual function void start_of_sim_ph();
bus_scenario::override_with_new(
"@env1:gen:bus_scenario",
pci_scenario::this_type,
log, `__FILE__, `__LINE__ );
endfunction
endclass
Scenarios
Controlling the Channel
On occasion, a scenario may need exclusi ve access to an output channel in
order to control the transaction stream. Exclusi ve access to a channel is granted
by using the grab()/ungrab() methods and specifying the grabber input to
the channel methods (put() or sneak()). For example,
virtual task apply( pci_channel channel,
ref int unsigned n_insts );
pci_trans tr;

tr = new;
tr.randomize with ( ... };
channel.grab( this );
channel.put ( tr.copy(), .grabber( this ));
channel.ungrab(this);
n_insts++;
endtask
In order to prevent deadlock in hierarchical scenarios, child scenarios have
access to channels grabbed by their parent. The parent-child relationship is
establi shed by using set_parent_scenario() as follows:
class soc_config_scenario extends ahb_scenario;
usb_cfg_scenario usb_scn = new();
dma_cfg_scenario dma_scn = new();
mmu_cfg_scenario mmu_scn = new();

function new();
define_scenario( "SOC Config", 0 );
usb_scn.set_parent_scenario( this );
dma_scn.set_parent_scenario( this );
mmu_scn.set_parent_scenario( this );
endfunction

virtual task apply( ahb_channel channel,
channel.grab( this );
usb_scn.apply( channel, n_insts );
dma_scn.apply( channel, n_insts );
mmu_scn.apply( channel, n_insts );
channel.ungrab( this );
endtask
endclass
Scenarios
Class Hierarchy
The scenario class hierarchy and how they interact are illustrated as follows:
Tips
Registered multi-stream scenarios can be obtained from anywhere inside
an environment by using get_ms_scenario(). This makes multi-stream
scenarios very flexible and reusable.
The `foreach_vmm_xactor() has many applications with scenarios. For
example, it is very convenient for registering scenarios or setting generator
values as follows:

`foreach_vmm_xactor( my_scenario_gen, "/./", "/./")
xact.stop_after_n_scenarios = 20;

A directed test can be created wi th one multi-stream scenario by pushing
the scenario to the front of the generators scenario_set[] array and
configuring the generator to run only 1 scenario.
In order to disable a generators round-robin algorithm, si mply turn off the
generators constraint (see Scenario Selection above).
A random multi-stream scenario can created by rand members or calling
randomize() inside the execute() method.
vmm_ms_scenario_gen
stream_id
scenario_id
n_scenarios
scenario_set[$]
last_selected[$]
next_in_set
constraint round_robin
vmm_scenario_election
stream_id
scenario_id
n_scenarios
scenario_set[$]
last_selected[$]
next_in_set
constraint round_robin
vmm_ms_scenario_gen_callbacks
vmm_scenario_gen_callbacks
vmm_data
vmm_scenario
scenario_kind
length
repeated
repeat_thresh
vmm_ms_scenario
execute()
vmm_scenario_base
vmm_ss_scenario #(T)
items[]
T using
apply()
vmm_atomic_scenario #(T)
vmm_xactor_callbacks
vmm_xactor
vmm_scenario_gen
select_scenario
main()/ inject()
select_scenario
main()
Scenarios
Gotchas
Be sure to release (ungrab) a grabbed channel to prevent deadlock.
For hierarchical scenarios, be sure to use set_parent_scenario() so
that children can have access to channels grabbed by their parent.
A default-configuration single-stream scenario generator has significantly
less performance than an atomic generator due to the additional overhead
associated wi th scenarios.
9

See also
vmm_scenario, vmm_ms_scenario, vmm_scenario_gen,
vmm_ms_scenario_gen, vmm_ss_scenario, vmm_*_scenario_election,
vmm_*_scenario_gen_callbacks

9
According to the VMM Standard Library User Guide, Version C-2009.06. Note,
a multi-stream generator used only wi th single-stream scenarios should have the
performance of a single-stream generator.
vmm_scenario
234 Copyri ght 2010 by Doul os Ltd. All ri ghts re served.
A scenario is a constrained random stream of transactions. The
vmm_scenario class is derived from vmm_data and it defines the members
and functionality needed for describing a basic scenario. For example,
vmm_scenario includes the number of transactions a scenario should create
(length), how many times it should be repeated (repeated), and essential
methods like define_scenario().
Both single and multi-stream scenarios are deri ved from this base class. In fact,
vmm_scenario is never used directly, but rather, all scenarios are extended
from either vmm_ss_scenario or vmm_ms_scenario. For single-stream
scenarios, the macro `vmm_scenario_gen( trans_type ) may be used
instead to automatically define a class called trans_type_scenario, which is
an descendent of vmm_scenario.
Declaration
class vmm_scenario extends vmm_data;
Methods
function new(
vmm_scenario parent = null);
Constructor.
virtual function vmm_data copy(
Copy method.
Returns a reference to a
vmm_scenario.
define_scenario(
string name,
Defines a new scenario name
and sets the maxi mum length
of the transaction stream (i.e.,
number of transactions to
generate).
Returns an integer scenario
kind identifier which can be
used for specifying scenario
kind related constraints.
protected function int unsigned
get_max_length();
Returns the maxi mum length
of the transaction stream.
function vmm_scenario
get_parent_scenario();
Returns the parent scenario.
Returns null for a top-level
scenario.
psdisplay(
Returns a string descripting
the scenario.
vmm_scenario
function void
redefine_scenario(
string name,
Redefines a scenarios name
or maxi mum length.
int unsigned scenario_kind
= 0);
scenario_kind.
function void
set_parent_scenario(
vmm_scenario parent);
Sets the scenario hierarchy by
specifying the scenarios
parent.
Members
rand int unsigned length; Maxi mum number of
transactions to generate.
rand int unsigned repeated = 0; Number of times to repeat the
scenario.
static int unsigned
repeat_thresh = 100;
Maxi mum number of times to
repeat a scenario.
rand int unsigned
scenario_kind;
Numeric ID assigned to a
scenario when registered with
define_scenario().
int scenario_id; Generators scenario count
constraints.
int stream_id; Generators stream ID
used by other components
(like a scoreboard) to
differentiate transactions.
constraint vmm_scenario_valid; Defines reasonable
constraints for the scenario
(like maxi mum length and
repetitions).
constraint repetition; Hard codes the repeated
value to 0.
Constraint must be overwritten
to change the repeated
value.
vmm_scenario
Shorthand Macros
The vmm_scenario shorthand macros provide an easy way to automate the
creation of predefined functions such as copy(), print(), allocate(), or
psdisplay(). The member macros are placed between a
`vmm_scenario_member_begin / `vmm_scenario_member_end pair. The
default implementation for these methods can be extended or overwritten by
defining a do_copy(), do_print(), do_allocate(), etc.
The name field specifies the data member name. The do field specifies the
methods to automatically generate. The enumeration values can be OR-ed
together for specific methods or DO_ALL for all methods. Those macros wi th a
how field specify whether a vmm_data copy should be deep (DO_DEEPCOPY) or
shallow (DO_REFCOPY), or if a compare should be deep (DO_DEEPCOMPARE) or
shallow (DO_REFCOMPARE).
There is also an additional constructor macro called `vmm_scenario_new().
This macro provides an easy shorthand way of defining a default-configuration
constructor. It is not needed if `vmm_scenario_member_begin is used,
unless a user-defined constructor needs to be written.
Begin / end macros
`vmm_scenario_member_begin( class )
`vmm_scenario_member_end( class )
Scalar data members
`vmm_scenario_member_scalar( name, do )
`vmm_scenario_member_scalar_array( name, do )
`vmm_scenario_member_scalar_da( name, do )
`vmm_scenario_member_scalar_aa_scalar( name, do )
`vmm_scenario_member_scalar_aa_string( name, do )
`vmm_scenario_member_enum( name, do )
`vmm_scenario_member_enum_array( name, do )
`vmm_scenario_member_enum_da( name, do )
`vmm_scenario_member_enum_aa_scalar( name, do )
`vmm_scenario_member_enum_array( name, do )
`vmm_scenario_member_enum_aa_string( name, do )
vmm_scenario
String data members
`vmm_scenario_member_string( name, do )
`vmm_scenario_member_string_array( name, do )
`vmm_scenario_member_string_da( name, do )
`vmm_scenario_member_string_aa_scalar( name, do )
`vmm_scenario_member_string_aa_string( name, do )
Class handle data members
`vmm_scenario_member_handle( name, do )
`vmm_scenario_member_handle_array( name,do )
`vmm_scenario_member_handle_da( name,do )
`vmm_scenario_member_handle_aa_scalar( name,_do )
`vmm_scenario_member_handle_aa_string( name, do )
vmm_data members
`vmm_scenario_member_vmm_data( name, do, how )
`vmm_scenario_member_vmm_data_array( name, do, how )
`vmm_scenario_member_vmm_data_da( name, do, how )
`vmm_scenario_member_vmm_data_aa_scalar( name, do, how )
`vmm_scenario_member_vmm_data_aa_string( name, do, how )
Constructor macro
`vmm_scenario_new( class ) ..
vmm_scenario
Example
`vmm_scenario_gen( instruction )
class branch_inst_scenario extends instruction_scenario;
constraint forward_long_branch {
foreach ( item[i] ) {
if ( items[i].opkind == BRANCH )
items[i].target > items[i].pc + 256;
}
}
endclass

`vmm_scenario_gen( ocp_trans )
class ocp_scenario extends ocp_trans_scenario;
constraint burst_mode {
if ( scenario_kind == burst ) {
length == 8;
repeated == 0;
foreach ( item[i] )
if ( i > 0 )
item[i].addr == item[i-1].addr + 1;
}
}
endclass

class my_scenario extends vmm_ms_scenario;
int my_scn = define_scenario("My Scenario", 0);

`vmm_scenario_member_begin( my_scenario )
`vmm_scenario_member_scalar( my_scn , DO_ALL )
`vmm_scenario_member_end( my_scenario )
virtual task execute(ref int n);
...
endtask
endclass
Tips
For single-stream scenarios, use the vmm_scenario data members to
constrain the transaction stream in items[].
Remember to overwrite the repetition constraint to set the repeated
value.
vmm_scenario
Remember to define scenarios with define_scenario() so that the
transaction stream length is set and scenario_kind can be used in
random constraints.
Gotchas
A vmm_scenario by itself does not have all the necessary elements
needed for scenario generation. Always create scenarios by extending
from either vmm_ms_scenario (for multi-stream) or vmm_ss_scenario
(for single-stream).
See also
Scenarios, vmm_ss_scenario, vmm_ms_scenario
vmm_*_scenario_election
Both the single-stream (vmm_scenario_gen) and the multi-stream
(vmm_ms_scenario_gen) scenario generators use an election object to select
the next scenario to generate. This election object is provided as
vmm_scenario_election#(T,text) for single-stream generators, and
vmm_ms_scenario_election for multi-stream. The single-stream generator
macro, `vmm_scenario_gen(class), automatically creates the single-stream
election class named class_scenario_election. These classes are
essentially identical wi th the exception that the scenario_set[] arrays are
defined for the respecti ve type of scenarios.
When a generator goes to select a scenario, it copies its registered scenarios
into the election objects scenario_set[] array. By default, the election
object defines a round-robin selection constraint that assigns the next selected
scenario to the select property. The select property is then used by the
scenario generator to pick the next scenario.
In this way, a scenario generators selection algorithm can easily be changed by
extending the election class, overriding the round_robin constraint, adding
additional constraints, and assigning the new election object to the generators
select_scenario property. The several members of the election object are
updated by the generator before randomization so that constraints can be bui lt
using these property values. See the article on Scenarios more details.
Declaration
class vmm_scenario_election#(type T=vmm_data,
string text="" );
class vmm_ms_scenario_election;
Members
Shared between both classes
int unsigned last_selected[$]; History of the last
selected scenarios.
Maxi mum length of 10.
int unsigned n_scenarios; Total number of
registered scenarios.
int unsigned next_in_set; The next scenario in the
set.
Used by the
round_robin
constraint.
int scenario_id; Generators scenario
count assigned before
randomization.
rand int select; The selected scenario.
Used by the generator to
select the next scenario.
int stream_id; Generators stream ID
assigned before
randomization.
constraint
vmm_scenario_election_valid;
Constraint to ensure that
select has a valid
value.
constraint round_robin; Constraint to pick the
next scenario in the
scenario set in a round-
robin fashion.

vmm_scenario_election #(T, text)
vmm_ss_scenario#(T) scenario_set[$]; The set of registered
scenarios.

vmm_ms_scenario scenario_set[$]; The set of registered
scenarios.
Example
Create a single-stream election definition
`vmm_scenario_gen( ahb_trans )

class random_election extends ahb_trans_scenario_election;
constraint round_robin {} // Removes constraint
endclass

program random_test;
random_election elect = new;
ahb_trans_scenario_gen gen = new( ... );

initial
begin
gen.select_scenario = elect; // New election algorithm
...
end
endprogram
Tips
Alternati vely to overriding the round_robin constraint, the constraint can
be disabled using SystemVerilogs constraint_mode() construct:

gen.select_scenario.round_robin.constraint_mode(0);
Use the `vmm_scenario_gen() macro to automatically define the
necessary election class.
See also
Scenarios, vmm_scenario_gen, vmm_ms_scenario_gen
vmm_scenario_gen
A scenario generator is defined by the vmm_scenario_gen class. A generator
is a vmm_xactor that automatically creates a transaction stream by invoking its
registered scenarios. By default, a vmm_scenario_gen scenario generator
has one output channel, out_chan, and is used only for single-stream
scenarios.
In order to generate transactions, a scenario must be registered with the
generator. This is accomplished by using the registration method
register_scenario(). Once registered, the generator randomly selects a
scenario using its vmm_scenario_election property, called
scenario_select. The selection algorithm can be changed by extending the
scenario election class and defining custom constraints. The default selection
algorithm selects scenarios in a round robin fashion, but this can be disabled by
turning off a generators round_robin constraint.
Scenario generators also invoke callbacks associated wi th the selected
scenario. Two callbacks are provideda pre-randomize method called
pre_scenario_randomize() and a post-randomize method called
post_scenario_gen(). Callbacks are created by extending the
vmm_scenario_gen_callbacks class.
The shorthand macro, `vmm_scenario_gen( class ), automatically
creates a scenario generator that generates transaction class objects.
Likewise, it automatically creates a basic scenario (class_scenario), atomic
scenario (class_atomic_scenario), callback
(class_scenario_gen_callbacks), and election class
(class_scenario_election).
The functionality of a scenario generator can be summari zed as follows:
1) Randomly selects a scenario.
2) Sets specific generator values like stream_id and scenario_id.
3) Calls any associated pre_scenario_randomize() callback.
4) Randomizes the scenario data members.
5) Calls any associated post_scenario_gen() callback.
6) Repeatedly call the scenarios apply() method to copy the randomly
generated transaction objects from the scenarios items[] array into the
output channel.
7) Stops if stop_after_n_insts or stop_after_n_scenarios is
reached.
See the article on Scenarios for more information.
Declaration
class vmm_scenario_gen_base extends vmm_xactor;
class vmm_scenario_gen #(type T = vmm_data,
string text = "")
extends vmm_scenario_gen_base;
vmm_scenario_gen
Methods
vmm_scenario_gen_base
function new(
string name,
string inst,
int stream_id = -1);
Constructor.
register_scenario(
string name,
vmm_ss_scenario_base
scenario);
Registers scenario scenario
with the generator with the
name name.
replace_scenario(
string name,
scenario);
Replaces the scenario
registered under name with the
alternati ve scenario
scenario.
scenario_exists(
string name);
Returns true if the scenario
name is registered.

vmm_scenario_gen
function new(
string inst,
int stream_id = -1
vmm_channel_typed#(T)
out_chan = null);
Constructor.
If out_chan is null, then an
output channel is automatically
created.
get_all_scenario_names(
Returns an array of all the
registered scenarios names.
get_n_insts();
Returns the actual number of
transaction instances
generated.
get_n_scenarios();
Returns the actual number of
scenarios applied.
function vmm_ss_scenario#(T)
get_scenario(
string name);
Returns the scenario
registered under name.
get_names_by_scenario(
scenario,
Returns an array of names
used to register the specified
scenario.
vmm_scenario_gen
get_scenario_index(
scenario);
Returns the index of the
scenario in the
scenario_set[] array.
Returns -1 if not found.
get_scenario_name(
vmm_ss_scenario#(T)
scenario);
Returns the registered string
name of the specified
scenario.
virtual task inject(
vmm_ss_scenario#(T)
scenario);
Causes the generator to
execute the specific scenario.
May be used when the
generator is running or
stopped.
virtual task inject_obj(
T obj);
Injects a transaction object
into the output stream.
May be used when the
generator is running or
stopped.
psdisplay(
the generator.
register_scenario(
string name,
vmm_ss_scenario_base scen);
Registers the specified
scenario with the generator as
name.
replace_scenario(
string name,
vmm_ss_scenario_base scen);
Replaces the scenario
registered under name with
scenario scen.
reset_xactor(
= SOFT_RST);
Resets the generator.
Flushes the output channel
and clears the generators
data members.
scenario_exists(
string name);
Returns true if scenario
specified by name is registered
in the scenario_set[]
array.
unregister_scenario(
scenario);
Unregisters the scenario
specified by scenario.
function vmm_ss_scenario#(T)
unregister_scenario_by_name(
string name);
Unregisters the scenario
specified by name.
vmm_scenario_gen
Members
protected int inst_count; Number of transaction
instances generated.
vmm_channel_typed#(T) out_chan; Output channel.
protected int scenario_count; Number of scenarios
executed.
vmm_ss_scenario#(T)
scenario_set[$];
Array of registered scenarios.
vmm_scenario_election#(T, text)
select_scenario;
Election instance used for
selection scenarios.
int unsigned
stop_after_n_insts;
Maxi mum limi t of transaction
instances to generate.
int unsigned
stop_after_n_scenarios;
Maxi mum limi t of scenarios to
execute.
typedef enum int {
GENERATED,
DONE
} symbols_e;
Macros
`vmm_scenario_gen( T, text ) Macro to automatically define the
following classes for transaction
type T:

T_scenario_gen
T_ss_scenario
T_atomic_scenario
T_scenario_gen_election
T_scenario_gen_callbacks
`vmm_scenario_gen_using(
T, channel_name, text )
Same as above, but specifies the
output channel type.
In VMM 1.2, equi valent to
`vmm_scenario_gen().

vmm_scenario_gen
Example
class pci_trans extends vmm_data;
...
endclass

`vmm_scenario_gen( pci_trans, "PCI transaction" )

class pci_scenario extends pci_trans_scenario;
int scn_id = define_scenario( "PCI, 5 );
...
endclass

class custom_elect extends pci_trans_scenario_gen_election;
constraint round_robin { } // Remove constraint so
// selection is random
endclass

program testcase;

pci_trans_scenario_gen pci_gen = new( "PCI Gen", 1 );
pci_scenario pci_scn = new;
custom_elect selection_algorithm = new;

initial
begin
pci_gen.register_scenario("PCI scenario", pci_scn);
pci_gen.stop_after_n_insts = 100;
pci_gen.select_scenario = selection_algorithm;
...
end
endprogram
Tips
When the maxi mum scenario or instance li mit is reached, the generator
must be reset before it can be restarted.
For a simple single transaction scenario, use the atomic scenario
automatically created by the `vmm_scenario_gen() macro.
The name that a scenario is registered wi th the generator does not need to
be the same as what was defined using define_scenario().
A scenario may be registered under different names to create aliases of the
scenario.
vmm_scenario_gen
Gotchas
A scenario generator wi ll not stop in the middle of a scenario so the number
transaction instances created may actually exceed the
stop_after_n_insts limit, or the number of scenarios applied may be
less than the stop_after_n_scenarios. Use get_n_insts() for the
actual instance count and get_n_scenarios() for the scenario count.
By default, the stop_after_n_insts and stop_after_n_scenarios
properties are set to 0, which means that the generator will never stop.
Re-registering a registered scenario will generate an erroruse
replace_scenario() instead.
See also
Scenarios, vmm_scenario, vmm_ss_scenario, vmm_*_scenario_gen_callbacks,
vmm_*_scenario_election, vmm_ms_scenario_gen
Both the single-stream (vmm_scenario_gen) and the multi-stream
(vmm_ms_scenario_gen) scenario generators use a scenario callback object,
vmm_scenario_gen_callbacks#(T,text) and
vmm_ms_scenario_gen_callbacks, respectively. Scenario callbacks are
extended from vmm_xactor_callbacks and are registered with the generator
in the usual way.
The callbacks class defines two virtual methods,
pre_scenario_randomize() and post_scenario_gen(). As their
names imply, the pre_scenario_randomize() is called by the generator
before the selected scenario is randomized, and the post_scenario_gen() is
called afterwards. These are useful functions for making test-specific
modifications at run-time instead of re-defining the scenario. While both the
single and multi-stream callbacks class define a post_scenario_gen()
method, only the single-stream scenario generator executes it. The
post_scenario_gen() method has a dropped argument which indicates to
the generator to drop the scenario. See the article on Scenarios more details.
Declaration
class vmm_scenario_gen_callbacks
#(type T=vmm_data, string text="" )
extends vmm_xactor_callbacks;
class vmm_ms_scenario_gen_callbacks
extends vmm_xactor_callbacks;
Methods
vmm_scenario_gen_callbacks #(T,text)
virtual task pre_scenario_randomize(
vmm_scenario_gen #(T, text) gen,
ref vmm_ss_scenario #(T) scenario);
Callback invoked by the
generator before
randomizing the
scenario.
gen refers to the
generator calling the
callback, and scenario
refers to the selected
executing scenario.
virtual task post_scenario_gen(
vmm_scenario_gen #(T, text) gen,
vmm_ss_scenario #(T) scenario,
ref bit dropped);
Callback invoked by
generator after
randomization and
before calling apply().
Similar arguments as
above. dropped
indicates to the
generator to drop the
scenario.

vmm_ms_scenario_gen_callbacks
virtual task pre_scenario_randomize(
vmm_ms_scenario_gen gen,
ref vmm_ms_scenario scenario);
Callback invoked by the
generator before
randomizing the
scenario.
gen refers to the
generator calling the
callback, and scenario
refers to the selected
executing scenario.
virtual task post_scenario_gen(
vmm_ms_scenario_gen gen,
vmm_ms_scenario scenario,
ref bit dropped);
Not used by the multi-
stream generator.
Example
`vmm_scenario_gen( ocp )
class ocp_scen_gen_callbacks extends
ocp_scenario_gen_callbacks;
virtual task post_scenario_gen( ocp_scenario_gen gen,
ocp_scenario scenario,
ref bit dropped );
// Print out the scenario
scenario.display();
`vmm_note( gen.log, "################### );
endtask
endclass

program interconnect_test;
ocp_scenario_gen gen = new( ... );
ocp_scen_gen_callbacks cb = new;

mem_transfer_scn mem_scn = new;
peripheral_scn periph_scn = new;
initial
begin
gen.register_scenario( "MEM_TRANSFER", mem_scn );
gen.register_scenario( "PERIPHALS", periph_scn );

gen.prepend_callback( cb );
...
end
endprogram
Tips
Use callbacks from testcases to enable/disable constraints, modify scenario
values, or cause the generator to drop scenarios.
Gotchas
The post_scenario_gen() callback is not used wi th multi-stream
scenarios.
See also
Scenarios, vmm_scenario_gen, vmm_ms_scenario_gen, vmm_xactor_callbacks
vmm_scheduler
A vmm_scheduler funnels transactions from multiple sources into one output
channel (the opposite effect of a vmm_broadcast). Unlike a simple channel
that indiscriminately interleaves transactions when fed from multiple sources, a
vmm_scheduler can identify source streams and use a user-configurable
scheduling algorithm to place the transactions in the output channel.

By default, the vmm_scheduler arbitrates in a round-robin method. The
vmm_scheduler::schedule() method can be overridden to define a custom
scheduling algorithm. An alternati ve approach is to define a custom
vmm_scheduler_election class, containing the appropriate random
constraints, and assign the election object to the
vmm_scheduler::randomized_sched variable instance (see
vmm_scheduler_election for details).
Declaration
class vmm_scheduler extends vmm_xactor;
Methods
function new(
string name,
string inst,
vmm_channel destination,
int instance_id = -1,
destination refers to the
output channel.
instance_id is an
optional instance identifier.
virtual protected task
get_object(
input vmm_channel source,
input int unsigned input_id,
input int offset);
Overloadable method
invoked by schedule()
that returns transaction obj
from input channel source
at offset offset.
virtual function int new_source(
vmm_channel channel);
Adds the new input channel
source to the scheduler.
Returns identifier for input
channel or -1 on error.
channel
channel
channel
channel
v
m
m
_
s
c
h
e
d
u
l
e
r

vmm_scheduler
psdisplay(
Function to print out the
broadcast information.
reset_xactor(
= SOFT_RST);
Resets broadcaster and
flushes input/output
channels.
Reset type equals
SOFT_RST,
PROTOCOL_RST,
FIRM_RST, or HARD_RST
(see VMM reference manual
for details).
A HARD_RST replaces the
factory instance of
randomized_sched (see
vmm_scheduler_election).
virtual task sched_from_input(
int channel_id,
int on_off);
Schedules a transaction
from the specified channel if
turned on.
on_off specifies on if 1
and off if 0.
virtual protected task schedule(
input vmm_channel sources[$],
input int unsigned
input_ids[$]);
Overloadable method that
defines the scheduling rules
of the vmm_scheduler.
The transaction returned as
obj is added to the output
channel. A return of null
means that no transaction
will be added.
The input channels and
corresponding IDs are
provided as sources[$]
and input_ids[$].
start_xactor();
Starts the broadcaster
instance.
stop_xactor();
Stops the broadcaster
instance.
Members
vmm_log log; Message service instance.
protected vmm_channel out_chan; Reference to output channel
set by the constructor.
vmm_scheduler
vmm_scheduler_election
randomized_sched;
Factory instance of
used by schedule() to pick
transactions.
Example
class my_scheduler extends vmm_scheduler;
randc bit [3:0] id; // randc so no repeated random IDs.
// (Note, the SystemVerilog standard
// only requires implementations of up to
// 8 bits for randc variables)

function new ( string name, string instance,
vmm_channel dst, int inst_id );
super.new ( name, instance, dst, inst_id );
endfunction

// User-defined custom scheduling algorithm
virtual protected task schedule ( output vmm_data obj,
input vmm_channel srcs[$],
input int unsigned input_ids[$] );

// A round-robin algorithm, but gi ving priority to the first input channel
if ( src[0].size() > 0 )
id = 0; // 1st channel is not empty so select it
else
// Randomize id to select the next channel to read from
void( this.randomize() with
{ id > 0 && id <= srcs.size(); } );

srcs[id].get( obj ); // Get object from selected channel
endtask
endclass

my_scheduler sched;
trans_channel channels[4];
trans_channel dst;
...

sched = new ( "scheduler", "sched", dst );

vmm_scheduler
foreach ( channels[i] ) begin
channels[i] = new ( ... );
sched.new_source( channels[i] );
end
...
endfunction

task start();
super.start();

sched.start_xactor();
...
endtask

task stop();
super.stop();

sched.stop_xactor();
...
endtask
endclass
Tips
Overloading the get_object() method enables user-configurable
changes to the transaction object like injecting errors, recording functional
coverage, or substituting alternati ve objects that are passed back to the
scheduling algorithm.
An easier approach to changing the scheduling algorithm than overloading
schedule() is to replace the vmm_scheduler_election instance in
the vmm_scheduler. See vmm_scheduler_election for details.
Gotchas
User extensions of start_xactor(), stop_xactor(), new_source(),
or sched_from_input() must call their respective base class methods
(e.g., super.start_xactor(), etc.).
If schedule() returns null, then no transaction will be scheduled and the
next scheduling cycle wi ll be delayed. When a scheduling cycle is delayed,
lock-up may occur unless (1) a new channel is added, (2) new data is put
into the channel, (3) a channel is turned on, or (4) the scheduler is
restarted.
vmm_scheduler
When overloading get_object(), make sure to remove objects from the
input channels using a method li ke vmm_channel::get() or else the
object may be used multiple ti mes.
See also
vmm_scheduler_election, vmm_broadcast, vmm_xactor
A vmm_scheduler_election object defines the random constraints used by
the vmm_schedulers schedule() method to determine the input channel
and offset in the channel from which to extract the next transaction (i.e., the
elected transaction) every election cycle. There are 2 constraints defined: (1)
vmm_scheduler_election_valid, and (2) default_round_robin.
Constraint vmm_scheduler_election_valid determines if there are any
valid transactions to pick. Constraint default_round_robin picks the next
input channel and channel offset for the next transaction.
In order to create a custom scheduling algorithm for a vmm_scheduler, the
vmm_scheduler_election class can be extended wi th its own custom
constraints, or the constraints can be turned off in the vmm_schedulers
randomized_sched instance, resulting in a random transaction scheduling
instead of in round-robin fashion.
Declaration
class vmm_scheduler_election;
Members
constraint default_round_robin; Constraint used to select
transactions in a round-robin
fashion.
constraint
vmm_scheduler_election_valid;
Constraint used to determine if
any transactions are available.
int unsigned election_id; ID incremented by the
scheduler before every
election cycle.
int unsigned id_history[$]; A queue of the last 10 input
channel IDs that were selected
int unsigned ids[$]; Unique input channel IDs
corresponding to the channels
in the sources[$] queue.
int instance_id; Identifier of the
vmm_scheduler instance
randomizing this
object.
int unsigned n_sources; Number of input sources.
int unsigned next_idx; Next input channel ID to
select. Used by round-robin
algorithm.
vmm_data obj_history[$]; Queue of the last 10
transactions selected.
rand int unsigned obj_offset; Offset of selected transaction
within the source channel.
The default_round_robin
constraint constrains this to 0.
vmm_channel sources[$]; Queue of input channel
sources.
rand int unsigned source_idx; Index of input channel from
which to elect the next
transaction.
Example
//
// Example of replacing the vmm_scheduler_election constraints
//
class custom_algorithm extends vmm_scheduler_election;

// Disable the round robin constraint
constraint default_round_robin { /* empty */ };

// Custom function that picks the source channel which has the greatest
// number of transactions to relieve back-pressure
function void post_randomize();
int qsize;

foreach ( srcs[i] )
if ( srcs[i].size() > qsize ) begin
qsize = srcs[i].size();
source_idx = i;
end
endfunction

// obj_offset is still set by the base classs
// vmm_scheduler_election_valid constraint

endclass

//
// Example of disabling constraints
//
my_scheduler sched;
trans_channel channels[4];
trans_channel dst;
...

sched = new ( "scheduler, "sched, dst );

foreach ( channels[i] ) begin
channels[i] = new ( ... );
sched.new_source( channels[i] );
end

// Disable the round-robin constraintmake election random
sched.randomized_sched.default_round_robin.constraint_mode(0);

// Could have also replaced the algorithm to disable the constraint:
// custom_algorithm cstm = new;
// sched.randomized_sched = cstm;
...
endfunction
endclass
Tips
While most of the members of the vmm_scheduler_election class are
used by the vmm_scheduler to perform the default round robin
scheduling, only source_idx and obj_offset are actually required to be
set for the vmm_scheduler.
Use the pre_randomize() and post_randomize() functions (example
shown above) to create custom scheduling election algorithms.
See also
vmm_scheduler
Shorthand Macros
The shorthand member macros automate the creation of various utili ty methods
for several VMM classes. Each member inside a class must be specified using
the macros so that they can be included in all the generated methods.
There are five components that use the shorthand member macrosvmm_data,
vmm_xactor, vmm_env, vmm_subenv, and vmm_scenario. The shorthand
macros provide the following methods:
vmm_data
vmm_scenario
vmm_xactor vmm_env vmm_subenv
allocate
byte_pack
byte_size
byte_unpack
copy
compare
is_valid
max_byte_size
new
psdisplay
psdisplay
kill_xactor
reset_xactor
start_xactor
stop_xactor
psdisplay
reset
start
stop
vote
psdisplay
reset
start
stop
vote

While the macros create different methods from component to component, the
same set of member macros are provided for the different components in the
following form:
`class_member_datatype ( name, do [, how] )
where class is one of vmm_data, vmm_scenario, vmm_xactor,
vmm_env or vmm_subenv and datatype is one of the following shorthand
macros:
Shorthand Macros
Macro Declares member
type:
`class_member_begin( class ) Starts the shorthand
section
`class_member_end( class ) Ends the shorthand
section
`class_member_enum( name, do ) Enumeration
Shorthand Macros
`class_member_enum_aa_scalar( name,
do )
Scalar-indexed
associati ve array of
enumerations
`class_member_enum_aa_string( name,
do )
String-indexed
enumerations
`class_member_enum_array( name, do ) Fixed array of
enumerations
`class_member_enum_da( name, do )
(vmm_data and vmm_scenario only)
Dynamic array of
enumerations.
`class_member_scalar( name, do ) Integral type
(E.g., bit, bit vector,
packed data type etc.)
`class_member_scalar_aa_scalar( name,
do )
Scalar-indexed
scalars
`class_member_scalar_aa_string( name,
do )
String-indexed
scalars
`class_member_scalar_array( name, do ) Fixed array of scalars
`class_member_scalar_da( name, do )
Dynamic array of
string
`class_member_string( name, do ) String
`class_member_string_aa_scalar( name,
do )
Scalar-indexed
strings
`class_member_string_aa_string( name,
do )
String-indexed
strings
`class_member_string_array( name,
do )
Fixed array of strings
`class_member_string_da( name, do )
Dynamic array of
string
`class_member_user_defined( name ) User-defined
implementation
`class_member_vmm_data( name, do, how) vmm_data member
`class_member_vmm_data_aa_scalar(
name, do, how )
Scalar-indexed
vmm_data members
Shorthand Macros
`class_member_vmm_data_aa_string(
name, do, how )
String-indexed
vmm_data members
`class_member_vmm_data_array(
name, do, how )
Fixed array of
vmm_data members
`class_member_vmm_data_da(
name, do, how )
Dynamic array of
vmm_data members

vmm_data / vmm_scenario specific
type:
`class_member_handle( name, do ) Class handle
`class_member_handle_aa_scalar( name,
do )
Scalar-indexed
class handles
`class_member_handle_aa_string( name,
do )
String-indexed
class handles
`class_member_handle_array( name,
do )
Fixed array of class
handles
`class_member_handle_da( name, do ) Dynamic array of
class handles
`class_new( class ) Turns off the
automatic constructor
definition
`class_member_vmm_scenario(
name, do, how )
(vmm_scenario only)
vmm_scenario
member

vmm_xactor / vmm_env / vmm_subenv specific
type:
`class_member_channel( name, do ) Channel member
`class_member_channel_aa_scalar(
name, do )
Scalar-indexed
channels
`class_member_channel_aa_string(
name, do )
String-indexed
channels
Shorthand Macros
`class_member_channel_array( name,
do )
Fixed array of
channels
`class_member_channel_aa_scalar(
name, do )
Scalar-indexed
channels
`class_member_xactor( name, do ) vmm_xactor
member
`class_member_xactor_aa_scalar( name,
do )
Scalar-indexed
xactors
`class_member_xactor_aa_string( name,
do )
String-indexed
xactors
`class_member_xactor_array( name,
do )
Fixed array of xactors

vmm_env / vmm_subenv specific
type:
`class_member_subenv( name, do ) vmm_subenv
member
`class_member_subenv_aa_scalar( name,
do )
Scalar-indexed
subenvs
`class_member_subenv_aa_string( name,
do )
String-indexed
subevns
`class_member_subenv_array( name,
do )
Fixed array of
subenvs
Actions
With each member macro, there is a do action that must be specified. This
indicates what actions to automatically generated. These actions can be OR-ed
or added together to turn on certain actions as well as subtracted to turn off the
action. The vmm_data member macros also include a how field that specifies
how the copying and comparing should be done. These options are listed in the
following tables.
Macro do actions
DO_PRINT Print member
Shorthand Macros
DO_COPY Copy member
DO_COMPARE Compare member
DO_PACK Pack member
DO_UNPACK Unpack member
DO_ALL Do all automation

Macro how field
DO_NOCOPY Do not copy member
DO_REFCOPY Copy only member references
(shallow copy)
DO_DEEPCOPY Deep copy
HOW_TO_COPY Both REFCOPY and DEEPCOPY
DO_NOCOMPARE Do not compare members
DO_REFCOMPARE Compare using only references
DO_DEEPCOMPARE Deep compare (compare all sub-
members)
HOW_TO_COMPARE Both REFCOMPARE and
DEEPCOMPARE
DO_NONE Skip all copying and comparison
DO_REF All DO_REF*
DO_DEEP All DO_DEEP*
Overriding Methods
When the shorthand macros are used, they define the various functions like
copy() and compare(), which means that these methods can no longer be
user defined. However, these functions can be overridden by defining a do
version of the method. For example, to customize the psdisplay() method, a
do_psdisplay() function can be defined as follows:
virtual function string do_psdisplay( string prefix = "");
// Custom display with an ANSI color
$sformat( do_psdisplay,
"\034[34m %s: (%s.%s) data = %d, addr = %d \034[0m",
prefix, this.name, this.inst, this.data, this.addr );

endfunction
Now when the psdisplay() method is called, it will invoke the user-defined
do_psdisplay() method instead of providing the built-in functionality.
Shorthand Macros
Non-member macros
Both the vmm_data and vmm_scenario classes include some non-member
shorthand macros that are also useful. By default, the shorthand macros
automatically create a class new constructor. This can be disabled by using
either `vmm_data_new() or `vmm_scenario_new(), respecti vely. The
constructor macro must be called before the member macros begin in order to
disable the constructor generation. Another macro,
`vmm_data_byte_size( max, n )
defines the max_byte_size() and byte_size() methods automatically. The
_max field specifies the value returned by max_byte_size() and _n the value
returned from byte_size().
Example
class mac_frame extends vmm_data;
plcp_frame plcp_history[];
plcp_frame current_frame;
int crc;

`vmm_data_member_begin ( mac_frame )
`vmm_data_member_scalar( crc, DO_ALL )
`vmm_data_member_handle_da( plcp_history, DO_ALL )
`vmm_data_member_vmm_data( current_frame, DO_ALL,
DO_DEEP)
`vmm_data_member_end ( mac_frame )
endclass

class ahb_trans extends vmm_data;
rand int data;
rand int addr;
rand enum { READ, WRITE } kind;

// Automate everything but the compare() function
`vmm_data_member_begin ( ahb_trans )
`vmm_data_member_scalar( data, DO_ALL DO_COMPARE )
`vmm_data_member_scalar( addr, DO_ALL DO_COMPARE )
`vmm_data_member_enum( kind, DO_ALL DO_COMPARE )
`vmm_data_member_end ( ahb_trans )

function bit do_compare( vmm_data to,
output string diff,
input int kind = -1 );
if ( to == null ) begin
Shorthand Macros
diff = "to argument is null!";
return 0;
end

if ( to.addr == this.addr && to.data == this.data )
return 1;
else
begin
diff = "these two are not equal!";
return 0;
end
endfunction
endclass
Tips
Action values can be OR-ed or added together like this:

`vmm_data_member_scalar( addr, DO_PRINT + DO_COPY +
DO_COMPARE )
or subtracted:

`vmm_data_member_scalar( addr, DO_ALL DO_IS_VALID )
While a do_method() should not invoke its super class (i.e.,
super.do_method()), a do_method() does not need to totally override
the bui lt-in default functionality. In order to do an action first and then
perform the bui lt-in functionality, add the following assignment inside the
user-defined method:

function vmm_data copy( vmm_data to = null );
this.__vmm_done_user = 0;
...
Gotchas
When creating your own custom utility methods, do not call the parent base
class (i.e., using super()).
The constructor macro must precede the begin macro.
See also
vmm_data, vmm_scenario, vmm_xactor, vmm_env, vmm_subenv
vmm_simulation
The vmm_simulation class is a top-level singleton that controls the execution
of the pre-test, top-test, and post-test si mulation ti melines. It is used to start the
execution of tests, and can also be used to insert additional phases in the global
timelines.
Declaration
class vmm_simulation extends vmm_unit;
Methods
function new(); Constructor.
allow_new_phases(
bit allow = 1 );
Allows the addi tion of user-
defined phases in ti melines.
display_phases();
Displays how the phases will
be executed in each timeline.
static function vmm_timeline
get_post_timeline();
post-test ti meline.
get_pre_timeline();
Returns a reference to the pre-
test ti meline.
static function vmm_simulation
get_sim();
Returns a reference to the top-
level singleton
vmm_simulation object.
get_top_timeline();
Returns a reference to the top
test ti meline.
static function void list(); Lists all avai lable tests.
static task run_tests(); Runs either the default
testcase or the test(s)
specified on the command
line.
Example
// Call run_tests() and display all the phases
program TB;
ìnclude "vmm_sv"

class my_test extends vmm_test;
function void start_of_sim_ph();
vmm_simulation::display_phases();
endfunction
endclass
vmm_simulation

my_xactor xactor;
...
endclass

initial begin
my_test t1 = new ( "t1" );
my_env env = new ( "env" );
...
vmm_simulation::run_tests();
end
endprogram

// Add a new phase
program P;

// New phase
virtual task init_registers_ph();
...
endtask
endclass

// New phase definition
class init_registers_def extends vmm_forked_task_phase_def
#( my_test );
`vmm_typename ( init_registers_def )

task do_task_phase ( my_test t );
if (t.is_enabled())
t.init_registers_ph();
endtask
endclass

my_test t;
init_registers_def init_reg_def;

initial begin
init_reg_def = new;
t = new;

vmm_simulation
// Enable user phases
vmm_simulation::allow_new_phases();

// Add the new phase before "start"
vmm_simulation::insert_phase("init_registers_ph",
"start",
init_reg_def );
end
endprogram
Tips
The VMM specification recommends calling display_phases() after the
build phase.
The test(s) run by run_tests() is determined as follows:
o If the command line argument +vmm_test or
+vmm_test_file is specified, then use the specified tests:

+vmm_test_file=<filename> File list of test to run
+vmm_test=<test> Test case to run
+vmm_test=<test>+<test>+... List of test cases to run
+vmm_test=ALL_TESTS Run all declared tests

o If no +vmm_test/+vmm_test_file AND only one defined top-
level tests, then execute that test.
o If no +vmm_test/+vmm_test_file AND multiple top-level tests
defined, then a warning message is printed and no test is run.
Gotchas
By default, user defined phases are not allowed and wi ll issue an error
message unless allow_new_phases() is called.
A fatal error message will be issued if a user defined phase is added to a
non-existent phase.
See also
Phases, vmm_timeline, vmm_test
vmm_ss_scenario
The vmm_ss_scenario #(T) class defines a single-stream scenario where T
is the transaction type that is generated by the scenario. Each single-stream
scenario contains an items[] array for the transaction objects generated by the
scenario. The length of a scenario (set by define_scenario()) limits the
number of transactions generated. A scenarios default apply() method wi ll
copy the randomized transaction objects from items[] into a scenario
generators output stream. For greater control or creating hierarchal scenarios,
the apply() can be overwritten to create a custom algorithm such as calling
other scenarios or modifying transactions before being placed into the output
channel. See the article on Scenarios for more detai ls.
Declaration
class vmm_ss_scenario_base extends vmm_scenario;
class vmm_ss_scenario #( type T = vmm_data ) extends
vmm_ss_scenario_base;
Methods
function new(); Constructor.
function void
allocate_scenario(
T using = null);
Allocates new transaction
objects for the items[] array
using copies of using if
defined.
virtual task apply(
vmm_channel_typed#(T)
channel,
ref int unsigned n_insts);
Applies the transactions in the
items[] array into the output
channel.
n_insts should be
incremented wi th the number of
items copied into the output
channel.
copy(
Copy method.
Returns a reference to a single-
stream scenario of the specific
type.
vmm_ss_scenario
define_scenario(
string name,
Defines a new scenario name
and sets the maxi mum length of
the transaction stream (i.e.,
number of transactions to
generate).
Returns an integer scenario kind
identifier which can be used for
specifying scenario kind related
constraints.
function void fill_scenario(
T using = null);
Extends the items[] array to
the maxi mum length and fills all
empty locations by copying
using if defined.
function void pre_randomize(); Pre-randomization method that
calls fill_scenario().
Override method to allocate the
items[] array differently.
psdisplay(
the scenario.
function void
redefine_scenario(
string name,
Redefines a scenarios name or
maxi mum length.
int unsigned scenario_kind
= 0);
scenario_kind.
Members
rand T items[]; Array of transaction T items
generated by the scenario.
static vmm_log log; Class-wide available message
service.
rand int unsigned
repeated = 0;
Number of times to repeat the
scenario.
static int unsigned
repeat_thresh = 100;
Maxi mum number of times to
repeat a scenario.
vmm_ss_scenario
rand int unsigned
scenario_kind;
Numeric ID assigned to a
scenario when registered with
define_scenario().
int scenario_id; Inherited from vmm_scenario.
Generators scenario count
constraints.
int stream_id; Inherited from vmm_scenario.
Generators stream ID assigned
before randomization used by
other components (like a
scoreboard) to differentiate
transactions.
constraint T_scenario_valid; Constraint that limi ts items[]
size to length.
T using; Factory pattern template
variable used to fill the
items[] array.
Example
//
// Random register write sequence
//
`vmm_scenario_gen( ahb_trans )
class rand_reg_scenario extends ahb_trans_scenario;
int id = define_scenario( "Random Reg", 0 );
int reg_addrs[] = '{ CFG1_REG, CNTR_REG, ... };

function void pre_randomize();
reg_addrs.shuffle; // Randomize the array
endfunction

constraint write_regs {
length == reg_addrs.size();

foreach ( items[i] ) {
items[i].addr = reg_addrs[i];
items[i].mode = WRITE;
}
}
vmm_ss_scenario

virtual task apply( ahb_trans_channel channel,
`vmm_note( log, "Generating register writes ..." );
super.apply( channel, n_insts );
endtask
endclass
Tips
Use the `vmm_scenario_gen macro to simplify creating single-stream
scenarios.
For a single item scenario, use the vmm_atomic_scenario #(T)
automatically generated by `vmm_scenario_gen().
Use stream_id for stream related constraints, and scenario_id to
constraint for specific scenarios.
Gotchas
Even if the repeated value is set to greater than 0, the generators
scenario count is only incremented once for a scenario regardless of the
number of times it is repeated.
See also
Scenarios, vmm_scenario, vmm_scenario_gen, vmm_ms_scenario
vmm_subenv
VMM encourages the reuse of testbench components between block and
system-level environments through the use of sub-environments. A sub-
environment is a self-contained component that generally includes a moni tor,
driver, transactor, and some type of self-checking. In order to remain reusable,
VMM encourages constructing sub-environments according to the following
guidelines
A sub-environment should have transaction-level inputs and outputs.
For explicitly phased environments, a sub-environment should be derived
from `VMM_SUBENV so it can be re-targetable from the command line.
For implicitly phased environments, a sub-environment should be derived
from vmm_group.
Physical interfaces should be passed using a custom bind_vif()
function, or by wrapping the virtual interface in a custom class wrapper and
setting the custom class wrapper from the top level using the
vmm_opts::set_object() facility.
A sub-environment should include a configure() method for configuring
itself and its sub-components.
The configure() method should call super.configured() upon
completion so the environment can be started.
The configure() method should configure the design using the register
abstraction layer.
A sub-environment should include a configuration descriptor, which is set
using the vmm_opts::set/get object() facility.
A vmm_consensus instance should be passed as a constructor argument
to indicate that the sub-environment has reached its end-of-test condition.
Declaration
class vmm_subenv extends vmm_group;
Methods
function new(
string name,
string inst,
vmm_consensus end_test,
end_test is used to signal
the sub-env has reached its
end-of-test condition.
virtual task cleanup();

Stops the sub-environment
and tests for end-of-test
conditions.
Requires super.cleanup().
vmm_subenv
protected function void
configured();
Sets the sub-environments
state as configured.
Required by the start()
method.
function void do_all(
do_what_e what,
vmm_env::restart_e
restart_kind = vmm_env::FIRM);
Method for configuring the
design.
protected virtual function
string do_psdisplay(
psdisplay() method
created by the vmm_subenv
shorthand macros.
do_reset(
vmm_env::restart_e kind);

reset() method created by
the vmm_subenv shorthand
macros.
do_start();
start() method created by
the vmm_subenv shorthand
macros.
do_stop();
overriding the default stop()
method created by the
vmm_subenv shorthand
macros.
do_vote();
end_vote() method created
by the vmm_subenv
shorthand macros.
function vmm_consensus
get_consensus();
Returns the end-of-test
consensus.
psdisplay(
Function to print out sub-
environment information.
virtual function void report(); Method for reporting the
success or failure of a test.
virtual task reset(
vmm_env::restart_e
kind = vmm_env::FIRM);
Resets the sub-environment.
virtual task start() Starts the sub-environment.
vmm_subenv
virtual task stop(); Stops the sub-environment.
Members
typedef enum {
DO_PRINT,
DO_START,
DO_STOP,
DO_RESET,
DO_VOTE,
DO_ALL } do_what_e;
this component.
protected vmm_consensus
end_test;
Notifies end-of-test condition
reached.
Macros
`VMM_SUBENV Extended user-defined sub-
environments should extend
using this macro.
Default is vmm_subenv.
Shorthand Macros
The vmm_subenv shorthand macros are a way of defining an environment wi th
automatically generated psdisplay(), start(), stop(), reset(), and
vote()
10
methods that have a default implementation. The macros are placed
between a `vmm_subenv_member_begin/`vmm_subenv_member_end pair.
Each macro has a do_what_e field, which specifies the methods to
automatically generate. The enumeration values can be OR-ed together for
specific methods or DO_ALL for all methods. The default i mplementation for
these methods can be extended or overwritten by defining a do_psdisplay(),
do_start(), do_stop(), do_reset(), or do_vote() method, respecti vely.
Begin / end macros
`vmm_subenv_member_begin( class )
`vmm_subenv_member_end ( class )

10
Automatically registers a member with the vmm_env::end_vote consensus
instance.
vmm_subenv
Scalar data members
`vmm_subenv_member_scalar( name, do )
`vmm_subenv_member_scalar_array( name, do )
`vmm_subenv_member_scalar_aa_scalar( name, do )
`vmm_subenv_member_scalar_aa_string( name, do )
`vmm_subenv_member_enum( name, do )
`vmm_subenv_member_enum_array( name, do )
`vmm_subenv_member_enum_aa_scalar( name, do )
`vmm_subenv_member_enum_aa_string( name, do )
String data members
`vmm_subenv_member_string( name, do )
`vmm_subenv_member_string_array( name, do )
`vmm_subenv_member_string_aa_scalar( name, do )
`vmm_subenv_member_string_aa_string( name, do )
VMM data members
`vmm_subenv_member_vmm_data( name, do )
`vmm_subenv_member_vmm_data_array( name, do )
`vmm_subenv_member_vmm_data_aa_scalar( name, do )
`vmm_subenv_member_vmm_data_aa_string( name, do )
`vmm_subenv_member_channel( name, do )
`vmm_subenv_member_channel_array( name, do )
`vmm_subenv_member_channel_aa_scalar( name, do )
`vmm_subenv_member_channel_aa_string( name, do )
`vmm_subenv_member_xactor( name, do )
`vmm_subenv_member_xactor_array( name, do )
`vmm_subenv_member_xactor_aa_scalar( name, do )
vmm_subenv
`vmm_subenv_member_xactor_aa_string( name, do )
Sub-environment data members
`vmm_subenv_member_subenv( name, do )
`vmm_subenv_member_subenv_array( name, do )
`vmm_subenv_member_subenv_aa_scalar( name, do )
`vmm_subenv_member_subenv_aa_string( name, do)
`vmm_subenv_member_user_defined( name )
Example
class my_subenv_cfg;
// Put config information here
endclass : my_subenv_cfg

class my_subenv extends vmm_subenv;
my_subenv_cfg cfg;
virtual dut_intf.tb dut_if;

tx_channel tx_chan;
my_scoreboard sb;
my_monitor mon;
my_driver drv;
my_atomic_gen gen;
my_ral_block ral;

function new ( string inst,
vmm_consensus end_test,
tx_channel chan,
virtual dut_intf.tb dut_if = null );
super.new ( "my_subenv", inst, end_test );
this.dut_if = dut_if;

if (tx_chan == null) begin
gen = new( "my_subenv gen", inst );
tx_chan = gen.out_chan;
end
this.tx_chan = chan;

vmm_subenv
sb = new ( inst, cfg );
mon = new ( inst, cfg, dut_if.mon );
drv = new ( inst, cfg, tx_chan, dut_if.drv );
endfunction : new

task configure();
ral.CONFIG.set(1); // Configure DUT using RAL
...
super.configured(); // Required for start()
endtask : configure

function void start();
super.start(); // Must call parent method!

// Start components
mon.start_xactor();
drv.start_xactor();
gen.start_xactor();

// Send received data to the scoreboard
fork
forever begin
trans tr;
mon.rx_chan.get( tr );
sb.put( tr );
end
join_none

// Setup for end-of-test
this.end_test.register_notification( gen.notify,
my_atomic_gen::DONE );
this.end_test.register_channel( tx_chan );
this.end_test.register_xactor( drv );
this.end_test.register_xactor( mon );
endfunction : start

task stop();
super.stop(); // Call parent method!
gen.stop_xactor();
drv.stop_xactor();
mon.stop_xactor();
endtask : stop

endclass : my_subenv
vmm_subenv
Tips
When constructing a testbench, partition related components into a sub-
environment to maxi mize reuse between block and system-level
environments.
A sub-environment should define a configure() method that calls
super.configured().
Gotchas
Extended i mplementations of cleanup(), start(), and stop()
methods must call their base class methods via super.method_name().
The start() method wi ll throw an error unless the configured()
method has been called.
See also
vmm_env, vmm_group
vmm_test
The vmm_test class is extended from the vmm_timeline and manages the
top-test timeline and its defined phases. It handles the registering of test cases,
and it provides a set_config() method that allows a single test case to
execute code before a testbench environment is constructed in the pre-test
timeline.
Declaration
class vmm_test extends vmm_timeline;
Methods
function new(
string name = "",
string doc = "",
Constructor.
name is the name of the
instance and doc refers to a
user comment or
documentation like Reset
Test.
get_doc();
the test.
get_name();
Returns the name of the test
case.
function bit has_config_done(); Returns 1 upon complete of
set_config().
virtual task run(vmm_env env); Provided for backward
compatibility wi th VMM 1.1.
Calls the environments run
task to execute the legacy
VMM steps like gen_cfg,
reset_dut, build, start, stop,
etc.
See the `vmm_test_begin
macro below.
set_config();
Optionally user-defined
function that get executed
before the pre-test ti meline.
Useful for setting factory
configuration information
before the environment is
constructed.
vmm_test
Macros
`vmm_test_begin( testclassname, envclassname, doc )
`vmm_test_end ( testclassname )
These macros are provided for backwards compatibility wi th VMM 1.1, which
executes steps gen_cfg, reset_dut, build, run, etc., but does not use the phasing
mechanism provided wi th VMM 1.2.
These macros create, instantiate, and register a test class. They also create the
run() task around the test case functionality. They provide a simple way to
define a test because only the run step functionali ty needs to be defined,
sandwiched between these two macros. Also, the macros create the test
constructor and register the test with the vmm_test_registry class.
It is important to note that tests created using these macros are statically
instantiated and are therefore visible to the environment. Likewise, the
environment is made visible to the test case, allowing it to register callbacks,
replace generators, traverse the testbench hierarchy, or anything else normally
done in a program block.
Since only the run() task is defined, vmm_simulation::run_tests() will
not execute the test case because the test has no defined phase callback (e.g.,
no run_test_ph()). Rather, vmm_test_registry::run(env) can be
used kick off the test and execute the traditional VMM steps.

`vmm_test_concatenate( starting-phase )
When multiple tests are to be executed, a test may specify itself as concatenable
with other tests by using the `vmm_test_concatenate macro. This macro is
placed inside the test class, and the phase to start the test is passed to the
macro. This automatically creates a concatenate_test_n_reset_phase()
function that will be invoked by the top-test ti meline to reset to the specified
phase when the test is executed.
Example
Example using set_config()
program P;
`vmm_typename ( test1 )
function new ( string name = "" );
super.new ( name );
endfunction

// Swap out a testbench component created by the factory
function void set_config();
vmm_test

// Replace with error injecting generator
typical_gen::override_with_new (
"@%*",
error_gen::this_type(),
`__FILE__,
`__LINE__ );
endfunction
endclass

test1 t;
initial begin
t = new ( "test1" );
vmm_simulation::run_tests(); // Kick off tests
end
endprogram : P
Example using test macros
class odd_data extends data_trans;
contraint special { data[0] == 1 };
endclass

`vmm_test_begin ( test1, env, "Test case 1" )
`vmm_note(log, {"Starting test ", get_name() });
env.build(); // Build the environment

// Swi tch to the different transaction type
begin
odd_data t = new;
env.gen.randomized_obj = t;
end
env.run(); // Generate the transactions
`vmm_note(log, { get_name(), " test done." });
`vmm_test_end ( test1 )

program TB;
ìnclude "vmm.sv"
initial begin
my_env env = new;
// Run the test cases
vmm_test_registry::run(env);
end
endprogram : TB
vmm_test
Tips
Since vmm_test extends vmm_timeline, the method run_phase("$") can
be called on a test object to kick off the simulation phases.
Gotchas
The set_config() method can only be used when one test is executing
(i.e., it does not work for test concatenation). If multiple tests are specified
to execute, those that have a set_config() method will be removed from
the execution list.
The `vmm_test_begin/`vmm_test_end macros do not work wi th the
new VMM 1.2 phasing so vmm_test_registry::run(env) needs to be
called instead of the vmm_simulation::run_tests() (details above).
See also
vmm_ti meline, vmm_simulation, vmm_test_registry
vmm_test_registry
The vmm_test_registry class is used for globally registering testcases to run
for simulation. While an instance of vmm_test_registry can be used, all
methods are static and globally accessible, and the test registry exists as a
singleton entity.
The run() method starts the execution of the registered testcases. If none are
specified, then a special Default testcase is created and started that invokes
env::run(). When more than one testcase is register, it must be specified on
the command line using +vmm_test. The VMM guidelines require that
vmm_test_registry::run() be invoked from within a SystemVerilog
program.
Declaration
class vmm_test_registry;
Methods
static function void list(); Displays a list of all registered
test cases.
static task run(
vmm_env env);
Starts the execution of a
registered testcase and
invokes env.run().
If no testcase is registered,
then a default testcase is
created and run.
If more than one testcase is
registered, then a test name
must be specified using the
command line option
+vmm_test.
Example
program t;

ìnclude "tests.sv" // Include all tests
my_env env = new();

initial
vmm_test_registry::run( env );

endprogram
vmm_test_registry
Tips
The `vmm_test_begin/`vmm_test_end macros automatically create a
testcase and invoke vmm_test_registry::run(env).
Gotchas
The VMM 1.2 phasing runs testcases differently from
vmm_test_registry::run(env). Use
vmm_simulation::run_tests() to execute test(s) using the new VMM
1.2 simulation semantics.
See also
vmm_simulation
vmm_timeline
The control of the phasing in VMM occurs through the vmm_timeline class.
The root vmm_unit objects are implicitly controlled by the pre-test, top-test, and
post-test ti melines located in the vmm_simulation class, but timelines can be
inserted anywhere inside the testbench hierarchy to insert addition phases or re-
arrange the order of execution.
Timeline Execution
When a timeline is inserted within a testbench hierarchy, it becomes a sub-
timeline of the higher-level global ti melines. For example, vmm_test extends
vmm_timeline, so test cases are examples of sub-timelines that execute under
the global pre-test, top-test, and post-test ti melines. When a sub-timeline is
encountered, all the phases are executed up to the currently executing phase in
the immediate higher level timeline.
Ti melines and their phases refer to the progress of the overall si mulation, not the
state of the threads in the si mulation. Phase execution, including forked phases,
blocks until all components on a timeline complete a phase before movi ng on to
the next phase. Therefore, components should never define infinite loops within
their phase methods or timeline execution wi ll be blocked. Rather, components
should fork off blocking tasks such as main() so that timeline execution can
proceed. This means that the execution of tasks in a transactor, such as
main(), may continue across multiple timeline phases. A test finishes upon
completion of the run_test phase, when a vmm_unit (such as vmm_env)
consents to the end of a test and returns from the run_test_ph() task.
Controlling Phases
Ti melines can have additional phases added, removed, re-ordered, or even
renamed. The timeline class provides methods like insert_phase(),
add_phase(), rename_phase(), and others. A phase in a timeline can also
be overwritten using vmm_unit::override_phase().
Ti melines can step through phase execution phase-by-phase. Several methods
are provided to control phases like step_function_phase(), run_phase(),
reset_to_phase(), and abort_phase(). These methods provide a way to
control phase execution from within an environment, but an easier method is to
use the command line argument, +vmm_break_on_phase= X, where X is the
name of the phase to stop execution by a call to $stop. If a
vmm_timeline_callbacks object has been registered with the timeline, then
the break_on_phase() method will be invoked (if defined) instead of $stop.
Declaration
class vmm_timeline extends vmm_unit;
vmm_timeline
Methods
function new(
string name = "",
string inst = "",
Constructor.
function bit abort_phase(
string name,
string fname = "",
int lineno = 0);
Aborts the specified phase
name if currently executing,
prints a warning if phase name
has already completed, and
issues an error message if
phase name will be executed.
function bit add_phase(
string name,
vmm_phase_def def);
Adds phase definition, def, to
phase name .
Returns 1 upon success, and
prints a fatal error if phase
name does not exist.
configure_test_ph();
Phase used by a testcase to
configure the environment.
Executed at the beginning of
the test root ti meline.
function bit delete_phase(
string phase_name,
string fname = "",
int lineno = 0);
Deletes the phase
phase_name from the
specified timeline.
0 if phase_name does not
exist.
function void display_phases(); Displays phases remaining to
be executed.
function string
get_current_phase_name();
Displays currently executing
phase.
function string
get_next_phase_name(
string name);
following phase.
Returns $ if name is the last
phase, and ? if name is
unknown.
function vmm_phase get_phase(
string name);
Returns the phase descriptor
for phase name.
Returns null if phase name is
unknown.
vmm_timeline
function string
get_previous_phase(
string name);
preceding phase.
Returns ^ if phase name is
the first one, and ? if
unknown.
function bit insert_phase(
string phase_name,
string before_name,
vmm_phase_def def,
string fname = "",
int lineno = 0);
Inserts phase phase_name
before phase before_name
in the current timeline, and
issues a warning that a new
user-defined phase has been
defined.
A before_name of ^ inserts
at the beginning of a timeline,
and $ inserts at the end.
function bit jump_to_phase(
string name,
string fname = "",
int lineno = 0);
Aborts execution of the current
phase in this and sub-
timelines, jumps to phase
name, and issues a warning
message.
vmm_timeline_callbacks cb);
timeline callback.
function bit rename_phase(
string old_name,
string new_name,
string fname = "",
int lineno = 0);
Renames phase old_name
with the new phase name
new_name, and issues a
warning that the phase has
been renamed.
0 if phase old_name does not
exist new_name is a duplicate.
function void reset_to_phase(
string name,
string fname = "",
int lineno = 0);
Resets ti meline to phase
name.
If name is configure or
earlier, all vmm_units sub-
instances are re-enabled.
task run_phase(
string name = "$",
string fname = "",
int lineno = 0);
Executes phases in the
current timeline up to and
including the specified phase
name.
function void
run_function_phase(
string name);
Runs the specified phase.
vmm_timeline
function void
step_function_phase(
string name,
string fname = "",
int lineno = 0);
Executes function phase name
in the ti meline.
Phase name must be a
function phase and the next
executable phase or a warning
message is issued.
function bit
task_phase_timeout(
string name,
int unsigned delta
vmm_log::severities_e
error_severity
=vmm_log::ERROR_SEV,
string fname = "",
int lineno = 0);
Sets the ti meout value for the
completion of phase name,
and issues an error message if
the task phase does not
complete before the timeout.
A timeout value of 0 specifies
no timeout. Delta refers to the
number of time uni ts specified
by the `timescale or
timeunit.
0 if phase does not exist or is
not a task phase.
function void
vmm_timeline_callbacks cb);
Unregisters the ti meline
callback.

vmm_timeline_callbacks
Declaration
virtual class vmm_timeline_callbacks;
Methods
break_on_phase(
vmm_timeline tl,
string name);
Callback method called when
the +break_on_X_phase
command line argument is
specified.
tl is the timeline instance and
name is the phase to break on.

vmm_timeline
Example
...
endclass
Example using run_phase
initial begin
my_test t = new ( "test1", "test1" );

// Cause the testcase to execute the bui ld phase
t.run_phase("build");

// Run all the phases
t.run_phase("$");
end

Example stepping through phases
initial begin
my_test t = new ("test1", "test1" );

t.run_phase("connect");

// Step to the next phase
t.step_function_phase("start_of_sim");
t.step_function_phase("reset");
...
end

Example setting a timeout
...
function void start_of_sim_ph();
vmm_timeline tl = this.get_timeline();

// Set reset ti meout of 20 ti me units
if (task_phase_timeout("reset", 20 ) == 0)
`vmm_error(log, "Problem setting timeout!");
endfunction
endclass
vmm_timeline
Example of removing a phase from a timeline
class generic_env extends vmm_env;
...
vmm_timeline tl = this.get_timeline();

tl.delete_phase("training");
tl.delete_phase("start");
endfunction
endclass

Example inserting a new phase
class memory_init_phase_def extends
vmm_topdown_function_phase_def#(vmm_unit);
`vmm_typename( memory_init_phase_def )

function void do_function_phase(vmm_unit obj);
obj.memory_init_ph();
endfunction
endclass

...

vmm_timeline tl;
memory_init_phase_def mem_init_ph = new;

// Insert the new memory initialization phase before "config_dut"
tl = this.get_timeline();
tl.insert_phase( "memory_init",
"config_dut",
mem_init_ph );
endfunction
endclass

// Now define the memory_init_ph function for my_env
function void my_env::mem_init_ph();
// Read in memory values
...
endfunction
vmm_timeline
Tips
When inserting a phase with insert_phase(), a before_phase of ^
inserts the phase at the beginning of the timeline, and $ inserts at the end.
Using a task phase ti meout is a good way to avoid simulation hangs from
wai ting or looping in a task.
For greatest usability, adding phases to the top-level timeline should be
avoided. Instead, new phases should be added in a vmm_units build
phase by inserting into its enclosing ti meline (see examples above).
To skip the execution of a phase, the vmm_unit::override_phase()
method can also be used to replace a phase with the
vmm_null_phase_def class.
The +vmm_break_on_phase and +vmm_break_on_timeline command
line plusargs are useful for stepping through the si mulation phases.
The default phase name for run_phase() is $; therefore, run_phase()
can be called without arguments to execute all the phases.
Gotchas
Calling task_phase_timeout() while a phase is currently executing
causes the timer to be reset to the new value.
Calling reset_to_phase() wi ll re-enable any previous disabled sub-
modules.
Using jump_to_phase() to skip phases may skip necessary initialization
and configuration and seriously corrupt the state of a test environment.
This method should only be used to abort a testcase, si mulation, or jump to
the report phase.
See also
vmm_group, Phases, vmm_phase, vmm_si mulation, vmm_unit
TLM Interfaces
VMM implements a set of transport interfaces classes (not to be confused with
SystemVerilog interfaces) based on the OSCI TLM-2.0 standard which provide
standard transaction level modeling (TLM) communication. These methods exist
in blocking and non-blocking forms. Blocking methods may wait before
returning and are always tasks. Non-blocking methods are not allowed to wai t
and are implemented as functions. The interface methods are pure virtual tasks
and functions that must be implemented by a transactor.
Common to all TLM transport interface methods are the transaction object to be
transported, the phase, and the delay. While any data object can be passed, the
TLM-2.0 standard defines a basic transaction type called a generic payload,
defined in VMM as the vmm_tlm_generic_payload class, which extends
vmm_data. As a transaction is passed back and forth, its status (or the phase of
the object) may be updated and modified by the different components. The
various transaction phases are defined by the type vmm_tlm::phase_e as:

Type vmm_tlm::phase_e Meaning
BEGIN_REQ Beginning of the request phase.
END_REQ End of the request phase.
BEGIN_RESP Beginning of the response phase.
END_RESP End of the response phase.

The phases are not to be confused wi th the values returned from the non-
blocking transport method, which are defined by the type vmm_tlm::sync_e as

Type vmm_tlm::sync_e Meaning
TLM_ACCEPTED
Nei ther the transaction, the phase or
the delay argument were modified by
nb_transport.
TLM_UPDATED
nb_transport has modified the
transaction, phase and/or delay
argument.
TLM_COMPLETED
The transaction is complete. This is a
shortcut to the final phase.
TLM_REFUSED
Transaction refused by receiver. For
example, the recipients FIFO is too
full to receive the new transaction.

TLM Interfaces
The enum type vmm_tlm::inf_e gi ves the role played by the channel when
binding a TLM port to a vmm_channel:

Type vmm_tlm::intf_e
TLM_BLOCKING_PORT
TLM_BLOCKING_EXPORT
TLM_NONBLOCKING_FW_PORT
TLM_NONBLOCKING_FW_EXPORT
TLM_NONBLOCKING_PORT
TLM_NONBLOCKING_EXPORT
TLM_ANALYSIS_PORT
TLM_ANALYSIS_EXPORT

Blocking interfaces are used in one direction to transfer data from an initiator to a
target. The initiator blocks unti l the data transport completes so the initiator does
not manage the ti ming of the transaction. The transfer function has the name
b_transport().
The non-blocking interfaces provide unidirectional forward (initiator -> target) and
backward (target -> initiator) paths, appended with the suffi xes _fw and _bw,
respecti vely. Because the data transfer does not block and communication can
be made in both directions, the overall transaction may be broken down into
multiple phases, which allows for modelling a more approximately timed model.
These transfer functions are referred to as nb_transport_fw() and
nb_transport_bw().
TLM-2.0 also specifies a bidirectional interface known as a socket to simplify
connections and provide a more generic usage model. A socket combines the
blocking and non-blocking unidirectional interfaces into one easy-to-use
connection, providing a combination of the three functions (b_transport(),
nb_transport_fw(), and nb_transport_bw()).
The actual TLM connections are made using ports and exports. TLM ports and
exports are each associated wi th one of the TLM interfaces. They are used as
members of transactors and channels. TLM ports and exports provide a
mechanism to decouple the initiator and target of a transaction, providing
encapsulation and i mproving reusabili ty. An export provides the functional
implementation of the interface methods. It is used to terminate a chain of
connected ports and exports.
A unidirectional TLM port can be connected to any unidirectional TLM export
provided the transaction type is the same. Likewi se, a socket port can connect
to any socket export. The type of transaction carried by an interface, port or
TLM Interfaces
export is set by a type parameter. There are two socket classes
vmm_tlm_initiator_socket and vmm_tlm_target_socket. Both contain
a port and an export.
TLM-2.0 also specifies another special type of port called an analysis port. An
analysis port allows for more than one connection and broadcasts transactions
to all bound connections through its write() method.
Declarations
Blocking Unidirectional Ports and Exports
class vmm_tlm_b_transport_port
#(type INITIATOR = vmm_tlm_xactor,
type DATA = vmm_data)
extends ...;
class vmm_tlm_b_transport_export
#(type TARGET = vmm_tlm_xactor,
extends ...;

Non-blocking Unidirectional Ports and Exports
class vmm_tlm_nb_transport_fw_port
type DATA = vmm_data,
type PHASE = vmm_tlm::phase_e)
extends ...;
class vmm_tlm_nb_transport_fw_export
type PHASE = vmm_tlm::phase_e )
extends ...;
class vmm_tlm_nb_transport_bw_port
extends ...;
class vmm_tlm_nb_transport_bw_export
extends ...;

Analysis Port and Export
class vmm_tlm_analysis_port
TLM Interfaces
extends ...;
class vmm_tlm_analysis_export
extends ...;

Bidirectional Socket Ports and Exports
class vmm_tlm_nb_transport_port
type FW_PHASE = vmm_tlm::phase_e,
type BW_PHASE = FW_PHASE)
extends ...;
class vmm_tlm_nb_transport_export
type FW_PHASE = vmm_tlm::phase_e,
type BW_PHASE = FW_PHASE)
extends ...;
class vmm_tlm_initiator_socket
extends ...;
class vmm_tlm_target_socket
extends ...;
Methods
Common to all base classes
vmm_tlm_port_base
vmm_tlm_export_base
vmm_tlm_socket_base
vmm_tlm_analysis_port_base
vmm_tlm_analysis_export_base
function check_bindings(); Checks bindings of ports and
exports and issues warnings if
anything is unbound.
function print_bindings(); Prints all ports and exports.
TLM Interfaces
function report_unbound(); Reports all unbound ports and
exports.
function vmm_tlm_TYPE
_base
#(DATA,PHASE) get_peer();
Returns the export bound to
this port, or null if unbound.
function void tlm_bind(
vmm_tlm_TYPE
_base
#(DATA,PHASE) peer,
int id = -1,
string fname = "",
int lineno = 0);
Binds TLM export peer to the
TLM port.
id used to distinguish between
multiple exports connected to
the port. An error is generated
if id is duplicated.
function void tlm_import(
vmm_tlm_TYPE
_base
#(DATA,PHASE) peer,
string fname = "",
int lineno = 0);
Imports a port from an inner
level of hierarchy to an outer
level.
function void tlm_unbind(
string fname = "",
int lineno = 0);
Unbinds a port, and issues a
warning if already unbound.

Where TYPE is:

TYPE
Class
export vmm_tlm_port_base
port vmm_tlm_export_base
socket vmm_tlm_socket_base
analysis_port vmm_tlm_analysis_port_base
analysis_export vmm_tlm_analysis_export_base

Unidirectional base classes
vmm_tlm_port_base
function new(
vmm_object parent,
string name,
vmm_log log);
Constructor.
function int get_peer_id(); Returns id of the export
bound to this port.
Returns -1 if unbound.
virtual task b_transport(
DATA trans,
ref int delay);
Blocking transport function
(initiator -> target).
Must be i mplemented by
derived classes.

TLM Interfaces
virtual function
vmm_tlm::sync_e nb_transport_bw(
DATA trans,
ref PHASE ph,
ref int delay);
Non-blocking backward
transport function (target ->
initiator).
derived classes.
virtual function
vmm_tlm::sync_e nb_transport_fw(
DATA trans,
ref PHASE ph,
ref int delay);
Non-blocking forward
transport function (initiator ->
target).
derived classes.

function new(
vmm_object parent,
string name,
vmm_log log);
Constructor.
function int get_n_peers(); Returns the number of
bindings.
Returns 0 if unbound.
function int get_peer_id(
#(DATA) peer);
Returns id of the export peer.
function get_peers(
#(DATA) peers[$]);
Returns a queue of all port
bindings on export peers.
virtual function void write(
DATA trans);
Broadcasts data transaction to
all bound exports.
derived classes.

vmm_tlm_export_base
function new(
vmm_object parent,
string name,
int max_binds = 1,
int min_binds = 0,
vmm_log log);
Constructor.
max_binds and
min_binds sets the
number of bindings
allowed/required for this
export.
export bindings.
TLM Interfaces
vmm_tlm_port_base
#(DATA,PHASE) peer);
Returns id of the port
binding on peer.
function void get_peers(
vmm_tlm_port_base
#(DATA,PHASE) peers[$]);
bindings to this export.
virtual function
vmm_tlm::sync_e nb_transport_bw(
DATA trans,
ref PHASE ph,
ref int delay);
initiator).
derived classes.
virtual function
vmm_tlm::sync_e nb_transport_fw(
DATA trans,
ref PHASE ph,
ref int delay);
Non-blocking forward
transport function (initiator ->
target).
derived classes.

function new(
vmm_object parent,
string name,
int max_binds = 1,
int min_binds = 0,
vmm_log log)
Constructor.
max_binds and
min_binds sets the
number of bindings
allowed/required for this
export.
export bindings.
vmm_tlm_port_base
#(DATA,PHASE) peer);
Returns id of the port
binding on peer.
function void get_peers(
#(DATA) peers[$]);
bindings to this export.
int id = -1,
DATA trans);
Writes transaction to all
bound ports.
derived classes.
TLM Interfaces
Blocking unidirectional interfaces
vmm_tlm_b_transport_port
vmm_tlm_b_transport_export
task b_transport(
DATA trans,
ref int delay);
Blocking transport of data
trans.
Delay is for timing annotation.

Non-blocking unidirectional ports
vmm_tlm_nb_transport_fw_port
function vmm_tlm::sync_e
nb_transport_fw(
DATA trans,
ref PHASE ph,
ref int delay);
Non-blocking forward transport
of data trans.
Returns status (phase) of
transaction.

vmm_tlm_nb_transport_bw_port
nb_transport_bw(
DATA trans,
ref PHASE ph,
ref int delay);
transport of data trans.
transaction.

Non-blocking unidirectional exports
vmm_tlm_nb_transport_fw_export
nb_transport_fw(
int id = -1,
DATA trans,
ref PHASE ph,
ref int delay);
of data trans.
transaction.

vmm_tlm_nb_transport_bw_export
nb_transport_bw(
int id = -1,
DATA trans,
ref PHASE ph,
ref int delay);
transaction.
TLM Interfaces
Analysis interfaces
vmm_tlm_analysis_port
DATA trans);
Writes data transaction to all
bound interfaces.

vmm_tlm_analysis_export
DATA trans);
Writes data transaction to all
bound interfaces.

Bidirectional socket base class
vmm_tlm_socket_base
function new(
vmm_object parent,
string name,
vmm_log log);
Constructor.
DATA trans,
ref int delay);
Blocking transport function
(initiator -> target).
derived classes.
virtual function
vmm_tlm::sync_e
nb_transport_bw(
DATA trans,
ref PHASE ph,
ref int delay);
initiator).
derived classes.
virtual function
vmm_tlm::sync_e
nb_transport_fw(
DATA trans,
ref PHASE ph,
ref int delay);
function (initiator -> target).
derived classes.

Bidirectional non-blocking socket interfaces
vmm_tlm_nb_transport_port
vmm_tlm_nb_transport_export
nb_transport_fw(
DATA trans,
ref FW_PHASE ph,
ref int delay);
of data trans.
transaction.
Delay is for timing annotation
TLM Interfaces
nb_transport_bw(
DATA trans,
ref BW_PHASE ph,
ref int delay);
transaction.

Bidirectional blocking/non-blocking socket interfaces
vmm_tlm_initiator_socket
vmm_tlm_target_socket
DATA trans,
ref int delay);
Blocking transport of data
trans.
nb_transport_fw(
DATA trans,
ref FW_PHASE ph,
ref int delay);
of data trans.
transaction.
Delay is for timing annotation
nb_transport_bw(
DATA trans,
ref BW_PHASE ph,
ref int delay);
transaction.

Macros
VMM provides a set of convenience macros to automatically create the interface
classes.
`vmm_tlm_b_transport_export( SUFFIX )
`vmm_tlm_b_transport_export( SUFFIX )
`vmm_tlm_nb_transport_fw_export ( SUFFIX )
`vmm_tlm_nb_transport_bw_export ( SUFFIX )
`vmm_tlm_nb_transport_port ( SUFFIX )
`vmm_tlm_nb_transport_export ( SUFFIX )
`vmm_tlm_initiator_socket ( SUFFIX )
`vmm_tlm_target_socket ( SUFFIX )
`vmm_tlm_analysis_export ( SUFFIX )
TLM Interfaces
Example
Example using blocking TLM connections
class initiator extends vmm_xactor;
vmm_tlm_b_transport_port #( initiator, trans )
init_port = new( this, "initiator_p" );
int delay;
...
task main();
init_port.b_transport( trans, delay );
endtask
endclass

class target extends vmm_xactor;
vmm_tlm_b_transport_export #( target, trans )
target_export = new ( this, "target_exp" );
...
// The target needs to implement the b_transport() functionality
task b_transport ( trans t,
ref int delay );
// Drive the transaction onto an interface
@(v_intf.cb);
v_intf.cb.we = 1b1;
v_intf.cb.data = t.data; // Put transaction data on bus
@(v_intf.cb);
...
endtask
endclass

// Connect everything up in the environment
initiator I = new(...);
target T = new(...);

I.init_port.tlm_bind( T.target_export );
endfunction
endclass

Example using TLM non-blocking socket connections
vmm_tlm_nb_transport_port #( initiator, trans )
socket = new( this, "init_socket" );
TLM Interfaces
trans t = new;
vmm_tlm::phase_e ph;
int delay;
...
// Provide the backward path i mplementation for target export
function vmm_tlm::sync_e nb_transport_bw(
trans t, ref vmm_tlm::phase_e ph,
ref int delay);
`vmm_note(this.log,
t.psdisplay("Received trans from target"));
endfunction

// The main initiator task
task main();
...
forever begin
t.randomize();
t.notify.indicate( vmm_data::STARTED );
socket.nb_transport_fw( t, ph, delay );
t.notify.wait_for( vmm_data::ENDED );
#5;
end
endtask
endclass

vmm_tlm_nb_transport_export #( target, trans )
socket = new ( this, "target_socket" );
trans trans_q[$];
trans t;
...

virtual protected task main();
...
forever begin
wait( trans_q.size() > 0 );
t = trans_q.pop_front();
`vmm_note(this.log, t.psdisplay(
"Processing transaction"));
socket.nb_transport_bw( t, ph, delay);
end
endtask : main

TLM Interfaces
// The forward path implementation for the initiator port
function vmm_tlm::sync_e nb_transport_fw(
int id =-1, trans t,
ref vmm_tlm::phase_e ph,
ref int delay);
`vmm_note(this.log,
t.psdisplay("Received trans from initiator"));
trans_q.push_front( t );
t.notify.indicate( vmm_data::ENDED );
return vmm_tlm::TLM_ACCEPTED;
endfunction
endclass

initiator I;
target T;

I.socket.tlm_bind( T.socket );
endfunction
endclass

Example of analysis ports
vmm_tlm_nb_transport_fw_export#( target, trans ) socket
= new(this, "target_socket");
vmm_tlm_analysis_port #( target, trans ) write_port
= new ( this, "target_aport" );

...
// Write the received transaction to the listening subscribers
virtual function vmm_tlm::sync_e nb_transport_fw(
trans t, ref vmm_tlm::phase_e ph,
ref int delay );
t.notify.indicate( vmm_data::ENDED );
this.write_port.write( t ); // Write to subscriber
return vmm_tlm::TLM_ACCEPTED;
endfunction: nb_transport_fw
endclass

class subscriber extends vmm_xactor;
vmm_tlm_analysis_export #( subscriber, trans )
write_export = new ( this, "sub_export" );
TLM Interfaces
special_cov cg = new;
...

function write ( int id = -1, trans t );
`vmm_note ( this.log,
t.psdisplay( "Received trans..." ));
this.data = t.data; // Grab data locally
cg.sample(); // Sample the data
endfunction
endclass
Tips
Use the TLM macros simplify port/export declarations.
When a subscriber has multiple analysis exports, only one implementation
can be provided for all of the exports. If separate write()
implementations are needed, then either use (1) the shorthand macros with
individual write<ID>() functions, or (2) use the peer id argument of the
write() function to differentiate between the function invocations.
An exports constructor allows for the specifying of the mini mum number of
bindings. Set the mini mum binding to greater than 0 to force an elaboration
check that issues an error for too few bindings.
To bind a TLM port or export to a vmm_channel, use vmm_connect
To bind a blocking port to a non-blocking export or vice-versa, use
vmm_connect
Gotchas
When importing a TLM connection, an error is issued if (1) there is not a
parent-child relationship, (2) the connection is already imported, or (3) the
connection is unbound.
See also
vmm_tlm_generic_payload, vmm_connect
vmm_tlm_extension
The class vmm_tlm_extension and its unparameterized base class
vmm_tlm_extension_base are used to create generic payload extensions
and are only to be used in conjunction with class vmm_tlm_generic_payload.
Each generic payload object has an array with one element for each distinct
extension type, the array index being equal to the ID field of the extension. Each
array element will be set if the corresponding extension is present, and null if the
extension is absent.
Declaration
class vmm_tlm_extension_base extends vmm_data;
static function int
max_num_extensions(bit increment = 0);

class vmm_tlm_extension
#(type DATA = vmm_tlm_extension_base)
extends vmm_tlm_extension_base;
const static int ID;
Example
class my_extension extends
vmm_tlm_extension #(my_extension);
int timestamp; // The extended attribute

`vmm_data_new(my_extension)
`vmm_data_member_begin(my_extension)
`vmm_data_member_scalar(timestamp, DO_ALL)
`vmm_data_member_end(my_extension)
endclass
...
// Set an extension in a producer
vmm_tlm_generic_payload tx;
my_extension ext = new;
...
ext.timestamp = $time;
tx.set_extension(my_extension::ID, ext);
...

// Get an extension in a consumer
my_extension ext;
$cast(ext, trans.get_extension(my_extension::ID));
if (ext)
$display("Timestamp = %0d", ext.timestamp);
vmm_tlm_extension
Tips
Each distinct user-defined extension class must instantiate class
vmm_tlm_extension with a different parameter type. Do this by using the
name of the class itself as the parameter value, as shown in the example
above
An extension class can contain as many attributes as you need
Manipulate extensions using the set_extension, get_extension and
clear_extension methods of class tlm_vmm_generic_payload.
The static member ID returns the index of the extension in the
m_extensions array of the generic payload
The static method max_num_extensions returns the length of the
m_extensions array
Gotchas
A generic payload transaction is limi ted to containing a single instance of
each type of extension. If you need multiple instances of a given extension,
you need to achieve the same effect by having one extension containing
references to multiple objects.
See also
vmm_tlm_generic_payload

The generic payload is a standard transaction type that represents the typical
attributes of a memory-mapped bus, and would be used as the DATA template
argument to the TLM port, export, and socket classes. The intent of the generic
payload is to model abstract bus transactions in an interoperable way.
Declaration
class vmm_tlm_generic_payload extends vmm_rw_access;
Members
typedef enum {
TLM_READ_COMMAND = 0,
TLM_WRITE_COMMAND = 1,
TLM_IGNORE_COMMAND = 2
} tlm_command;
Values for the
command attribute
typedef enum {
TLM_OK_RESPONSE = 1,
TLM_INCOMPLETE_RESPONSE = 0,
TLM_GENERIC_ERROR_RESPONSE = -1,
TLM_ADDRESS_ERROR_RESPONSE = -2,
TLM_COMMAND_ERROR_RESPONSE = -3,
TLM_BURST_ERROR_RESPONSE = -4,
TLM_BYTE_ENABLE_ERROR_RESPONSE = -5
} tlm_response_status;
Values for the
response status
attribute
longint m_address;
The address to which the first byte of
the data array is read or written
tlm_command m_command;
The command to be executed at the
target
byte m_data[];
The data array to be read from or
written to the target
int unsigned m_length;
The number of bytes in the data array
tlm_response_status
m_response_status;
The response status returned from the
target
bit m_dmi_allowed;
A hint returned from the target that the
target may support the Direct Memory
Interface (not used by VMM)
byte m_byte_enable[];
The byte enable array. A value of 8hff
implies the corresponding byte in the
data array is enabled
int unsigned
m_byte_enable_length;
The number of bytes in the byte
enable array
int unsigned
m_streaming_width;
The address wraps around at this
number of bytes
vmm_tlm_extension_base
m_extensions[];
An array of extensions. The element
will be null if the extension is absent
Methods
function vmm_tlm_extension_base
set_extension(
int index,
vmm_tlm_extension_base ext);
Set the element of the
extension array at the gi ven
index to the gi ven extension,
and return the old value
function vmm_tlm_extension_base
get_extension(
int index);
Return the extension at the
given index in the extension
array, or null if absent
function void
clear_extension(
int index);
Set the element in the
extension array at the gi ven
index to null
Example
begin: initiator
vmm_tlm_generic_payload tx;
...
assert( tx.randomize() with {
m_address >= 0 && m_address < 256;
m_length == 4 || m_length == 8;
m_data.size == m_length;
m_byte_enable_length <= m_length;
(m_byte_enable_length % 4) == 0;
m_byte_enable.size == m_byte_enable_length;
m_streaming_width == m_length;
} );
m_port.b_transport(tx, delay);
if ( tx.m_response_status !=
vmm_tlm_generic_payload::TLM_OK_RESPONSE )
...
end

task b_transport(int id = -1,
vmm_tlm_generic_payload trans,
ref int delay);
longint adr = trans.m_address;
vmm_tlm_generic_payload::tlm_command
cmd = trans.m_command;
int unsigned len = trans.m_length;
int unsigned bel = trans.m_byte_enable_length;
int unsigned wid = trans.m_streaming_width;

if (adr + len >= SIZE) begin
trans.m_response_status =
vmm_tlm_generic_payload::TLM_ADDRESS_ERROR_RESPONSE;
return;
end
if (wid < len) begin
vmm_tlm_generic_payload::TLM_BURST_ERROR_RESPONSE;
return;
end
`define REM(a, b) ((a)-(((a)/(b))*(b)))
if (cmd == vmm_tlm_generic_payload::TLM_READ_COMMAND)
for (int unsigned i = 0; i < len; i++)
begin
if ( bel == 0 || trans.m_byte_enable[ `REM(i, bel)] )
trans.m_data[i] = mem[adr + i];
end
else
if (cmd == vmm_tlm_generic_payload::TLM_WRITE_COMMAND)
for (int unsigned i = 0; i < len; i++)
begin
if ( bel == 0 || trans.m_byte_enable[ `REM(i, bel)] )
mem[adr + i] = trans.m_data[i];
end
vmm_tlm_generic_payload::TLM_OK_RESPONSE;
endtask : b_transport
Tips
The address, command, data, data length, and response status attributes
must always be used.
Every generic payload attribute should be initialized by the initiator. Only
the response status and DMI allowed attributes (and the data array in the
case of a read command) may be modified by the target.
A byte enable length of 0 indicates that the byte enable array is unused.
The index in the byte enable array for byte number N is calculated as the
remainder after dividing N by m_byte_enable_length.
The address to which bytes are read or written wraps around such that it
takes values in the range m_address : m_address + m_streaming_width -1.
A streaming width attribute equal to the data length indicates that streaming
mode is not used, because each data byte will have a unique address.
The response status attribute should be checked by the initiator on return.
See also
TLM Interfaces, vmm_tlm_extension

vmm_tlm_reactive_if
The vmm_tlm_reactive_if class allows a TLM transport port to be connected
to a consumer that receives incoming transaction as if through a vmm_channel.
In other words, the producer calls b_transport or nb_transport_fw, while
the consumer calls get or try_get. Similar to a channel, the
vmm_tlm_reactive_if interface places transactions into a FIFO bounded by
q_size. The tlm_bind() method is used to connect the reacti ve interface to a
TLM port, which may be either blocking or non-blocking.
Declarations
class vmm_tlm_reactive_if
#( type DATA = vmm_data, int q_size = 0 )
extends vmm_object;
Methods
function new(
vmm_object parent,
string name);
Constructor.
function int tlm_bind(
vmm_tlm_base tlm_intf,
string fname = "",
int lineno = 0);
Binds this reacti ve interface to a
TLM port
intf specifies the export type to
bind to the port:

vmm_tlm::
TLM_NONBLOCKING_EXPORT
TLM_BLOCKING_EXPORT
TLM_NONBLOCKING_FW_EXPORT

task b_transport(
int id = -1,
DATA trans,
ref int delay);
Standard blocking transport
method to be called through the
TLM port bound to this interface
nb_transport_fw(
int id = -1,
DATA trans,
ref vmm_tlm::phase_e ph,
ref int delay);
Standard non blocking transport
method to be called through the
TLM port bound to this interface
task get(output DATA tr); Gets the next transaction sent
through the socket interface.
function DATA try_get(); Checks if there is a pending
transaction and returns it;
otherwise, returns null.
vmm_tlm_reactive_if
function void completed(); Called by the consumer to indicate
that the acti ve transaction has
been completed.

Example
vmm_tlm_b_transport_port #(initiator, trans)
init_port = new( this, "init_port" );

task main();
init_port.b_transport( tx, delay );
...
endtask
endclass

// Use the reacti ve interface in the target
vmm_tlm_reactive_if #( trans, 1 )
reactive_if = new ( this, "reactive_if" );

task main();
...
reactive_if.get(tr);
...
reactive_if.completed();
endtask
endclass

initiator I = new(...);
target T = new(...);

T.reactive_if.tlm_bind (
I.init_port, vmm_tlm::TLM_BLOCKING_EXPORT
);
endfunction
endclass
vmm_tlm_reactive_if
Gotchas
A q_size of 0 causes all transactions to be refused unless a consumer is
wai ting with a call to get(). Therefore, in order not to violate the
semantics of b_transport, make sure to set the queue size greater than
0.
Calling get or try_get without havi ng first called completed on a
previously activated transaction can cause an outstanding transport call to
fail, so always call completed
See also
TLM Interfaces, vmm_channel

vmm_unit
vmm_unit class is the abstract base class of structural testbench elements such
as transactors, transaction-level models and generators.
Users should not directly extend from vmm_unit, but rather use vmm_group for
environments, and vmm_xactor for transactors and generators etc. Both of
these components extend from vmm_unit. vmm_unit provides a set of virtual
tasks and functions for each of the standard simulation phases. These do
nothing by default and should be overridden in derived classes to implement the
required behaviour in each simulation phase.
It inherits the methods required to i mplement a hierarchy of units from its
vmm_object base class.
Declaration
virtual class vmm_unit extends vmm_object;
Methods
function new(
string name,
string inst
vmm_unit parent = null);
Constructor. If parent object is
specified, adds this to the
parents list of child objects
and registers its vote member
with parent's vote.
get_typename();
Returns the string "vmm_unit"
consensus_requested(
vmm_unit who);
Indicates that the unit who has
requested consensus from this
unit.
function void consent(
string why
Sets vote to consent to end
of test with reason
forced(
string why
Forces a consensus on this
unit.
force_thru(
vmm_unit child,
bit thru = 1);
Forces a consensus from a
sub-unit of this unit.
If thru = 1, then forcing a
consensus on the sub-uni t wi ll
force a consensus on this uni t.
function void oppose(
string why
Sets vote to object to end of
test with reason
vmm_unit
virtual task request_consensus(
string why
="No reason specified");
Requests a consensus from all
components under the
vmm_units hierarchy.
function bit is_unit_enabled(); Returns 1'b1 if unit enabled
function void disable_unit(); Disable the phases of this unit
(must be called before
start_of_sim phase)
function vmm_timeline
get_timeline();
Returns the ti meline parent of
this unit
build_ph();
Override in derived classes to
define build phase
configure_ph();
define configure phase
connect_ph();
define connect phase
final_ph();
define final phase
report_ph();
define report phase
start_of_sim_ph();
define start_of_si m phase
start_of_test_ph();
define start_of_test phase
virtual task cleanup_ph(); Override in derived classes to
define cleanup phase
virtual task config_dut_ph(); Override in derived classes to
define config_dut phase
virtual task disabled_ph(); Override in derived classes to
define disabled phase (this
method is only called if unit is
disabled)
virtual task reset_ph(); Override in derived classes to
define reset phase
virtual task run_ph(); Override in derived classes to
define run phase
virtual task shutdown_ph(); Override in derived classes to
define shutdown phase
virtual task start_ph(); Override in derived classes to
define start phase
virtual task training_ph(); Override in derived classes to
define training phase
vmm_unit
virtual function vmm_phase_def
override_phase(
string name,
vmm_phase_def def);
Overrides the named phase
method wi th the specified
phase definition object.
Returns the previously used
phase definition object for this
phase (if any)
Members
this component.
vmm_voter vote; Consensus interface for this
component. The vote
members of child components
are registered with
this.vote and participate in
the consensus.
By default, consents to end of
test.
Example
program P;
ìnclude "vmm_sv"

class my_unit extends vmm_unit;
`vmm_typename(my_unit)
function new(vmm_object parent = null,
string name, string inst);
super.new(parent,name,inst);
endfunction

// override run phase task to print message after delay
virtual task run_ph();
#10 `vmm_note(log,"run_phase");
endtask

// alternati ve training phase function
function void mytraining_ph();
`vmm_note(log,"mytraining phase");
endfunction
endclass
// phase definition class
class mytraining_ph_def #(type T=my_unit)
vmm_unit
extends vmm_topdown_function_phase_def #(T);
`vmm_typename(mytraining_ph_def)
function void do_function_phase(T obj);
obj.mytraining_ph();
endfunction
endclass

// test class
function new(string name);
super.new(null,name);
endfunction
endclass

my_unit U1;
my_training_ph_def #(my_unit) train_def;
my_test t1;

initial begin
U1 = new(null,"myunit","U1");
cfg_def = new;
t1 = new(null,"test1");
U1.override_phase("training",train_def);
vmm_simulation::run_tests();
end
endprogram: P
Tips
For transactors, use the vmm_xactor class instead it is derived from
vmm_unit.
For environments or sub-environments in implicitly phased environments,
use vmm_group to model the env or subenv.
You only need to override the phase methods that you require. The others
have a default implementation that does nothing.
Gotchas
You cannot create an instance of vmm_unit you must always inherit it to
create derived classes for testbench components.
If an instance of a class derived from vmm_unit is disabled, it can only be
reenabled by resetting its ti meline to a phase up to and including
configure.
vmm_unit
vmm_unit does not support callbacks so when callbacks are needed use
vmm_xactor or vmm_group instead.
See also
vmm_object, Phases
vmm_version
The vmm_version class returns the version and vendor information of the VMM
library. The version string is composed of:

VMM Version major.minor.patch (vendor)

where
major Major version number
minor Minor version number
patch
Patch number
(vendor dependent)
vendor
Vendor name
(default is Synopsys)
Declaration
class vmm_version;
Members
function void cfdisplay(
Displays the values of the
VMM macros used to
configure the VMM library.
Displays the version and
vendor.
function int major();
Returns the major version
number.
function int minor();
Returns the minor version
number.
function int patch();
Returns the patch number
(vendor dependent).
Returns the version and
vendor string.
function string vendor(); Returns the vendor string.

vmm_version
Example
program print_version;
initial begin
vmm_version version;
version.display();
end
endprogram
Sample output:
VMM Version 1.11.4 (Synopsys)
Tips
Use cfdisplay() for a full display of your VMM configuration.
vmm_xactor
The vmm_xactor class forms the basis for all transactors, generators, bus-
functional models, drivers or monitors. It is derived from vmm_unit, which
provides implicit phasing. Transactors can be customized by extending the
main() task and by testcases by using callbacks (see vmm_xactor_callback
for details).
Declaration
class vmm_xactor extends vmm_unit;
Methods
function new(
string name,
string inst,
int stream_id = -1,
Constructor.
append_callback(
vmm_xactor_callbacks cb);
Appends the specified
callback with this instance of
the transactor.
function void do_kill_xactor(); Method to override the default
kill_xactor() method
macros.
function string do_psdisplay(
Method to override the default
psdisplay() method
macros.
function void do_reset_xactor(
vmm_xactor::reset_e rst_typ);
reset_xactor() method
macros.
function void
do_start_xactor();
start_xactor() method
macros.
function void do_stop_xactor(); Method to override the default
stop_xactor() method
macros.
function void exp_vmm_sb_ds(
vmm_data tr);
Sends output transaction to
registered scoreboards for
checking.
vmm_xactor
function void
get_input_channels(
ref vmm_channel chans[$]);
Returns the input channels of
the transactor.
get_instance();
transactor instance.
get_name();
Returns the name of this
xactor.
function void
get_output_channels(
ref vmm_channel chans[$]);
Returns the output channels of
the transactor.
function void inp_vmm_sb_ds(
vmm_data tr);
Sends input transaction to
registered scoreboards.
function void kill(); Prepares a transactor for
deletion.
virtual protected task main(); User-definable main
implementation of transactor.
Must be forked off by
start_xactor().
prepend_callback(
callback to this instance of the
transactor.
psdisplay(
Prints description of
transactor.
function void
register_vmm_sb_ds(
vmm_sb_ds_base sb,
Registers the specified
scoreboard with the
transactor.
Kind equals INPUT, EXPECT,
or EITHER.
Order equals IN_ORDER,
WITH_LOSSES, or
OUT_ORDER.
function void reset_xactor(
= SOFT_RST);
Resets the state of the
transactor and terminates
executing threads based on
the reset type.
Reset type equals SOFT_RST,
PROTOCOL_RST, FIRM_RST,
or HARD_RST (see VMM
reference manual for details).
restore_rng_state();
Restores the state of all
random number generators
associated wi th the transactor.
vmm_xactor
save_rng_state();
Saves the state of all random
number generators associated
with the transactor.
start_xactor();
Starts execution threads (calls
main()).
stop_xactor();
Stops execution threads.
Unregisters the specified
callback with this instance of
the transactor.
function void
vmm_sb_ds_base sb);
Unregisters scoreboard with
transactor.
protected task wait_if_stopped(
int unsigned n_threads = 1);
Blocks until transactor is
started.
protected task
wait_if_stopped_or_empty(
vmm_channel chan,
int unsigned n_threads = 1);
Blocks until the transactor is
started or the specified
channel is not empty.
xactor_status(
Displays status of transactor.
Members
typedef enum {
DO_PRINT,
DO_START,
DO_STOP,
DO_RESET,
DO_KILL,
DO_ALL } do_what_e;
this component.
typedef enum int {
XACTOR_IDLE,
XACTOR_BUSY,
XACTOR_STARTED,
XACTOR_STOPPED,
XACTOR_RESET,
XACTOR_STOPPING,
XACTOR_IS_STOPPED
} notifications_e;
vmm_xactor
typedef enum int {
SOFT_RST,
PROTOCOL_RST,
FIRM_RST,
HARD_RST } reset_e;
Reset enumeration types
(used by reset_xactor(),
do_all(), and
do_reset_xactor()).
int stream_id; Identifier for the stream of
transactions.
Shorthand Macros
The vmm_xactor shorthand macros are a way of defining a transactor wi th
automatically generated psdisplay(), start_xactor(), stop_xactor(),
reset_xactor() or kill() methods that have a default implementation.
The macros are placed between a
`vmm_xactor_member_begin/`vmm_xactor_member_end pair. Each
macro has a do_what_e field, which specifies the methods to automatically
generate. The enumeration values can be OR-ed together for specific methods
or DO_ALL for all methods. The default implementation for these methods can
be extended or overwritten by defining a do_psdisplay(),
do_start_xactor(), do_stop_xactor(), do_reset_xactor(), or
do_kill() method, respecti vely.
Begin / end macros
`vmm_xactor_member_begin( class )
`vmm_xactor_member_end( class )
Scalar data members
`vmm_xactor_member_scalar( name, do )
`vmm_xactor_member_scalar_array( name, do )
`vmm_xactor_member_scalar_aa_scalar( name, do )
`vmm_xactor_member_scalar_aa_string( name, do )
`vmm_xactor_member_enum( name, do )
`vmm_xactor_member_enum_array( name, do )
`vmm_xactor_member_enum_aa_scalar( name, do )
`vmm_xactor_member_enum_array( name, do )
`vmm_xactor_member_enum_aa_string( name, do )
vmm_xactor
String data members
`vmm_xactor_member_string( name, do )
`vmm_xactor_member_string_array( name, do )
`vmm_xactor_member_string_aa_scalar( name, do )
`vmm_xactor_member_string_aa_string( name, do )
VMM data members
`vmm_xactor_member_vmm_data( name, do )
`vmm_xactor_member_vmm_data_array( name, do )
`vmm_xactor_member_vmm_data_aa_scalar( name, do )
`vmm_xactor_member_vmm_data_aa_string( name, do )
`vmm_xactor_member_channel( name, do )
`vmm_xactor_member_channel_array( name, do )
`vmm_xactor_member_channel_aa_scalar( name, do )
`vmm_xactor_member_channel_aa_string( name, do )
`vmm_xactor_member_xactor( name, do )
`vmm_xactor_member_xactor_array( name, do )
`vmm_xactor_member_xactor_aa_scalar( name, do )
`vmm_xactor_member_xactor_aa_string( name, do )
`vmm_xactor_member_user_defined( name )
Example
class apb_xactor extends vmm_xactor;
`vmm_typename(apb_xactor)
apb_chan chan;
local bit go; // Go flag
function new( string name, string inst, int id = -1 );
super.new( name , inst, id );
chan = new ( ... );
endfunction
vmm_xactor
task main();
super.main(); // Required
while (go) begin : main_loop
apb_trans tr;
this.wait_if_stopped_or_empty( this.chan );
this.chan.get ( tr );
... // Main functionali ty
this.wait_if_stopped();
end
endtask

task run_ph();
fork
begin
go = 1;
this.main(); // Fork off the main loop
end
join_none
endtask

task void stop_xactor;
super.stop_xactor(); // Required
go = 0; // Stop the main loop
endtask

task shutdown_ph();
if ( /* Done */ )
this.stop_xactor();
endtask
endclass

apb_xactor apb_xtor;

// Use a factory instance to create the transactor
super.build();
apb_xtor
= apb_xactor::create_instance(this, "APB XTOR");
...
endfunction

super.start();
vmm_xactor
this.apb_xtor.start_xactor(); // Start the transactor
endtask
endclass
Tips
A callback method can be registered wi th more than one transactor.
When reset_xactor() is extended, the SOFT_RST type must be
implemented.
Use the wait_if_stopped() and wait_if_stopped_or_empty()
methods if the transactor can be stopped without violating the protocol.
See vmm_xactor_callbacks for details on using callbacks in a
vmm_xactor.
Gotchas
A warning is issued if a callback is registered more than once with the same
transactor or an attempt is made to unregister an unregistered callback.
When extending start_xactor(), main(), or stop_xactor(), it is
required to call the base class method using super.method_name() for
proper functionali ty.
None of the implicit phases are called for a vmm_xactor if the top-level is a
vmm_env.
See also
vmm_xactor_iter, vmm_xactor_callbacks
The vmm_xactor_callbacks class is used for extending the functionali ty of a
vmm_xactor from outside of the transactor. For example, a test case can
change the way a transactor generates transactions by adding error injection or
custom randomizations. The vmm_xactor_callbacks class is an empty
abstract class, which can be extended wi th methods of any name. Once the
callback is registered wi th the transactor (see vmm_xactor), the
`vmm_callback macro can be used to invoke the callback inside the
transactors main() method.
Declaration
virtual class vmm_xactor_callbacks;
Macros
`vmm_callback( facade, call )
The `vmm_callback is used within a transactors main() task. The facade
refers to the extended vmm_xactor_callbacks class, and the call refers to
the callback method to invoke inside the derived vmm_xactor_callbacks
class.
Example
typedef class my_xactor; // Forward typedef

class my callback extends vmm_xactor_callbacks;

// Task to call before the transaction is sent
virtual task pre_tr( my_xactor xactor,
my_trans tr );
`vmm_note( xactor.log,
{ "Received transaction: , tr.psdipslay()} );

endtask

// Task to call after the transaction is sent
virtual task post_tr( my_xactor xactor,
my_trans tr );
`vmm_note( xactor.log,
"Sending transaction to scoreboard" );
xactor.inp_vmm_sb_ds( tr );
endtask
endclass : my_callback


...

task main();
fork
super.main(); // Required
join_none
while (1) begin
apb_trans tr = new ( ... );

`vmm_callback ( my_callback,
pre_tr ( this, tr));
... // Main functionali ty

`vmm_callback( my_callback,
post_tr ( this, tr ));
end
endtask
endclass : my_xactor

my_xactor xtor;
my_callback cb;

// Use a factory instance to create the transactor
super.build();
xtor = my_xactor::create_instance(this, "MY_XTOR" );
cb = new ();
xtor.append_callback( cb ); // Default callback
endfunction

super.start();
this.xtor.start_xactor(); // Start the transactor
endtask
endclass : my_env

// Extend the callbacks functionality
class my_tests_callback extends my_callback;
task pre_tr( my_xactor xactor, my_trans tr );
if ( !tr.randomize() with { addr > IO_RANGE } )
`vmm_error ( this.log,
"Cannot randomize transaction!" );
endtask
endclass

program test1;

my_env env;
my_tests_callback cb;

initial begin
env = new ( "my_env" );
cb = new();

// Add new callback to modify the randomization
env.xtor.append_callback( cb );

env.run();
end

endprogram : test1
Tips
A callback method can be registered wi th more than one transactor.
Callbacks are executed in the order that they are registered.
Gotchas
A warning is issued if a callback is registered more than once with the same
transactor or an attempt is made to unregister an unregistered callback.
See also
vmm_xactor
vmm_xactor_iter
The vmm_xactor_iter class is provided to iterate over all registered
transactors in an environment, wherever they may reside. A regular expression
can be used to find a specific set of instances. This iterator can be useful for
adding callbacks to transactors, starting or stopping, assigning new transaction
templates, resetting transactors, etc. For convenience, the
`foreach_vmm_xactor macro is provided to simplify the creation and use of a
vmm_xactor_iter object.
Declaration
class vmm_xactor_iter;
Methods
function new(
string name = "",
string inst = "");
The name or inst specify the
full name of vmm_xactor to
match.
If name or inst is enclosed in
/ /, then the name is
interpreted as a regular
expression.
function vmm_xactor first(); Returns the first transactor
matching the name or inst
name specified to the new
constructor.
Returns null if no matching
transactors are found.
function vmm_xactor next(); Returns the next matching
transactor.
function vmm_xactor xactor(); Returns the current transactor
being iterated upon.
Members
string inst; Instance name of iterator.
this component.
string name; Name of iterator.
vmm_xactor_iter
Macros
`foreach_vmm_xactor ( xactor, name, inst )
The `foreach_vmm_xactor macro is shorthand for creating a
vmm_xactor_iter object and iterating through all matching transactors. The
macro creates a local instance variable of xactor called xact, which can be
used within the macro block.
Example
// Search all instances
vmm_xactor_iter iterator = new("/./", "/./");

while( iterator.xactor() != null) begin
my_xactor xtor;
// If the transactor is a my_xactor, then start it
if($cast(xtor, iterator.xactor())
xtor.start_xactor();
iterator.next();
end
// Example using the `foreach_vmm_xactor macro
begin
`foreach_vmm_xactor( my_xactor, "/./" , "/./") begin
xact.start_xactor();
end
end
Tips
Use vmm_xactor as the first argument to the `foreach_vmm_xactor
macro to find all transactors.
The first() method is implicitly called when a vmm_xactor_iter is
created so any found transactors are immediately available from the
xactor() method.
Gotchas
The order that the functions first() and next() iterate is unspecified.
See also
vmm_xactor

Index

Index
Before A
$psprintf ............................................................................. 98
$sformat ............................................................................. 98
% (percent), match pattern ................................................ 110
* (asterisk), match pattern ................................................. 110
. (period), match pattern .................................................... 110
? (query), match pattern .................................................... 110
\ (backslash)
in regular expression .................................................... 112
__vmm_done_user ........................................................... 266
`foreach_vmm_object ....................................................... 127
`foreach_vmm_object_in_namespace ................................ 127
`foreach_vmm_xactor ........................................ 127, 232, 335
`VMM_12 ........................................................................... 33
`vmm_atomic_gen ........................................................ 16, 18
`vmm_atomic_gen_using ........................................ 16, 18, 20
`vmm_callback ........................................................... 70, 331
`vmm_channel .................................................................... 30
`vmm_class_factory ............................................................ 65
`vmm_command ................................................................. 96
`vmm_cycle ........................................................................ 96
`vmm_data_byte_size ................................................. 53, 265
`vmm_data_member_* macros ............................................ 52
`vmm_data_new .................................................... 53, 55, 265
`vmm_debug ...................................................................... 96
`vmm_env_member_* macros ............................................. 60
`vmm_error ........................................................................ 96
`vmm_fatal ......................................................................... 96
`VMM_IN_PACKAGE ......................................................... 33
`VMM_LOG_ANSI_COLOR .......................................... 33, 94
`VMM_LOG_FORMAT_FILE_LINE .......................... 33, 79, 94
`VMM_NO_STR_DPI .......................................................... 33
`vmm_note ......................................................................... 96
`vmm_notify_observer ...................................................... 117
`VMM_NULL_LOG_MACROS ............................................. 33
`VMM_PARAM_CHANNEL ................................................. 33
`VMM_POST_INCLUDE ..................................................... 33
`VMM_PRE_INCLUDE ....................................................... 33
`vmm_protocol ................................................................... 96
`VMM_REGEX_DEBUG ..................................................... 33
`vmm_report ....................................................................... 96
`vmm_rtl_config_begin ...................................................... 200
`vmm_rtl_config_boolean .................................................. 200
`vmm_rtl_config_end ........................................................ 200
`vmm_rtl_config_int .......................................................... 200
`vmm_rtl_config_obj ......................................................... 200
`vmm_rtl_config_string ...................................................... 200
Index
`VMM_RW_ADDR_WIDTH ................................................. 33
`VMM_SB_DS_IN_STDLIB .......................... 33, 205, 209, 210
`vmm_scenario_gen .................................. 221, 227, 243, 246
`vmm_scenario_gen_using ....................................... 227, 246
`vmm_scenario_member_* macros .................................... 236
`vmm_scenario_new ................................................. 237, 265
`VMM_SUBENV ............................................................... 276
`vmm_subenv_member_* macros ..................................... 276
`vmm_test_begin ............................................... 282, 284, 286
`vmm_test_concatenate .................................................... 282
`vmm_test_end ................................................................ 282
`vmm_tlm_analysis_export ................................................ 303
`vmm_tlm_b_transport_export ........................................... 303
`vmm_tlm_ini tiator_socket ................................................. 303
`vmm_tlm_nb_transport_bw_export ................................... 303
`vmm_tlm_nb_transport_export ......................................... 303
`vmm_tlm_nb_transport_fw_export .................................... 303
`vmm_tlm_nb_transport_port ............................................. 303
`vmm_tlm_target_socket ................................................... 303
`vmm_trace ........................................................................ 96
`vmm_transaction ............................................................... 96
`vmm_typename ................................................................. 65
`vmm_uni t_config_* macros ................................................ 36
`vmm_user ......................................................................... 96
`vmm_verbose ................................................................... 96
`vmm_warning .................................................................... 96
`vmm_xactor_member_* macros ....................................... 327
+vmm_break_on_phase ....................................... 34, 287, 293
+vmm_break_on_timeline ........................................... 34, 293
+vmm_channel_fill_thresh ................................................... 34
+vmm_force_verbosi ty .................................................. 34, 93
+vmm_gen_rtl_config .......................................................... 34
+vmm_log_debug ............................................................... 34
+vmm_log_default ........................................................ 34, 92
+vmm_log_nofatal_at_1000 ................................................ 34
+vmm_log_nowarn_at_200 ................................................. 34
+vmm_object_children_thresh ............................................. 34
+vmm_object_root_thresh ................................................... 34
+vmm_object_thresh_check ................................................ 34
+vmm_option ................................................................... 130
+vmm_opts ................................................................ 34, 130
+vmm_opts_file .......................................................... 34, 130
+vmm_rtl_config ................................................................. 34
+vmm_test ................................................................. 35, 269
+vmm_test_file ........................................................... 35, 269
+vmm_tr_verbosity ............................................................. 35

Index
A
abort_on_error ................................................................... 87
abort_phase ..................................................................... 288
activate .............................................................................. 26
active_slot .......................................................................... 26
add_phase ....................................................................... 288
add_to_output .............................................................. 22, 24
add_watchpoint ............................................................ 72, 94
allocate
Factory .......................................................................... 65
vmm_data ...................................................................... 48
allocate_scenario ...................................................... 229, 270
allow_new_phases ................................................... 267, 269
append
vmm_sb_ds_stream_i ter ....................................... 215, 218
append_callback
vmm_group .................................................................... 70
vmm_log ........................................................................ 72
vmm_notify .................................................................. 114
vmm_sb_ds ......................................................... 205, 212
vmm_xactor ................................................................. 324
apply
vmm_scenario ...................................................... 222, 223
vmm_ss_scenario ........................................................ 270
B
b_transport ....................................................................... 295
bcast_off ...................................................................... 22, 24
bcast_on ...................................................................... 22, 24
BLAST ............................................................................. 114
block ................................................................................ 150
broadcast_mode ................................................................. 22
build .................................................................................. 57
build_config_ph
vmm_rtl_config ............................................................. 199
build_ph
vmm_unit ..................................................................... 318
byte_pack .......................................................................... 48
byte_size ................................................................... 48, 265
byte_unpack ....................................................................... 49
C
catch .................................................................................. 94
catcher ............................................................................... 72
caught ......................................................................... 85, 94
cfdisplay ................................................................... 322, 323
Index
cfg_dut ............................................................................... 57
channel .............................................................................. 39
channel_exists ................................................................. 104
check_bindings ................................................................ 297
cleanup
vmm_env ....................................................................... 57
vmm_subenv ............................................................... 274
cleanup_ph
vmm_unit ..................................................................... 318
clear_extension ................................................................ 311
Command Line Switches .................................................. 33
compare
vmm_data ...................................................................... 49
vmm_sb_ds ......................................................... 204, 205
complete ............................................................................ 26
completed ........................................................................ 315
config_dut_ph
vmm_unit ..................................................................... 318
configuration file, RTL ....................................................... 202
Configuration Macros ....................................................... 36
configure .......................................................................... 114
configure_ph
automation using macros ................................................ 36
vmm_unit ..................................................................... 318
configure_test_ph ............................................................. 288
configured ................................................................ 275, 280
connect_ph
vmm_unit ..................................................................... 318
consensus
vmm_unit ..................................................................... 318
consensus_requested ............................................... 311, 317
consent
vmm_unit ..................................................................... 317
vmm_voter ..................................................................... 45
contained ......................................................................... 224
continue_msg ..................................................................... 87
copy
Factory .......................................................................... 65
vmm_data ................................................................ 49, 55
vmm_log .................................................................. 73, 81
vmm_ms_scenario ....................................................... 100
vmm_notify .................................................................. 115
vmm_sb_ds_iter ........................................................... 216
vmm_sb_ds_stream_i ter ............................................... 218
vmm_scenario .............................................................. 234
vmm_ss_scenario ........................................................ 270
copy_data .................................................................... 49, 55
create_instance ............................................................ 66, 69
create_watchpoint ........................................................ 73, 94
Index
D
data
data_id ............................................................................... 51
default_file_fmt
vmm_rtl_config ............................................................. 200
default_round_robin .......................................................... 257
define_scenario
vmm_scenario ...................................................... 222, 234
vmm_scenario_gen ...................................................... 247
vmm_ss_scenario ........................................................ 271
define_stream .......................................................... 205, 211
delete
vmm_sb_ds_iter ........................................................... 216
delete_phase ................................................................... 288
describe
vmm_sb_ds ................................................................. 205
vmm_sb_ds_iter ........................................................... 216
disable_types ..................................................................... 73
disable_unit ...................................................................... 318
disabled_ph
vmm_unit ..................................................................... 318
display
vmm_data ...................................................................... 49
vmm_log ........................................................................ 73
vmm_notify .................................................................. 115
vmm_sb_ds ................................................................. 205
vmm_sb_ds_iter ........................................................... 216
vmm_version ............................................................... 322
display_phases
vmm_simulation ................................................... 267, 269
vmm_ti meline ............................................................... 288
distributed ........................................................................ 224
do_all ............................................................................... 275
DO_ALL ..................................................................... 51, 264
do_allocate ........................................................................ 52
do_byte_pack ..................................................................... 49
do_byte_size ...................................................................... 49
do_byte_unpack ................................................................. 50
do_compare ....................................................................... 50
DO_COMPARE .......................................................... 51, 264
do_copy ............................................................................. 50
DO_COPY ................................................................. 51, 264
DO_DEEP .................................................................. 51, 264
DO_DEEPCOMPARE ................................................. 51, 264
DO_DEEPCOPY ........................................................ 51, 264
Index
do_is_valid ................................................................... 50, 52
do_ki ll .............................................................................. 327
do_ki ll_xactor ................................................................... 324
do_max_byte_size .............................................................. 50
DO_NOCOMPARE ..................................................... 51, 264
DO_NOCOPY ............................................................ 51, 264
DO_NONE ................................................................. 51, 264
DO_PACK .................................................................. 51, 264
DO_PRINT ................................................................. 51, 263
do_psdisplay .................................................................... 264
vmm_data ................................................................ 50, 52
vmm_env ................................................................. 57, 60
vmm_subenv ....................................................... 275, 276
vmm_xactor ......................................................... 324, 327
DO_REF .................................................................... 51, 264
DO_REFCOMPARE ................................................... 51, 264
DO_REFCOPY ................................................................ 264
do_reset
vmm_env ................................................................. 57, 60
vmm_subenv ....................................................... 275, 276
do_reset_xactor ........................................................ 324, 327
do_start
vmm_env ................................................................. 57, 60
vmm_subenv ....................................................... 275, 276
do_start_xactor ........................................................ 324, 327
do_stop
vmm_env ................................................................. 58, 60
vmm_subenv ....................................................... 275, 276
do_stop_xactor ......................................................... 324, 327
DO_UNPACK ............................................................. 51, 264
do_vote
vmm_env ................................................................. 58, 60
vmm_subenv ....................................................... 275, 276
dropped ................................................................... 213, 215
E
empty_level ........................................................................ 26
enable_types ...................................................................... 73
end_msg ............................................................................ 74
ENDED .............................................................................. 51
execute
multi-stream scenario ................................................... 225
EXECUTE .......................................................................... 51
exp_stream_id
vmm_sb_ds_iter ........................................................... 216
exp_vmm_sb_ds .............................................................. 324
expect_in_order ........................................................ 204, 206
Index
expect_out_of_order ................................................. 204, 206
expect_wi th_losses ............................................ 204, 206, 210
F
Factory ............................................................................. 64
fclose
vmm_rtl_config_file_format ........................................... 203
field ................................................................................. 146
file
RTL configuration ......................................................... 202
file_fmt
vmm_rtl_config ............................................................. 200
fill_scenario ...................................................................... 229
vmm_ss_scenario ........................................................ 271
final_ph
vmm_unit ..................................................................... 318
find
first
vmm_sb_ds_iter ........................................................... 216
vmm_xactor_iter ................................................... 334, 335
flow .................................................................................... 26
flush
vmm_channel ................................................................. 26
vmm_sb_ds ................................................................. 206
fopen
for_each
vmm_channel ................................................................. 26
vmm_log ........................................................................ 74
for_each_offset .................................................................. 26
force_thru
vmm_unit ..................................................................... 317
force_verbosi ty ................................................................... 93
forced
vmm_unit ..................................................................... 317
vmm_voter ..................................................................... 45
forcing ............................................................................... 43
foreach_vmm_object (macro) ............................................ 127
foreach_vmm_object_in_namespace (macro) ..................... 127
foreach_vmm_xactor (macro) ............................. 127, 232, 335
format_msg .................................................................. 87, 94
full_level ............................................................................ 26
Index
G
gen_cfg .............................................................................. 58
get
vmm_channel ................................................................. 26
vmm_tlm_reacti ve_if ..................................................... 314
get_all_channel_names .................................................... 104
get_all_ms_scenario_gen_names ...................................... 104
get_all_ms_scenario_names ............................................. 104
get_all_scenario_names ................................................... 244
get_channel
vmm_ms_scenario ............................................... 100, 224
vmm_ms_scenario_gen ................................................ 104
get_channel_name ........................................................... 105
get_config
vmm_rtl_config ............................................................. 199
get_config_ph
vmm_rtl_config ............................................................. 199
get_consensus ................................................................. 275
get_context_gen ............................................................... 100
get_current_phase_name ................................................. 288
get_doc
vmm_test ..................................................................... 281
get_extension ................................................................... 311
get_input_channels ........................................................... 325
get_instance
vmm_log ........................................................................ 74
vmm_xactor ................................................................. 325
get_max_length ................................................................ 234
get_message_count ........................................................... 74
get_ms_scenario
vmm_ms_scenario ........................................ 100, 226, 232
get_ms_scenario_gen ....................................................... 105
get_ms_scenario_gen_name ............................................ 105
get_ms_scenario_index .................................................... 105
get_ms_scenario_name .................................................... 105
get_n_dropped
vmm_sb_ds ................................................................. 206
vmm_sb_ds_iter ........................................................... 216
get_n_inserted
vmm_sb_ds ................................................................. 206
vmm_sb_ds_iter ........................................................... 216
get_n_insts
vmm_scenario_gen ...................................................... 244
get_n_matched
vmm_sb_ds ................................................................. 206
vmm_sb_ds_iter ........................................................... 216
Index
get_n_mismatched
vmm_sb_ds ................................................................. 206
vmm_sb_ds_iter ........................................................... 217
get_n_not_found
vmm_sb_ds ................................................................. 206
vmm_sb_ds_iter ........................................................... 217
get_n_orphaned
vmm_sb_ds ......................................................... 207, 211
vmm_sb_ds_iter ........................................................... 217
get_n_peers ..................................................................... 299
get_n_pending
vmm_sb_ds ......................................................... 207, 211
vmm_sb_ds_iter ........................................................... 217
get_n_scenarios
vmm_scenario_gen ...................................................... 244
get_name
vmm_log ........................................................................ 74
vmm_test ..................................................................... 281
vmm_xactor ................................................................. 325
get_names_by_channel .................................................... 105
get_names_by_ms_scenario ............................................. 106
get_names_by_ms_scenario_gen ..................................... 106
get_names_by_scenario ................................................... 244
get_next_phase_name ...................................................... 288
get_object ......................................................... 252, 255, 256
get_output_channels ......................................................... 325
get_parent_scenario ......................................................... 234
get_peer .......................................................................... 298
get_peer_id ...................................................................... 299
get_peers ......................................................................... 299
get_phase ........................................................................ 288
get_previous_phase ......................................................... 289
get_scenario .................................................................... 244
get_scenario_index ........................................................... 245
get_scenario_name .......................................................... 245
get_sim ............................................................................ 267
get_ti meline
vmm_unit ..................................................................... 318
get_top_timeline ............................................................... 267
get_typename
Factory .......................................................................... 65
vmm_unit ............................................................. 311, 317
get_verbosi ty ...................................................................... 74
grab
vmm_channel ......................................................... 27, 231
grab_channels .................................................................. 101
grabber
vmm_channel ............................................................... 231
Index
H
has_config_done .............................................................. 281
Hierarchy
iteration over ................................................................ 127
name ........................................................................... 110
separator ..................................................................... 110
HOW_TO_COMPARE ...................................................... 264
HOW_TO_COPY .............................................................. 264
hw_reset ............................................................................ 58
I
ID .................................................................................... 308
incr_n_dropped
vmm_sb_ds_iter ........................................................... 217
incr_n_inserted
vmm_sb_ds_iter ........................................................... 217
incr_n_matched
vmm_sb_ds_iter ........................................................... 217
incr_n_mismatched
vmm_sb_ds_iter ........................................................... 217
incr_n_not_found
vmm_sb_ds_iter ........................................................... 217
incr_n_orphaned
vmm_sb_ds_iter ........................................................... 217
incr_n_pending
vmm_sb_ds_iter ........................................................... 217
indicate ............................................................................ 115
indicated
vmm_notify_callbacks ........................................... 117, 211
vmm_notify_observer ................................................... 118
inject
vmm_atomic_gen ........................................................... 17
vmm_scenario_gen ...................................................... 245
inject_obj ......................................................................... 245
inp_stream_id
vmm_sb_ds_iter ........................................................... 217
inp_vmm_sb_ds ............................................................... 325
insert
vmm_sb_ds .................................................. 207, 211, 215
insert_phase ............................................................ 289, 293
inst_count
vmm_scenario_gen ...................................................... 246
intf_e
vmm_tlm ...................................................................... 295
IP-XACT
TM
....................................................................... 195
is_above ............................................................................ 74
Index
is_configured .................................................................... 115
is_forced ............................................................................ 43
is_full ................................................................................. 27
is_grabbed ......................................................................... 27
is_locked ............................................................................ 27
is_not_above ...................................................................... 74
is_ok
vmm_sb_ds_iter ........................................................... 217
is_on ........................................................................ 115, 121
is_reached ......................................................................... 43
is_unit_enabled ................................................................ 318
is_valid .............................................................................. 50
is_waited_for .................................................................... 115
issue ............................................................................ 85, 94
items ........................................................................ 229, 271
iterator ............................................................................. 127
J
jump_to_phase ......................................................... 289, 293
K
kill
vmm_channel ................................................................. 27
vmm_log ........................................................................ 74
vmm_xactor ................................................................. 325
L
last
vmm_sb_ds_iter ........................................................... 217
last_selected .................................................................... 240
length
of scenario ........................................................... 222, 228
vmm_sb_ds_iter ........................................................... 217
vmm_scenario .............................................................. 235
level ................................................................................... 27
list
vmm_log ........................................................................ 74
vmm_simulation ........................................................... 267
vmm_test_registry ........................................................ 285
load ................................................................................... 50
lock .................................................................................... 27
log_default ......................................................................... 92
log_start ....................................................................... 75, 81
Index
M
main
vmm_xactor ......................................................... 325, 330
major ............................................................................... 322
map_to_name
vmm_rtl_config ............................................................. 199
match ............................................................... 204, 207, 210
match string ..................................................................... 110
matched ................................................................... 213, 215
max_byte_size
vmm_data ......................................................... 50, 55, 265
max_num_extensions ....................................................... 308
memory ........................................................................... 149
Messaging ........................................................................ 91
Callbacks ....................................................................... 95
Catching ........................................................................ 94
Creating messages ......................................................... 95
Flow .............................................................................. 96
Formatting ..................................................................... 94
Handling ........................................................................ 93
Issuing ........................................................................... 92
Macros .......................................................................... 95
Types & Severities ......................................................... 91
Watchpoints ................................................................... 94
minor ............................................................................... 322
mismatched ............................................................. 213, 215
modify ................................................................................ 75
ms_scenario_exists .......................................................... 106
ms_scenario_gen_exi sts ................................................... 106
Multi-Stream Scenarios ..................................................... 224
N
n_scenarios ..................................................................... 240
Name Matching ............................................................... 110
name pattern .................................................................... 110
nays .................................................................................. 43
nb_transport_bw ............................................................... 295
nb_transport_fw ................................................................ 295
new
Factory .......................................................................... 65
new_output ........................................................................ 22
new_source ..................................................................... 252
new_stream_iter
vmm_sb_ds_iter ........................................................... 217
next
vmm_sb_ds_iter ........................................................... 217
vmm_xactor_iter ................................................... 334, 335
Index
next_in_set ...................................................................... 240
not_found ................................................................. 213, 215
notify .................................................................................. 39
O
ON_OFF .......................................................................... 114
ONE_SHOT ..................................................................... 114
oppose
vmm_unit ..................................................................... 317
vmm_voter ..................................................................... 46
orphaned ......................................................................... 213
out_chan
vmm_scenario .............................................................. 222
vmm_scenario_gen .............................................. 243, 246
override_phase
vmm_unit ...................................................... 287, 293, 319
override_with_copy ....................................................... 66, 69
override_with_new ........................................................ 66, 69
P
parent_scenario ................................................................ 235
pass_or_fail ....................................................................... 88
patch ............................................................................... 322
peek .................................................................................. 27
phase_e
vmm_tlm ...................................................................... 294
Phases ............................................................................ 138
playback ............................................................................ 27
pos
vmm_sb_ds_iter ........................................................... 218
post_insert ....................................................................... 213
post_inst_gen ..................................................................... 17
post_scenario_gen ................................................... 229, 243
postflush .......................................................................... 219
Post-test ti meline .............................................................. 138
power_on_reset .................................................................. 58
power_up ........................................................................... 58
pre_abort ..................................................................... 82, 95
pre_debug .................................................................... 82, 95
pre_finish ..................................................................... 83, 95
pre_insert ......................................................................... 214
pre_randomize ................................................................. 271
pre_scenario_randomize ........................................... 229, 243
pre_stop ...................................................................... 83, 95
preflush ............................................................................ 219
prepend
Index
vmm_sb_ds_stream_i ter ....................................... 215, 219
prepend_callback
vmm_group .................................................................... 70
vmm_log ........................................................................ 75
vmm_sb_ds ......................................................... 207, 212
vmm_xactor ................................................................. 325
Pre-test timeline ............................................................... 138
prev
vmm_sb_ds_iter ........................................................... 218
print_bindings ................................................................... 297
psdisplay
vmm_broadcast .............................................................. 22
vmm_channel ................................................................. 27
vmm_consensus ............................................................ 43
vmm_data ...................................................................... 50
vmm_env ....................................................................... 58
vmm_log ........................................................................ 75
vmm_ms_scenario ............................................... 101, 271
vmm_notify .................................................................. 115
vmm_scenario .............................................................. 234
vmm_scenario_gen ...................................................... 245
vmm_scheduler ............................................................ 253
vmm_subenv ............................................................... 275
vmm_version ............................................................... 322
vmm_xactor ................................................................. 325
put ..................................................................................... 28
Q
q_size ...................................................................... 314, 316
quick_compare ................................................................. 207
R
RAL (Register Abstraction Layer) ....................................... 146
randomized_obj .................................................................. 18
read_bit
read_int
read_string
reconfigure ................................................................... 28, 32
record ................................................................................ 28
redefine_scenario
vmm_ms_scenario ....................................................... 101
vmm_scenario .............................................................. 235
Index
vmm_ss_scenario ........................................................ 271
REFCOPY ......................................................................... 51
regfile .............................................................................. 148
register ............................................................................ 147
Register Abstraction Layer ............................................. 146
register_channel
vmm_consensus ............................................................ 43
vmm_ms_scenario_gen ........................................ 106, 224
register_consensus ............................................................. 43
register_ms_scenario ................................................ 106, 228
register_ms_scenario_gen ........................................ 106, 226
register_no_notification ....................................................... 44
register_notification ............................................................. 44
register_scenario ............................................... 228, 244, 245
register_vmm_sb_ds
vmm_channel ................................................................. 28
vmm_notify .................................................................. 115
vmm_xactor ................................................................. 325
register_voter ..................................................................... 44
register_xactor ................................................................... 44
remove
vmm_channel ........................................................... 28, 32
vmm_sb_ds ................................................................. 207
remove_watchpoint
vmm_log .................................................................. 75, 94
rename_phase ................................................................. 289
repeat_thresh
vmm_scenario ...................................................... 228, 235
vmm_ss_scenario ........................................................ 271
repeated
vmm_ms_scenario ....................................................... 102
vmm_scenario ...................................................... 228, 235
vmm_ss_scenario ................................................ 271, 273
repetition .......................................................................... 228
repetition constraint .......................................................... 235
replace_channel ............................................................... 106
replace_ms_scenario ........................................................ 106
replace_ms_scenario_gen ................................................ 106
replace_scenario ............................................... 244, 245, 248
report
vmm_env ....................................................................... 58
vmm_log ........................................................................ 76
vmm_sb_ds ......................................................... 207, 211
vmm_subenv ............................................................... 275
report_ph
vmm_unit ..................................................................... 318
report_unbound ................................................................ 298
reset
vmm_channel ................................................................. 28
Index
vmm_log ........................................................................ 76
vmm_notify .................................................................. 116
vmm_subenv ............................................................... 275
reset_dut ............................................................................ 58
reset_env ........................................................................... 58
reset_ph
vmm_unit ..................................................................... 318
reset_to_phase ........................................................ 289, 293
reset_xactor
vmm_atomic_gen ........................................................... 17
vmm_broadcast .............................................................. 22
vmm_scenario_gen ...................................................... 245
vmm_scheduler ............................................................ 253
vmm_xactor ......................................................... 325, 330
restart .......................................................................... 58, 63
restart_test ......................................................................... 58
restore_rng_state ............................................................. 325
round_robin ....................................................... 228, 242, 243
round_robin constraint ...................................................... 241
RTL configuration ............................................ 195, 199, 202
run
vmm_env ....................................................................... 58
vmm_test ..................................................................... 281
vmm_test_registry ......................................... 282, 284, 285
run_ph
vmm_unit ..................................................................... 318
run_phase
vmm_test ..................................................................... 284
vmm_ti meline ....................................................... 289, 293
run_tests
vmm_simulation ............................. 138, 267, 282, 284, 286
S
save .................................................................................. 50
save_config_ph
vmm_rtl_config ............................................................. 199
save_rng_state ................................................................. 326
scenario_count
vmm_scenario_gen ...................................................... 246
scenario_exists ........................................................ 244, 245
scenario_id
vmm_data ...................................................................... 51
vmm_ms_scenario ....................................................... 101
vmm_scenario .............................................................. 235
vmm_scenario_election ................................................ 241
vmm_ss_scenario ........................................................ 272
Index
scenario_kind
vmm_scenario ...................................................... 222, 235
vmm_ss_scenario ........................................................ 272
scenario_name
vmm_ms_scenario ....................................................... 101
vmm_scenario .............................................................. 235
vmm_ss_scenario ........................................................ 271
scenario_set
vmm_*_scenario_election ..................................... 240, 241
vmm_scenario_gen .............................................. 228, 246
vmm_scenario_gen ...................................................... 232
Scenarios ........................................................................ 221
sched_from_input ............................................................. 253
schedule .................................................................. 253, 255
select ....................................................................... 240, 241
select_scenario
vmm_*_scenario_election ............................................. 240
vmm_scenario_gen .............................................. 228, 246
set_config
vmm_test .................................................. 66, 69, 281, 284
set_extension ................................................................... 311
set_format .......................................................................... 76
set_instance ....................................................................... 76
set_log ............................................................................... 50
set_name ........................................................................... 76
set_parent_scenario ......................................................... 231
set_sev_image ............................................................. 76, 81
set_typ_i mage .............................................................. 76, 81
set_verbosity ...................................................................... 76
Shorthand Macros .......................................................... 260
shutdown_ph
vmm_unit ..................................................................... 318
Simulation steps ................................................................. 56
Single-Stream Scenarios ................................................... 221
sink .................................................................................... 28
size .................................................................................... 28
sneak ........................................................................... 24, 28
start
vmm_channel ................................................................. 28
vmm_env ....................................................................... 58
vmm_subenv ............................................................... 275
start_msg ........................................................................... 77
start_of_si m_ph
vmm_unit ..................................................................... 318
start_of_test_ph
vmm_unit ..................................................................... 318
start_ph
Index
vmm_unit ..................................................................... 318
start_xactor
vmm_broadcast .............................................................. 23
vmm_channel ................................................................. 24
vmm_scheduler ............................................................ 253
vmm_xactor ......................................................... 326, 330
STARTED .......................................................................... 51
status
vmm_channel ................................................................. 29
vmm_notify ................................................... 116, 120, 121
step_function_phase ......................................................... 290
stop
vmm_env ....................................................................... 58
vmm_log ........................................................................ 75
vmm_subenv ............................................................... 276
stop_after_n_errors ............................................................ 77
stop_after_n_insts
vmm_atomic_gen ..................................................... 18, 20
vmm_scenario_gen ....................................... 229, 246, 248
stop_after_n_scenarios
vmm _scenario_gen ..................................................... 229
vmm_ms_scenario_gen ................................. 108, 109, 248
vmm_scenario_gen ...................................................... 246
stop_xactor
vmm_broadcast ........................................................ 23, 24
vmm_scheduler ............................................................ 253
vmm_xactor ......................................................... 326, 330
stream_id
vmm_*_scenario_election ............................................. 241
vmm_data ...................................................................... 51
vmm_ms_scenario ....................................................... 101
vmm_sb_ds ................................................................. 208
vmm_scenario .............................................................. 235
vmm_ss_scenario ........................................................ 272
sync_e
vmm_notify .................................................................. 114
vmm_tlm ...................................................................... 294
system ............................................................................. 152
T
T_scenario_valid constraint ............................................... 272
task_phase_ti meout .................................................. 290, 293
tee ............................................................................... 24, 29
tee_mode ........................................................................... 29
terminated ................................................................ 116, 120
text .................................................................................... 77
throw ........................................................................... 85, 94
Index
Ti meline ........................................................................... 138
timestamp ................................................................ 116, 121
TLM Interfaces ................................................................ 294
TLM_ACCEPTED ............................................................. 294
tlm_bind .............................................................. 39, 298, 314
tlm_command ................................................................... 310
TLM_COMPLETED .......................................................... 294
tlm_i mport ........................................................................ 298
TLM_REFUSED ............................................................... 294
tlm_response_status ......................................................... 310
tlm_transport_interconnect .................................................. 39
tlm_unbind ....................................................................... 298
TLM_UPDATED ............................................................... 294
Top-test ti meline ............................................................... 138
training_ph
vmm_unit ..................................................................... 318
transform ................................................................. 205, 208
try_get ............................................................................. 314
try_grab ............................................................................. 29
try_peek ............................................................................. 29
U
uncatch .............................................................................. 77
uncatch_all ......................................................................... 77
ungrab
vmm_channel ......................................................... 29, 231
unlock ................................................................................ 29
unmodify ............................................................................ 77
unregister_callback
vmm_group .................................................................... 70
vmm_log ........................................................................ 77
vmm_notify .................................................................. 116
vmm_sb_ds ................................................................. 208
vmm_ti meline ............................................................... 290
vmm_xactor ................................................................. 326
unregister_channel ........................................................... 107
unregister_channel_by_name ............................................ 107
unregister_ms_scenario .................................................... 107
unregister_ms_scenario_by_name .................................... 107
unregister_ms_scenario_gen ............................................ 107
unregister_ms_scenario_gen_by_name ............................. 107
unregister_scenario .......................................................... 245
unregister_scenario_by_name ........................................... 245
unregister_vmm_sb_ds ..................................................... 326
vmm_notify .................................................................. 116
use_hier_inst_name ........................................................... 77
use_orig_inst_name ........................................................... 77
uses_hier_inst_name .......................................................... 77
Index
using
scenario ....................................................................... 228
vmm_ss_scenario ........................................................ 272
V
vendor ............................................................................. 322
Verbosity Level ................................................................... 92
virtual register ................................................................... 150
vmm_*_phase_def .......................................................... 143
vmm_*_scenario_election ....................................... 240, 243
vmm_*_scenario_gen_callbacks .................................... 249
VMM_12 (macro) ................................................................ 33
vmm_atomic_gen ............................................................. 16
vmm_atomic_gen (macro) ............................................. 16, 18
vmm_atomic_gen_callbacks ................................................ 16
vmm_atomic_gen_using (macro) ............................. 16, 18, 20
vmm_atomic_scenario ...................................................... 273
vmm_bottomup_function_phase_def .................................. 143
vmm_break_on_phase (plusarg) .......................... 34, 287, 293
vmm_break_on_timeline (plusarg) ............................... 34, 293
vmm_broadcast ................................................................ 21
vmm_callback (macro) ................................................ 70, 331
vmm_channel ................................................................... 25
vmm_channel (macro) ........................................................ 30
vmm_channel_fill_thresh (plusarg) ....................................... 34
vmm_class_factory (macro) ................................................. 65
vmm_command (macro) ..................................................... 96
vmm_connect ................................................................... 39
vmm_consensus .............................................................. 42
vmm_cycle (macro) ............................................................ 96
vmm_data ......................................................................... 48
vmm_data_byte_size (macro) ...................................... 53, 265
vmm_data_member_* macros ............................................. 52
vmm_data_new (macro) ......................................... 53, 55, 265
vmm_debug (macro) ........................................................... 96
vmm_done_user ................................. See __vmm_done_user
vmm_env .............................................................. 56, 70, 71
vmm_env_member_* macros .............................................. 60
vmm_error (macro) ............................................................. 96
vmm_fatal (macro) .............................................................. 96
vmm_force_verbosity (plusarg) ...................................... 34, 93
vmm_forked_task_phase_def ............................................ 143
vmm_gen_rtl_config (plusarg) ............................................. 34
vmm_group .............................................................. 70, 274
vmm_group_callbacks ........................................................ 70
VMM_IN_PACKAGE (macro) .............................................. 33
vmm_log ........................................................................... 72
VMM_LOG_ANSI_COLOR (macro) ............................... 33, 94
Index
vmm_log_callbacks .................................................... 82, 95
vmm_log_catcher ................................................. 85, 89, 94
vmm_log_debug (plusarg) ................................................... 34
vmm_log_default (plusarg) ............................................ 34, 92
vmm_log_format ......................................................... 87, 94
VMM_LOG_FORMAT_FILE_LINE (macro) .............. 33, 79, 94
vmm_log_msg .................................................................. 89
vmm_log_nofatal_at_1000 (plusarg) .................................... 34
vmm_log_nowarn_at_200 (plusarg) ..................................... 34
vmm_log_watchpoint .................................................... 86, 94
vmm_mam ....................................................................... 155
vmm_mam_allocator ......................................................... 156
vmm_mam_cfg ................................................................. 156
vmm_mam_region ............................................................ 156
vmm_ms_scenario ......................................................... 100
vmm_ms_scenario_election ...................................... 228, 240
vmm_ms_scenario_gen .................................................. 104
vmm_ms_scenario_gen_callbacks ..................................... 249
VMM_NO_STR_DPI (macro) .............................................. 33
vmm_note (macro) ............................................................. 96
vmm_notify ..................................................................... 113
vmm_notify_callbacks ............................................... 113, 117
vmm_notify_observer ................................................ 117, 120
vmm_notify_observer (macro) ........................................... 117
VMM_NULL_LOG_MACROS (macro) .................................. 33
vmm_object .................................................................... 122
vmm_object_children_thresh (plusarg) ................................. 34
vmm_object_iter ............................................................. 127
vmm_object_root_thresh (plusarg) ....................................... 34
vmm_object_thresh_check (plusarg) .................................... 34
vmm_option (plusarg) ....................................................... 130
vmm_opts ....................................................................... 130
vmm_opts (plusarg) .................................................... 34, 130
vmm_opts_file (plusarg) .............................................. 34, 130
VMM_PARAM_CHANNEL (macro) ...................................... 33
vmm_phase .................................................................... 141
VMM_POST_INCLUDE (macro) .......................................... 33
VMM_PRE_INCLUDE (macro) ............................................ 33
vmm_protocol (macro) ........................................................ 96
vmm_ral ........................................................................... 158
vmm_ral_access .............................................................. 159
vmm_ral_block ................................................................. 161
vmm_ral_block_or_sys ..................................................... 163
vmm_ral_env ................................................................... 166
vmm_ral_field ................................................................... 167
vmm_ral_field_callbacks ................................................... 170
vmm_ral_mem ................................................................. 170
vmm_ral_mem_backdoor .................................................. 174
vmm_ral_mem_burst ........................................................ 175
Index
vmm_ral_mem_callbacks .................................................. 175
vmm_ral_mem_frontdoor .................................................. 176
vmm_ral_reg .................................................................... 177
vmm_ral_reg_backdoor .................................................... 181
vmm_ral_reg_callbacks .................................................... 181
vmm_ral_reg_frontdoor ..................................................... 181
vmm_ral_sys .................................................................... 182
vmm_ral_tests .................................................................. 184
vmm_ral_version .............................................................. 185
vmm_ral_vfield ................................................................. 185
vmm_ral_vfield_callbacks ................................................. 187
vmm_ral_vreg .................................................................. 188
vmm_ral_vreg_callbacks ................................................... 191
VMM_REGEX_DEBUG (macro) .......................................... 33
vmm_report (macro) ........................................................... 96
vmm_rtl_config ....................................................... 195, 199
vmm_rtl_config (plusarg) ..................................................... 34
vmm_rtl_config_begin (macro) .......................................... 200
vmm_rtl_config_boolean (macro) ....................................... 200
vmm_rtl_config_end (macro) ............................................. 200
vmm_rtl_config_file_format .................................... 195, 202
vmm_rtl_config_int (macro) ............................................... 200
vmm_rtl_config_obj (macro) .............................................. 200
vmm_rtl_config_string (macro) .......................................... 200
vmm_rw ........................................................................... 191
vmm_rw_access ............................................................... 192
VMM_RW_ADDR_WIDTH (macro) ...................................... 33
vmm_rw_burst .................................................................. 192
vmm_rw_xactor ................................................................ 193
vmm_rw_xactor_callbacks ................................................ 193
vmm_sb_ds .................................................................... 204
vmm_sb_ds_*iter ............................................................ 216
vmm_sb_ds_callbacks ........................................... 205, 212
VMM_SB_DS_IN_STDLIB (macro) ............... 33, 205, 209, 210
vmm_sb_ds_iter ................................................ 204, 207, 216
vmm_sb_ds_stream_i ter .................................... 204, 207, 216
vmm_scenario ................................................................ 234
vmm_scenario_election ............................................ 228, 240
vmm_scenario_election_valid constraint ............................ 241
vmm_scenario_gen ........................................................ 243
vmm_scenario_gen (macro) ....................... 221, 227, 243, 246
vmm_scenario_gen_callbacks ............................ 229, 243, 249
vmm_scenario_gen_using (macro) ............................ 227, 246
vmm_scenario_member_* macros ..................................... 236
vmm_scenario_new (macro) ..................................... 237, 265
vmm_scheduler ...................................................... 252, 257
vmm_scheduler_election ................................. 252, 255, 257
vmm_scheduler_election_valid .......................................... 257
vmm_simulation ..................................................... 267, 287
Index
vmm_ss_scenario ................................................... 221, 270
vmm_subenv ....................................................... 70, 71, 274
VMM_SUBENV (macro) .................................................... 276
vmm_subenv_member_* macros ....................................... 276
vmm_test ........................................................................ 281
vmm_test (plusarg) ..................................................... 35, 269
vmm_test_begin (macro) .................................... 282, 284, 286
vmm_test_concatenate (macro) ......................................... 282
vmm_test_end (macro) ............................................. 282, 286
vmm_test_file (plusarg) ............................................... 35, 269
vmm_test_registry .......................................................... 285
vmm_timeline ................................................................. 287
vmm_ti meline_callbacks ........................................... 287, 290
vmm_tlm .......................................................................... 294
vmm_tlm_analysis_export ................................................. 296
vmm_tlm_analysis_export (macro) ..................................... 303
vmm_tlm_analysis_port .................................................... 296
vmm_tlm_b_transport_export ............................................ 296
vmm_tlm_b_transport_export (macro) ................................ 303
vmm_tlm_b_transport_port ................................................ 296
vmm_tlm_extension ....................................................... 308
vmm_tlm_extension_base ................................................. 308
vmm_tlm_generic_payload ..................................... 294, 310
vmm_tlm_initiator_socket .................................................. 297
vmm_tlm_initiator_socket (macro) ..................................... 303
vmm_tlm_nb_transport_bw_export .................................... 296
vmm_tlm_nb_transport_bw_export (macro) ........................ 303
vmm_tlm_nb_transport_bw_port ........................................ 296
vmm_tlm_nb_transport_export .......................................... 297
vmm_tlm_nb_transport_export (macro) .............................. 303
vmm_tlm_nb_transport_fw_export ..................................... 296
vmm_tlm_nb_transport_fw_export (macro) ......................... 303
vmm_tlm_nb_transport_fw_port ......................................... 296
vmm_tlm_nb_transport_port .............................................. 297
vmm_tlm_nb_transport_port (macro) ................................. 303
vmm_tlm_reactive_if ...................................................... 314
vmm_tlm_target_socket .................................................... 297
vmm_tlm_target_socket (macro) ........................................ 303
vmm_topdown_function_phase_def ................................... 143
vmm_tr_verbosity (plusarg) ................................................. 35
vmm_trace (macro) ............................................................. 96
vmm_transaction (macro) .................................................... 96
vmm_typename (macro) ..................................................... 65
vmm_unit .................................................................. 70, 317
vmm_unit_config_* macros ................................................. 36
vmm_user (macro) ............................................................. 96
vmm_verbose (macro) ........................................................ 96
vmm_version .................................................................. 322
vmm_voter ................................................................... 42, 45
Index
vmm_warning (macro) ........................................................ 96
vmm_xactor .................................................................... 324
vmm_xactor_callbacks ........................................... 330, 331
vmm_xactor_iter ..................................................... 127, 334
vmm_xactor_member_* macros ........................................ 327
W
wai t_for .................................................................... 116, 121
wai t_for_end ...................................................................... 59
wai t_for_msg ................................................................ 78, 94
wai t_for_off .............................................................. 116, 121
wai t_for_watchpoint ...................................................... 78, 94
wai t_if_stopped ........................................................ 326, 330
wai t_if_stopped_or_empty ......................................... 326, 330
write ........................................................................ 296, 299
write_bit
write_int
write_string
X
xactor ...................................................................... 334, 335
xactor_status .................................................................... 326

Free VMM Resources
To assist users in understanding and applying VMM
Doulos has created other free resources in the form of
videos, tutorials and examples. These can be found at
www.doulos.com/vmm
Full scope independent training in SystemVerilog and
VMM is provided by Doulos worldwide and training
programs can be customized and delivered to team and
business requirements. For full details see
www.doulos.com
The Golden Reference Guide Series
This Golden Reference Guide is one in a series covering
languages and methodologies available from Doulos.
Check out the full Golden Reference Guide series at
www.doulos.com
About Doulos
Doulos is the global leader for the development and
delivery of world class training solutions for SoC and
FPGA design and verification. Established in 1990 and
fully independent, Doulos sets the industry standard for
high quality training and specializes in delivering know-
how in leading edge technologies, languages and design
methods.
Doulos know-how is delivered worldwide through regularly
scheduled classes in major locations in the U.S. and
Europe, and through in-house training at customer
locations. To find out more about the Doulos training
portfolio please visit www.doulos.com

VMM Golden Reference Guide Jan 2010

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

VMM Golden Reference Guide Jan 2010

Uploaded by

Copyright:

Available Formats

A concise guide to VMM Verification Methodology Version 1.

is a registered trademark of Doulos Ltd.

Where TYPE is:

You might also like