UVM 1.2 Class Reference manual

UVM 1.2 Class Reference manual
Universal Verification Methodology
(UVM) 1.2 Class Reference
June 2014
Copyright© 2011 - 2014 Accellera Systems Initiative (Accellera). All rights reserved.
Accellera Systems Initiative Inc., 1370 Trancas Street #163, Napa, CA 94558, USA.
Notices
Accellera Systems Initiative (Accellera) Standards documents are developed within Accellera and the Technical
Committees of Accellera. Accellera develops its standards through a consensus development process, approved by its
members and board of directors, which brings together volunteers representing varied viewpoints and interests to
achieve the final product. Volunteers are not necessarily members of Accellera and serve without compensation.
While Accellera administers the process and establishes rules to promote fairness in the consensus development process, Accellera does not independently evaluate, test, or verify the accuracy of any of the information contained in its
standards.
Use of an Accellera Standard is wholly voluntary. Accellera disclaims liability for any personal injury, property or
other damage, of any nature whatsoever, whether special, indirect, consequential, or compensatory, directly or indirectly resulting from the publication, use of, or reliance upon this, or any other Accellera Standard document.
Accellera does not warrant or represent the accuracy or content of the material contained herein, and expressly disclaims any express or implied warranty, including any implied warranty of merchantability or suitability for a specific
purpose, or that the use of the material contained herein is free from patent infringement. Accellera Standards documents are supplied “AS IS.”
The existence of an Accellera Standard does not imply that there are no other ways to produce, test, measure, purchase, market, or provide other goods and services related to the scope of an Accellera Standard. Furthermore, the
viewpoint expressed at the time a standard is approved and issued is subject to change due to developments in the
state of the art and comments received from users of the standard. Every Accellera Standard is subjected to review
periodically for revision and update. Users are cautioned to check to determine that they have the latest edition of any
Accellera Standard.
In publishing and making this document available, Accellera is not suggesting or rendering professional or other services for, or on behalf of, any person or entity. Nor is Accellera undertaking to perform any duty owed by any other
person or entity to another. Any person utilizing this, and any other Accellera Standards document, should rely upon
the advice of a competent professional in determining the exercise of reasonable care in any given circumstances.
Interpretations: Occasionally questions may arise regarding the meaning of portions of standards as they relate to specific applications. When the need for interpretations is brought to the attention of Accellera, Accellera will initiate
action to prepare appropriate responses. Since Accellera Standards represent a consensus of concerned interests, it is
important to ensure that any interpretation has also received the concurrence of a balance of interests. For this reason,
Accellera and the members of its Technical Committees are not able to provide an instant response to interpretation
requests except in those cases where the matter has previously received formal consideration.
Comments for revision of Accellera Standards are welcome from any interested party, regardless of membership
affiliation with Accellera. Suggestions for changes in documents should be in the form of a proposed change of text,
together with appropriate supporting comments. Comments on standards and requests for interpretations should be
addressed to:
Accellera Systems Initiative Inc.
1370 Trancas Street #163
Napa, CA 94558
USA
Note: Attention is called to the possibility that implementation of this standard may require use of subject matter covered by patent rights. By publication of this standard, no position is taken with respect to the existence
or validity of any patent rights in connection therewith. Accellera shall not be responsible for identifying pat-
UVM 1.2 Class Reference
Front-2
ents for which a license may be required by an Accellera standard or for conducting inquiries into the legal
validity or scope of those patents that are brought to its attention.
Accellera is the sole entity that may authorize the use of Accellera-owned certification marks and/or trademarks to
indicate compliance with the materials set forth herein.
Authorization to photocopy portions of any individual standard for internal or personal use must be granted by Accellera, provided that permission is obtained from and any required fee is paid to Accellera. To arrange for authorization
please contact Lynn Bannister, Accellera, 1370 Trancas Street #163, Napa, CA 94558, phone (707) 251-9977, e-mail
lynn@accellera.org. Permission to photocopy portions of any individual standard for educational classroom use can
also be obtained from Accellera.
Suggestions for improvements to the UVM 1.2 Class Reference are welcome. They should be sent to the UVM email
reflector
uvm-wg@lists.accellera.org
UVM 1.2 Class Reference
Front-3
Contents
1.
Overview .............................................................................................................................................................1
1.1
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2.
Normative References.........................................................................................................................................2
3.
Definitions, Acronyms, and Abbreviations.........................................................................................................2
3.1
Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.2
Acronyms and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4.
Classes and Utilities ............................................................................................................................................5
5.
Core Base Classes ...............................................................................................................................................8
6.
7.
8.
9.
5.1
Miscellaneous Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.2
uvm_object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.3
uvm_transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.4
uvm_root. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.5
Port Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Reporting Classes..............................................................................................................................................46
6.1
uvm_report_message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.2
uvm_report_object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.3
uvm_report_handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.4
uvm_report_server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.5
uvm_report_catcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Recording Classes .............................................................................................................................................89
7.1
uvm_tr_database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.2
uvm_tr_stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Factory Classes ...............................................................................................................................................103
8.1
uvm_*_registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8.2
uvm_factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Phasing Classes ...............................................................................................................................................125
9.1
uvm_phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
9.2
uvm_domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
UVM 1.2 Class Reference
Front-4
10.
11.
12.
9.3
uvm_bottomup_phase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
9.4
uvm_task_phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
9.5
uvm_topdown_phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
9.6
UVM Common Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
9.7
UVM Run-Time Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
9.8
User-Defined Phases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Configuration and Resource Classes...............................................................................................................173
10.1
uvm_resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
10.2
uvm_resource_db . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
10.3
uvm_config_db . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Synchronization Classes .................................................................................................................................202
11.1
uvm_event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
11.2
uvm_event_callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
11.3
uvm_barrier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
11.4
uvm_objection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
11.5
uvm_heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
11.6
uvm_callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Container Classes ............................................................................................................................................232
12.1
uvm_pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
12.2
uvm_queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
13.
TLM Interfaces ...............................................................................................................................................241
14.
TLM1 ..............................................................................................................................................................242
14.1
Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
14.2
Exports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
14.3
Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
14.4
Imps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
14.5
FIFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
14.6
FIFO Base. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
14.7
Channel Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
14.8
Sequence Item Pull Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
14.9
Sequencer Base. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
UVM 1.2 Class Reference
Front-5
15.
TLM2 ..............................................................................................................................................................281
15.1
Interface Masks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
15.2
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
15.3
Generic Payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
15.4
Socket Base. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
15.5
Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
15.6
Exports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
15.7
Imps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
15.8
Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
15.9
Temporal Decoupling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
16.
Analysis Ports .................................................................................................................................................328
17.
Component Classes .........................................................................................................................................331
18.
19.
17.1
uvm_component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
17.2
uvm_test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
17.3
uvm_env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
17.4
uvm_agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
17.5
uvm_monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
17.6
uvm_scoreboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
17.7
uvm_driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
17.8
uvm_push_driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
17.9
uvm_random_stimulus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
17.10
uvm_subscriber. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Comparators ....................................................................................................................................................374
18.1
uvm_in_order_comparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
18.2
uvm_algorithmic_comparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
18.3
uvm_pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
18.4
uvm_policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Sequencer Classes ...........................................................................................................................................387
19.1
uvm_sequencer_base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
19.2
uvm_sequencer_param_base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
19.3
uvm_sequencer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
19.4
uvm_push_sequencer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
UVM 1.2 Class Reference
Front-6
20.
21.
22.
23.
24.
25.
Sequence Classes ............................................................................................................................................406
20.1
uvm_sequence_item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
20.2
uvm_sequence_base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
20.3
uvm_sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
20.4
uvm_sequence_library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Macros.............................................................................................................................................................436
21.1
Report Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
21.2
Component and Object Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
21.3
Sequence-Related Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
21.4
Callback Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
21.5
TLM Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
21.6
Register Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
21.7
Version Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Policy Classes .................................................................................................................................................491
22.1
uvm_printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
22.2
uvm_comparer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
22.3
uvm_recorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
22.4
uvm_packer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
22.5
links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Data Access Policies .......................................................................................................................................538
23.1
Set / Get Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
23.2
Simple Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
23.3
Get To Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
23.4
Set Before Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Register Layer .................................................................................................................................................549
24.1
Register Layer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
24.2
Global Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Register Model ................................................................................................................................................557
25.1
Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
25.2
Address Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
25.3
Register Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
25.4
Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
UVM 1.2 Class Reference
Front-7
26.
27.
28.
29.
25.5
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
25.6
Memories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
25.7
Indirect Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
25.8
FIFO Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
25.9
Virtual Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
25.10
Virtual Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
25.11
Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
25.12
Memory Allocation Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
DUT Integration ..............................................................................................................................................682
26.1
Generic Register Operation Descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
26.2
Register Model Adaptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
26.3
Explicit Register Predictor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
26.4
Register Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
26.5
Backdoors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
26.6
HDL Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
Test Sequences ...............................................................................................................................................711
27.1
Run All Built-In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
27.2
Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
27.3
Register Bit Bash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
27.4
Register Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
27.5
Shared Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
27.6
Memory Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
27.7
Memory Walk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
27.8
HDL Paths Checking Test Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
Command Line Processor (CLP) Class ..........................................................................................................736
28.1
CLP Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
28.2
uvm_cmdline_processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
Globals ............................................................................................................................................................744
29.1
Types and Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
29.2
Globals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
29.3
Core Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
29.4
Traversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
UVM 1.2 Class Reference
Front-8
Bibliography....................................................................................................................................................769
Index................................................................................................................................................................770
UVM 1.2 Class Reference
Front-9
1. Overview
Verification has evolved into a complex project that often spans internal and external teams, but the discontinuity
associated with multiple, incompatible methodologies among those teams has limited productivity. The Universal
Verification Methodology (UVM) 1.2 Class Reference addresses verification complexity and interoperability within
companies and throughout the electronics industry for both novice and advanced teams while also providing
consistency. While UVM is revolutionary, being the first verification methodology to be standardized, it is also
evolutionary, as it is built on the Open Verification Methodology (OVM), which combined the Advanced
Verification Methodology (AVM) with the Universal Reuse Methodology (URM) and concepts from the e Reuse
Methodology (eRM). Furthermore, UVM also infuses concepts and code from the Verification Methodology Manual
(VMM), plus the collective experience and knowledge of the 300+ members of the Accellera Universal Verification
Methodology Work Group (UVMWG) to help standardize verification methodology.
1.1 Scope
The UVM application programming interface (API) defines a standard for the creation, integration, and extension of
UVM Verification Components (UVCs) and verification environments that scale from block to system. The UVM
1.2 Class Reference is independent of any specific design processes and is complete for the construction of
verification environments. The generator to connect register abstractions, many of which are captured using IPXACT (IEEE Std 1685™), is not part of the standard, although a register package is.
1.2 Purpose
The purpose of the UVM 1.2 Class Reference is to enable verification interoperability throughout the electronics
ecosystem. To further that goal, a reference implementation will be made available, along with the UVM 1.2 User’s
Guide. While these materials are neither required to implement UVM, nor considered part of the standard, they help
provide consistency when the UVM 1.2 Class Reference is applied and further enable UVM to achieve its purpose.
UVM 1.2 Class Reference
1
2. Normative References
The following referenced documents are indispensable for the application of this specification (i.e., they must be
understood and used, so each referenced document is cited in text and its relationship to this document is explained).
For dated references, only the edition cited applies. For undated references, the latest edition of the referenced
document (including any amendments or corrigenda) applies.
IEEE Std 1800™, IEEE Standard for SystemVerilog Unified Hardware Design, Specification and Verification Language.1, 2
3. Definitions, Acronyms, and Abbreviations
For the purposes of this document, the following terms and definitions apply. The IEEE Standards Dictionary Online
should be consulted for terms not defined in this clause.3
3.1 Definitions
agent: An abstract container used to emulate and verify DUT devices; agents encapsulate a driver, sequencer, and
monitor.
blocking: An interface where tasks block execution until they complete. See also: non blocking.
component: A piece of VIP that provides functionality and interfaces. Also referred to as a transactor.
consumer: A verification component that receives transactions from another component.
driver: A component responsible for executing or otherwise processing transactions, usually interacting with the
device under test (DUT) to do so.
environment: The container object that defines the testbench topology.
export: A transaction level modeling (TLM) interface that provides the implementation of methods used for communication. Used in UVM to connect to a port.
factory method: A classic software design pattern used to create generic code by deferring, until run time, the exact
specification of the object to be created.
foreign methodology: A verification methodology that is different from the methodology being used for the majority
of the verification environment.
generator: A verification component that provides transactions to another component. Also referred to as a producer.
monitor: A passive entity that samples DUT signals, but does not drive them.
non blocking: A call that returns immediately. See also: blocking.
1
IEEE publications are available from the Institute of Electrical and Electronics Engineers, Inc., 445 Hoes Lane, Piscataway, NJ 08854, USA
(http://standards.ieee.org/).
2
The IEEE standards or products referred to in this clause are trademarks of the Institute of Electrical and Electronics Engineers, Inc.
3IEEE Standards Dictionary Online subscription is available at:
http://www.ieee.org/portal/innovate/products/standard/standards_dictionary.html.
UVM 1.2 Class Reference
2
port: A TLM interface that defines the set of methods used for communication. Used in UVM to connect to an
export.
primary (host) methodology: The methodology that manages the top-level operation of the verification environment
and with which the user/integrator is presumably more familiar.
request: A transaction that provides information to initiate the processing of a particular operation.
response: A transaction that provides information about the completion or status of a particular operation.
scoreboard: The mechanism used to dynamically predict the response of the design and check the observed response
against the predicted response. Usually refers to the entire dynamic response-checking structure.
sequence: A UVM object that procedurally defines a set of transactions to be executed and/or controls the execution
of other sequences.
sequencer: An advanced stimulus generator which executes sequences that define the transactions provided to the
driver for execution.
test: Specific customization of an environment to exercise required functionality of the DUT.
testbench: The structural definition of a set of verification components used to verify a DUT. Also referred to as a
verification environment.
transaction: A class instance that encapsulates information used to communicate between two or more components.
transactor: See component.
virtual sequence: A conceptual term for a sequence that controls the execution of sequences on other sequencers.
3.2 Acronyms and Abbreviations
API
application programming interface
CDV
coverage-driven verification
CBCL common base class library
CLI
command line interface
DUT
device under test
DUV
device under verification
EDA
electronic design automation
FIFO
first-in, first-out
HDL
hardware description language
HVL
high-level verification language
IP
intellectual property
UVM 1.2 Class Reference
3
OSCI
Open SystemC Initiative
TLM
transaction level modeling
UVC
UVM Verification Component
UVM
Universal Verification Methodology
VIP
verification intellectual property
UVM 1.2 Class Reference
4
4. Classes and Utilities
The UVM Class Library provides the building blocks needed to quickly develop wellconstructed and reusable verification components and test environments in
SystemVerilog.
This UVM Class Reference provides detailed reference information for each user-visible
class in the UVM library. For additional information on using UVM, see the UVM User’s
Guide located in the top level directory within the UVM kit.
We divide the UVM classes and utilities into categories pertaining to their role or
function. A more detailed overview of each category-- and the classes comprising them-can be found in the menu at left.
Globals
This category defines a small list of types,
variables, functions, and tasks defined in the
uvm_pkg scope. These items are accessible
from any scope that imports the uvm_pkg. See
Types and Enumerations and Globals for details.
Base
This basic building blocks for all environments
are components, which do the actual work,
transactions, which convey information between
components, and ports, which provide the
interfaces used to convey transactions. The
UVM’s core base classes provide these building
blocks. See Core Base Classes for more
information.
Reporting
The reporting classes provide a facility for
issuing reports (messages) with consistent
formatting and configurable side effects, such
as logging to a file or exiting simulation. Users
can also filter out reports based on their
verbosity , unique ID, or severity. See
Reporting Classes for more information.
Factory
As the name implies, the UVM factory is used to
manufacture (create) UVM objects and
components. Users can configure the factory to
produce an object of a given type on a global
or instance basis. Use of the factory allows
dynamically configurable component hierarchies
and object substitutions without having to
modify their code and without breaking
encapsulation. See Factory Classes for details.
Phasing
This sections describes the phasing capability
providing by UVM. The details can be found in
Phasing Overview.
Configuration and Resources
The Configuration and Resource Classes are a
set of classes which provide a configuration
database. The configuration database is used to
store and retrieve both configuration time and
run time properties.
Synchronization
The UVM provides event and barrier
synchronization classes for process
synchronization. See Synchronization Classes
for more information.
Containers
The Container Classes are type parameterized
UVM 1.2 Class Reference
5
data structures which provide queue and pool
services. The class based queue and pool types
allow for efficient sharing of the data structures
compared with their SystemVerilog built-in
counterparts.
Policies
Each of UVM’s policy classes performs a specific
task for uvm_object-based objects: printing,
comparing, recording, packing, and unpacking. They are implemented separately from
uvm_object so that users can plug in different
ways to print, compare, etc. without modifying
the object class being operated on. The user
can simply apply a different printer or compare
“policy” to change how an object is printed or
compared. See Policy Classes for more
information.
TLM
The UVM TLM library defines several abstract,
transaction-level interfaces and the ports and
exports that facilitate their use. Each TLM
interface consists of one or more methods used
to transport data, typically whole transactions
(objects) at a time. Component designs that
use TLM ports and exports to communicate are
inherently more reusable, interoperable, and
modular. See TLM Interfaces for details.
Components
Components form the foundation of the UVM. They encapsulate behavior of drivers,
scoreboards, and other objects in a testbench. The UVM library provides a set of predefined
component types, all derived directly or
indirectly from uvm_component. See
Predefined Component Classes for more
information.
Sequencers
The sequencer serves as an arbiter for
controlling transaction flow from multiple
stimulus generators. More specifically, the
sequencer controls the flow of
uvm_sequence_item-based transactions
generated by one or more uvm_sequence
#(REQ,RSP)-based sequences. See Sequencer
Classes for more information.
Sequences
Sequences encapsulate user-defined procedures
that generate multiple uvm_sequence_itembased transactions. Such sequences can be
reused, extended, randomized, and combined
sequentially and hierarchically in interesting
ways to produce realistic stimulus to your DUT. See Sequence Classes for more information.
Macros
The UVM provides several macros to help
increase user productivity. See the set of
macro categories in the main menu for a
complete list of macros for Reporting,
Components, Objects, Sequences, Callbacks,
TLM and Registers.
Register Layer
The Register abstraction classes, when properly
extended, abstract the read/write operations to
registers and memories in a design-under-
UVM 1.2 Class Reference
6
verification. See Register Layer for more
information.
Command Line Processor
The command line processor provides a general
interface to the command line arguments that
were provided for the given simulation. The
capabilities are detailed in the
uvm_cmdline_processor section.
Summary
UVM 1.2 Class Reference
The UVM Class Library provides the building blocks needed to quickly develop
well-constructed and reusable verification components and test environments in
SystemVerilog.
UVM 1.2 Class Reference
7
5. Core Base Classes
The UVM library defines a set of base classes and utilities that facilitate the design of
modular, scalable, reusable verification environments.
The basic building blocks for all environments are components and the transactions they
use to communicate. The UVM provides base classes for these, as shown below.
uvm_object - All components and transactions derive from uvm_object, which
defines an interface of core class-based operations: create, copy, compare, print,
sprint, record, etc. It also defines interfaces for instance identification (name, type
name, unique id, etc.) and random seeding.
uvm_component - The uvm_component class is the root base class for all UVM
components. Components are quasi-static objects that exist throughout
simulation. This allows them to establish structural hierarchy much like modules
and program blocks. Every component is uniquely addressable via a hierarchical
path name, e.g. “env1.pci1.master3.driver”. The uvm_component also defines a
phased test flow that components follow during the course of simulation. Each
phase-- build, connect, run, etc.-- is defined by a callback that is executed in
precise order. Finally, the uvm_component also defines configuration, reporting,
transaction recording, and factory interfaces.
uvm_transaction - The uvm_transaction is the root base class for UVM
transactions, which, unlike uvm_components, are transient in nature. It extends
uvm_object to include a timing and recording interface. Simple transactions can
derive directly from uvm_transaction, while sequence-enabled transactions derive
from uvm_sequence_item.
uvm_root - The uvm_root class is special uvm_component that serves as the toplevel component for all UVM components, provides phasing control for all UVM
components, and other global services.
Summary
Core Base Classes
The UVM library defines a set of base classes and utilities that facilitate the
design of modular, scalable, reusable verification environments.
UVM 1.2 Class Reference
8
5.1 Miscellaneous Structures
Contents
Miscellaneous
Structures
uvm_void
uvm_utils #(TYPE,FIELD)
The uvm_void class is the base class for all UVM
classes.
This class contains useful template functions.
uvm_void
The uvm_void class is the base class for all UVM classes. It is an abstract class with no
data members or functions. It allows for generic containers of objects to be created,
similar to a void pointer in the C programming language. User classes derived directly
from uvm_void inherit none of the UVM functionality, but such classes may be placed in
uvm_void-typed containers along with other UVM objects.
Summary
uvm_void
The uvm_void class is the base class for all UVM classes.
CLAss DEcLARATION
virtual class uvm_void
uvm_utils #(TYPE,FIELD)
This class contains useful template functions.
Summary
uvm_utils #(TYPE,FIELD)
This class contains useful template functions.
CLAss DEcLARATION
class uvm_utils #(
type TYPE = int,
string FIELD = "config"
)
METHOds
find_all
get_config
UVM 1.2 Class Reference
Recursively finds all component instances of the parameter type
TYPE, starting with the component given by start.
This method gets the object config of type TYPE associated with
9
component comp.
METHOds
find_all
static function types_t find_all(
uvm_component start
)
Recursively finds all component instances of the parameter type TYPE, starting with the
component given by start. Uses uvm_root::find_all.
get_config
static function TYPE get_config(
uvm_component comp,
bit is_fatal
)
This method gets the object config of type TYPE associated with component comp. We
check for the two kinds of error which may occur with this kind of operation.
UVM 1.2 Class Reference
10
5.2 uvm_object
The uvm_object class is the base class for all UVM data and hierarchical classes. Its
primary role is to define a set of methods for such common operations as create, copy,
compare, print, and record. Classes deriving from uvm_object must implement the pure
virtual methods such as create and get_type_name.
Summary
uvm_object
The uvm_object class is the base class for all UVM data and hierarchical classes.
CLAss HIERARchY
uvm_void
uvm_object
CLAss DEcLARATION
virtual class uvm_object extends uvm_void
new
SEEdING
use_uvm_seeding
reseed
IdENTIFIcATION
set_name
get_name
get_full_name
get_inst_id
get_inst_count
get_type
get_object_type
get_type_name
CREATION
create
clone
PRINTING
print
sprint
do_print
UVM 1.2 Class Reference
Creates a new uvm_object with the given instance name.
This bit enables or disables the UVM seeding
mechanism.
Calls srandom on the object to reseed the object using
the UVM seeding mechanism, which sets the seed based
on type name and instance name instead of based on
instance position in a thread.
Sets the instance name of this object, overwriting any
previously given name.
Returns the name of the object, as provided by the
name argument in the new constructor or set_name
method.
Returns the full hierarchical name of this object.
Returns the object’s unique, numeric instance identifier.
Returns the current value of the instance counter, which
represents the total number of uvm_object-based
objects that have been allocated in simulation.
Returns the type-proxy (wrapper) for this object.
Returns the type-proxy (wrapper) for this object.
This function returns the type name of the object, which
is typically the type identifier enclosed in quotes.
The create method allocates a new object of the same
type as this object and returns it via a base uvm_object
handle.
The clone method creates and returns an exact copy of
this object.
The print method deep-prints this object’s properties in
a format and manner governed by the given printer
argument; if the printer argument is not provided, the
global uvm_default_printer is used.
The sprint method works just like the print method,
except the output is returned in a string rather than
displayed.
The do_print method is the user-definable hook called
by print and sprint that allows users to customize what
11
convert2string
REcORdING
record
do_record
COpYING
copy
do_copy
COMpARING
compare
do_compare
PAcKING
pack
pack_bytes
pack_ints
do_pack
UNpAcKING
unpack
unpack_bytes
unpack_ints
do_unpack
CONFIGuRATION
set_int_local
set_string_local
set_object_local
gets printed or sprinted beyond the field information
provided by the `uvm_field_* macros, Utility and Field
Macros for Components and Objects.
This virtual function is a user-definable hook, called
directly by the user, that allows users to provide object
information in the form of a string.
The record method deep-records this object’s properties
according to an optional recorder policy.
The do_record method is the user-definable hook called
by the record method.
The copy makes this object a copy of the specified
object.
The do_copy method is the user-definable hook called
by the copy method.
Deep compares members of this data object with those
of the object provided in the rhs (right-hand side)
argument, returning 1 on a match, 0 otherwise.
The do_compare method is the user-definable hook
called by the compare method.
The pack methods bitwise-concatenate this object’s
properties into an array of bits, bytes, or ints.
The do_pack method is the user-definable hook called
by the pack methods.
The unpack methods extract property values from an
array of bits, bytes, or ints.
The do_unpack method is the user-definable hook called
by the unpack method.
These methods provide write access to integral, string,
and uvm_object-based properties indexed by a
field_name string.
new
function new (
string name = ""
)
Creates a new uvm_object with the given instance name. If name is not supplied, the
object is unnamed.
SEEdING
use_uvm_seeding
UVM 1.2 Class Reference
12
static bit use_uvm_seeding = 1
This bit enables or disables the UVM seeding mechanism. It globally affects the
operation of the reseed method.
When enabled, UVM-based objects are seeded based on their type and full hierarchical
name rather than allocation order. This improves random stability for objects whose
instance names are unique across each type. The uvm_component class is an example
of a type that has a unique instance name.
reseed
function void reseed ()
Calls srandom on the object to reseed the object using the UVM seeding mechanism,
which sets the seed based on type name and instance name instead of based on
instance position in a thread.
If the use_uvm_seeding static variable is set to 0, then reseed() does not perform any
function.
IdENTIFIcATION
set_name
virtual function void set_name (
string name
)
Sets the instance name of this object, overwriting any previously given name.
get_name
virtual function string get_name ()
Returns the name of the object, as provided by the name argument in the new
constructor or set_name method.
get_full_name
virtual function string get_full_name ()
Returns the full hierarchical name of this object. The default implementation is the same
as get_name, as uvm_objects do not inherently possess hierarchy.
Objects possessing hierarchy, such as uvm_components, override the default
implementation. Other objects might be associated with component hierarchy but are
not themselves components. For example, uvm_sequence #(REQ,RSP) classes are
typically associated with a uvm_sequencer #(REQ,RSP). In this case, it is useful to
override get_full_name to return the sequencer’s full name concatenated with the
sequence’s name. This provides the sequence a full context, which is useful when
debugging.
UVM 1.2 Class Reference
13
get_inst_id
virtual function int get_inst_id ()
Returns the object’s unique, numeric instance identifier.
get_inst_count
static function int get_inst_count()
Returns the current value of the instance counter, which represents the total number of
uvm_object-based objects that have been allocated in simulation. The instance counter
is used to form a unique numeric instance identifier.
get_type
static function uvm_object_wrapper get_type ()
Returns the type-proxy (wrapper) for this object. The uvm_factory’s type-based override
and creation methods take arguments of uvm_object_wrapper. This method, if
implemented, can be used as convenient means of supplying those arguments.
The default implementation of this method produces an error and returns null. To enable
use of this method, a user’s subtype must implement a version that returns the
subtype’s wrapper.
For example
class cmd extends uvm_object;
typedef uvm_object_registry #(cmd) type_id;
static function type_id get_type();
return type_id::get();
endfunction
endclass
Then, to use
factory.set_type_override(cmd::get_type(),subcmd::get_type());
This function is implemented by the `uvm_*_utils macros, if employed.
get_object_type
virtual function uvm_object_wrapper get_object_type ()
Returns the type-proxy (wrapper) for this object. The uvm_factory’s type-based override
and creation methods take arguments of uvm_object_wrapper. This method, if
implemented, can be used as convenient means of supplying those arguments. This
method is the same as the static get_type method, but uses an already allocated object
UVM 1.2 Class Reference
14
to determine the type-proxy to access (instead of using the static object).
The default implementation of this method does a factory lookup of the proxy using the
return value from get_type_name. If the type returned by get_type_name is not
registered with the factory, then a null handle is returned.
For example
class cmd extends uvm_object;
typedef uvm_object_registry #(cmd) type_id;
static function type_id get_type();
return type_id::get();
endfunction
virtual function type_id get_object_type();
return type_id::get();
endfunction
endclass
This function is implemented by the `uvm_*_utils macros, if employed.
get_type_name
virtual function string get_type_name ()
This function returns the type name of the object, which is typically the type identifier
enclosed in quotes. It is used for various debugging functions in the library, and it is
used by the factory for creating objects.
This function must be defined in every derived class.
A typical implementation is as follows
class mytype extends uvm_object;
...
const static string type_name = "mytype";
virtual function string get_type_name();
return type_name;
endfunction
We define the type_name static variable to enable access to the type name without need
of an object of the class, i.e., to enable access via the scope operator,
mytype::type_name.
CREATION
create
virtual function uvm_object create (
string name = ""
)
The create method allocates a new object of the same type as this object and returns it
via a base uvm_object handle. Every class deriving from uvm_object, directly or
UVM 1.2 Class Reference
15
indirectly, must implement the create method.
A typical implementation is as follows
class mytype extends uvm_object;
...
virtual function uvm_object create(string name="");
mytype t = new(name);
return t;
endfunction
clone
virtual function uvm_object clone ()
The clone method creates and returns an exact copy of this object.
The default implementation calls create followed by copy. As clone is virtual, derived
classes may override this implementation if desired.
PRINTING
print
function void print (
uvm_printer printer = null
)
The print method deep-prints this object’s properties in a format and manner governed
by the given printer argument; if the printer argument is not provided, the global
uvm_default_printer is used. See uvm_printer for more information on printer output
formatting. See also uvm_line_printer, uvm_tree_printer, and uvm_table_printer for
details on the pre-defined printer “policies,” or formatters, provided by the UVM.
The print method is not virtual and must not be overloaded. To include custom
information in the print and sprint operations, derived classes must override the do_print
method and use the provided printer policy class to format the output.
sprint
function string sprint (
uvm_printer printer = null
)
The sprint method works just like the print method, except the output is returned in a
string rather than displayed.
The sprint method is not virtual and must not be overloaded. To include additional fields
in the print and sprint operation, derived classes must override the do_print method and
use the provided printer policy class to format the output. The printer policy will manage
all string concatenations and provide the string to sprint to return to the caller.
UVM 1.2 Class Reference
16
do_print
virtual function void do_print (
uvm_printer printer
)
The do_print method is the user-definable hook called by print and sprint that allows
users to customize what gets printed or sprinted beyond the field information provided
by the `uvm_field_* macros, Utility and Field Macros for Components and Objects.
The printer argument is the policy object that governs the format and content of the
output. To ensure correct print and sprint operation, and to ensure a consistent output
format, the printer must be used by all do_print implementations. That is, instead of
using $display or string concatenations directly, a do_print implementation must call
through the printer’s API to add information to be printed or sprinted.
An example implementation of do_print is as follows
class mytype extends uvm_object;
data_obj data;
int f1;
virtual function void do_print (uvm_printer printer);
super.do_print(printer);
printer.print_field_int("f1", f1, $bits(f1), UVM_DEC);
printer.print_object("data", data);
endfunction
Then, to print and sprint the object, you could write
mytype t = new;
t.print();
uvm_report_info("Received",t.sprint());
See uvm_printer for information about the printer API.
convert2string
virtual function string convert2string()
This virtual function is a user-definable hook, called directly by the user, that allows
users to provide object information in the form of a string. Unlike sprint, there is no
requirement to use a uvm_printer policy object. As such, the format and content of the
output is fully customizable, which may be suitable for applications not requiring the
consistent formatting offered by the print/sprint/do_print API.
Fields declared in Utility Macros macros (`uvm_field_*), if used, will not automatically
appear in calls to convert2string.
An example implementation of convert2string follows.
class base extends uvm_object;
string field = "foo";
virtual function string convert2string();
convert2string = {"base_field=",field};
endfunction
endclass
class obj2 extends uvm_object;
UVM 1.2 Class Reference
17
string field = "bar";
virtual function string convert2string();
convert2string = {"child_field=",field};
endfunction
endclass
class obj extends base;
int addr = 'h123;
int data = 'h456;
bit write = 1;
obj2 child = new;
virtual function string convert2string();
convert2string = {super.convert2string(),
$sformatf(" write=%0d addr=%8h data=%8h ",write,addr,data),
child.convert2string()};
endfunction
endclass
Then, to display an object, you could write
obj o = new;
uvm_report_info("BusMaster",{"Sending:\n ",o.convert2string()});
The output will look similar to
UVM_INFO @ 0: reporter [BusMaster] Sending:
base_field=foo write=1 addr=00000123 data=00000456 child_field=bar
REcORdING
record
function void record (
uvm_recorder recorder = null
)
The record method deep-records this object’s properties according to an optional recorder
policy. The method is not virtual and must not be overloaded. To include additional
fields in the record operation, derived classes should override the do_record method.
The optional recorder argument specifies the recording policy, which governs how
recording takes place. See uvm_recorder for information.
A simulator’s recording mechanism is vendor-specific. By providing access via a common
interface, the uvm_recorder policy provides vendor-independent access to a simulator’s
recording capabilities.
do_record
virtual function void do_record (
uvm_recorder recorder
)
The do_record method is the user-definable hook called by the record method. A derived
UVM 1.2 Class Reference
18
class should override this method to include its fields in a record operation.
The recorder argument is policy object for recording this object. A do_record
implementation should call the appropriate recorder methods for each of its fields. Vendor-specific recording implementations are encapsulated in the recorder policy,
thereby insulating user-code from vendor-specific behavior. See uvm_recorder for more
information.
A typical implementation is as follows
class mytype extends uvm_object;
data_obj data;
int f1;
function void do_record (uvm_recorder recorder);
recorder.record_field("f1", f1, $bits(f1), UVM_DEC);
recorder.record_object("data", data);
endfunction
COpYING
copy
function void copy (
uvm_object rhs
)
The copy makes this object a copy of the specified object.
The copy method is not virtual and should not be overloaded in derived classes. To copy
the fields of a derived class, that class should override the do_copy method.
do_copy
virtual function void do_copy (
uvm_object rhs
)
The do_copy method is the user-definable hook called by the copy method. A derived
class should override this method to include its fields in a copy operation.
A typical implementation is as follows
class mytype extends uvm_object;
...
int f1;
function void do_copy (uvm_object rhs);
mytype rhs_;
super.do_copy(rhs);
$cast(rhs_,rhs);
field_1 = rhs_.field_1;
endfunction
The implementation must call super.do_copy, and it must $cast the rhs argument to the
derived type before copying.
UVM 1.2 Class Reference
19
COMpARING
compare
function bit compare (
uvm_object rhs,
uvm_comparer comparer = null
)
Deep compares members of this data object with those of the object provided in the rhs
(right-hand side) argument, returning 1 on a match, 0 otherwise.
The compare method is not virtual and should not be overloaded in derived classes. To
compare the fields of a derived class, that class should override the do_compare method.
The optional comparer argument specifies the comparison policy. It allows you to control
some aspects of the comparison operation. It also stores the results of the comparison,
such as field-by-field miscompare information and the total number of miscompares. If a
compare policy is not provided, then the global uvm_default_comparer policy is used. See uvm_comparer for more information.
do_compare
virtual function bit do_compare (
uvm_object rhs,
uvm_comparer comparer
)
The do_compare method is the user-definable hook called by the compare method. A
derived class should override this method to include its fields in a compare operation. It
should return 1 if the comparison succeeds, 0 otherwise.
A typical implementation is as follows
class mytype extends uvm_object;
...
int f1;
virtual function bit do_compare (uvm_object rhs,uvm_comparer comparer);
mytype rhs_;
do_compare = super.do_compare(rhs,comparer);
$cast(rhs_,rhs);
do_compare &= comparer.compare_field_int("f1", f1, rhs_.f1);
endfunction
A derived class implementation must call super.do_compare() to ensure its base class’
properties, if any, are included in the comparison. Also, the rhs argument is provided as
a generic uvm_object. Thus, you must $cast it to the type of this object before
comparing.
The actual comparison should be implemented using the uvm_comparer object rather
than direct field-by-field comparison. This enables users of your class to customize how
comparisons are performed and how much miscompare information is collected. See
uvm_comparer for more details.
UVM 1.2 Class Reference
20
PAcKING
pack
function int pack (
ref bit bitstream[], input uvm_packer packer
= null
)
pack_bytes
function int pack_bytes (
ref byte unsigned bytestream[], input uvm_packer packer
= null
)
pack_ints
function int pack_ints (
ref int unsigned intstream[], = null
input uvm_packer packer
)
The pack methods bitwise-concatenate this object’s properties into an array of bits,
bytes, or ints. The methods are not virtual and must not be overloaded. To include
additional fields in the pack operation, derived classes should override the do_pack
method.
The optional packer argument specifies the packing policy, which governs the packing
operation. If a packer policy is not provided, the global uvm_default_packer policy is
used. See uvm_packer for more information.
The return value is the total number of bits packed into the given array. Use the array’s
built-in size method to get the number of bytes or ints consumed during the packing
process.
do_pack
virtual function void do_pack (
uvm_packer packer
)
The do_pack method is the user-definable hook called by the pack methods. A derived
class should override this method to include its fields in a pack operation.
The packer argument is the policy object for packing. The policy object should be used
to pack objects.
A typical example of an object packing itself is as follows
class mysubtype extends mysupertype;
...
shortint myshort;
obj_type myobj;
byte myarray[];
...
function void do_pack (uvm_packer packer);
super.do_pack(packer); // pack mysupertype properties
UVM 1.2 Class Reference
21
packer.pack_field_int(myarray.size(), 32);
foreach (myarray)
packer.pack_field_int(myarray[index], 8);
packer.pack_field_int(myshort, $bits(myshort));
packer.pack_object(myobj);
endfunction
The implementation must call super.do_pack so that base class properties are packed as
well.
If your object contains dynamic data (object, string, queue, dynamic array, or associative
array), and you intend to unpack into an equivalent data structure when unpacking, you
must include meta-information about the dynamic data when packing as follows.
For queues, dynamic arrays, or associative arrays, pack the number of elements in
the array in the 32 bits immediately before packing individual elements, as shown
above.
For string data types, append a zero byte after packing the string contents.
For objects, pack 4 bits immediately before packing the object. For null objects,
pack 4’b0000. For non-null objects, pack 4’b0001.
When the `uvm_field_* macros are used, Utility and Field Macros for Components and
Objects, the above meta information is included provided the
uvm_packer::use_metadata variable is set for the packer.
Packing order does not need to match declaration order. However, unpacking order must
match packing order.
UNpAcKING
unpack
function int unpack (
ref bit bitstream[], = null
input uvm_packer packer
)
unpack_bytes
function int unpack_bytes (
ref byte unsigned bytestream[], input uvm_packer packer
= null
)
unpack_ints
function int unpack_ints (
ref int unsigned intstream[], = null
input uvm_packer packer
)
The unpack methods extract property values from an array of bits, bytes, or ints. The
method of unpacking must exactly correspond to the method of packing. This is assured
if (a) the same packer policy is used to pack and unpack, and (b) the order of unpacking
is the same as the order of packing used to create the input array.
UVM 1.2 Class Reference
22
The unpack methods are fixed (non-virtual) entry points that are directly callable by the
user. To include additional fields in the unpack operation, derived classes should override
the do_unpack method.
The optional packer argument specifies the packing policy, which governs both the pack
and unpack operation. If a packer policy is not provided, then the global
uvm_default_packer policy is used. See uvm_packer for more information.
The return value is the actual number of bits unpacked from the given array.
do_unpack
virtual function void do_unpack (
uvm_packer packer
)
The do_unpack method is the user-definable hook called by the unpack method. A
derived class should override this method to include its fields in an unpack operation.
The packer argument is the policy object for both packing and unpacking. It must be
the same packer used to pack the object into bits. Also, do_unpack must unpack fields
in the same order in which they were packed. See uvm_packer for more information.
The following implementation corresponds to the example given in do_pack.
function void do_unpack (uvm_packer packer);
int sz;
super.do_unpack(packer); // unpack super's properties
sz = packer.unpack_field_int(myarray.size(), 32);
myarray.delete();
for(int index=0; index<sz; index++)
myarray[index] = packer.unpack_field_int(8);
myshort = packer.unpack_field_int($bits(myshort));
packer.unpack_object(myobj);
endfunction
If your object contains dynamic data (object, string, queue, dynamic array, or associative
array), and you intend to unpack into an equivalent data structure, you must have
included meta-information about the dynamic data when it was packed.
For queues, dynamic arrays, or associative arrays, unpack the number of elements
in the array from the 32 bits immediately before unpacking individual elements, as
shown above.
For string data types, unpack into the new string until a null byte is encountered.
For objects, unpack 4 bits into a byte or int variable. If the value is 0, the target
object should be set to null and unpacking continues to the next property, if any. If the least significant bit is 1, then the target object should be allocated and its
properties unpacked.
CONFIGuRATION
set_int_local
virtual function void set_int_local (
string field_name, uvm_bitstream_t value,
recurse
= 1
bit UVM 1.2 Class Reference
23
)
set_string_local
virtual function void set_string_local (
string field_name, string value,
bit recurse
= 1
)
set_object_local
virtual function void set_object_local (
string field_name, uvm_object value,
bit clone
= 1,
bit recurse
= 1
)
These methods provide write access to integral, string, and uvm_object-based properties
indexed by a field_name string. The object designer choose which, if any, properties will
be accessible, and overrides the appropriate methods depending on the properties’
types. For objects, the optional clone argument specifies whether to clone the value
argument before assignment.
The global uvm_is_match function is used to match the field names, so field_name may
contain wildcards.
An example implementation of all three methods is as follows.
class mytype extends uvm_object;
local
local
local
local
local
int myint;
byte mybyte;
shortint myshort; // no access
string mystring;
obj_type myobj;
// provide access to integral properties
function void set_int_local(string field_name, uvm_bitstream_t value);
if (uvm_is_match (field_name, "myint"))
myint = value;
else if (uvm_is_match (field_name, "mybyte"))
mybyte = value;
endfunction
// provide access to string properties
function void set_string_local(string field_name, string value);
if (uvm_is_match (field_name, "mystring"))
mystring = value;
endfunction
// provide access to sub-objects
function void set_object_local(string field_name, uvm_object value,
bit clone=1);
if (uvm_is_match (field_name, "myobj")) begin
if (value != null) begin
obj_type tmp;
// if provided value is not correct type, produce error
if (!$cast(tmp, value) )
/* error */
else begin
if(clone)
$cast(myobj, tmp.clone());
else
myobj = tmp;
end
end
else
myobj = null; // value is null, so simply assign null to myobj
end
endfunction
...
UVM 1.2 Class Reference
24
Although the object designer implements these methods to provide outside access to one
or more properties, they are intended for internal use (e.g., for command-line debugging
and auto-configuration) and should not be called directly by the user.
UVM 1.2 Class Reference
25
5.3 uvm_transaction
The uvm_transaction class is the root base class for UVM transactions. Inheriting all the
methods of uvm_object, uvm_transaction adds a timing and recording interface.
This class provides timestamp properties, notification events, and transaction recording
support.
Use of this class as a base for user-defined transactions is deprecated. Its subtype,
uvm_sequence_item, shall be used as the base class for all user-defined transaction
types.
The intended use of this API is via a uvm_driver #(REQ,RSP) to call
uvm_component::accept_tr, uvm_component::begin_tr, and uvm_component::end_tr
during the course of sequence item execution. These methods in the component base
class will call into the corresponding methods in this class to set the corresponding
timestamps (accept_time, begin_time, and end_time), trigger the corresponding event
(begin_event and end_event, and, if enabled, record the transaction contents to a
vendor-specific transaction database.
Note that get_next_item/item_done when called on a uvm_seq_item_pull_port will
automatically trigger the begin_event and end_events via calls to begin_tr and end_tr. While convenient, it is generally the responsibility of drivers to mark a transaction’s
progress during execution. To allow the driver or layering sequence to control sequence
item timestamps, events, and recording, you must call
uvm_sqr_if_base#(REQ,RSP)::disable_auto_item_recording at the beginning of the
driver’s run_phase task.
Users may also use the transaction’s event pool, events, to define custom events for the
driver to trigger and the sequences to wait on. Any in-between events such as marking
the beginning of the address and data phases of transaction execution could be
implemented via the events pool.
In pipelined protocols, the driver may release a sequence (return from finish_item() or
its `uvm_do macro) before the item has been completed. If the driver uses the
begin_tr/end_tr API in uvm_component, the sequence can wait on the item’s end_event
to block until the item was fully executed, as in the following example.
task uvm_execute(item, ...);
// can use the `uvm_do macros as well
start_item(item);
item.randomize();
finish_item(item);
item.end_event.wait_on();
// get_response(rsp, item.get_transaction_id()); //if needed
endtask
A simple two-stage pipeline driver that can execute address and data phases
concurrently might be implemented as follows:
task run();
// this driver supports a two-deep pipeline
fork
do_item();
do_item();
join
endtask
task do_item();
forever begin
mbus_item req;
UVM 1.2 Class Reference
26
lock.get();
seq_item_port.get(req); // Completes the sequencer-driver handshake
accept_tr(req);
// request bus, wait for grant, etc.
begin_tr(req);
// execute address phase
// allows next transaction to begin address phase
lock.put();
// execute data phase
// (may trigger custom "data_phase" event here)
end_tr(req);
end
endtask: do_item
Summary
uvm_transaction
The uvm_transaction class is the root base class for UVM transactions.
CLAss HIERARchY
uvm_void
uvm_object
uvm_transaction
CLAss DEcLARATION
virtual class uvm_transaction extends uvm_object
METhOds
new
accept_tr
do_accept_tr
begin_tr
begin_child_tr
do_begin_tr
end_tr
do_end_tr
get_tr_handle
disable_recording
enable_recording
is_recording_enabled
is_active
get_event_pool
set_initiator
UVM 1.2 Class Reference
Creates a new transaction object.
Calling accept_tr indicates that the transaction item
has been received by a consumer component.
This user-definable callback is called by accept_tr
just before the accept event is triggered.
This function indicates that the transaction has been
started and is not the child of another transaction.
This function indicates that the transaction has been
started as a child of a parent transaction given by
parent_handle.
This user-definable callback is called by begin_tr and
begin_child_tr just before the begin event is
triggered.
This function indicates that the transaction execution
has ended.
This user-definable callback is called by end_tr just
before the end event is triggered.
Returns the handle associated with the transaction,
as set by a previous call to begin_child_tr or
begin_tr with transaction recording enabled.
Turns off recording for the transaction stream.
Turns on recording to the stream specified.
Returns 1 if recording is currently on, 0 otherwise.
Returns 1 if the transaction has been started but has
not yet been ended.
Returns the event pool associated with this
transaction.
Sets initiator as the initiator of this transaction.
27
get_initiator
get_accept_time
get_begin_time
get_end_time
set_transaction_id
get_transaction_id
VARIABLEs
events
begin_event
end_event
Returns the component that produced or started the
transaction, as set by a previous call to set_initiator.
Returns the time at which this transaction was
accepted, begun, or ended, as by a previous call to
accept_tr, begin_tr, begin_child_tr, or end_tr.
Sets this transaction’s numeric identifier to id.
Returns this transaction’s numeric identifier, which is
-1 if not set explicitly by set_transaction_id.
The event pool instance for this transaction.
A uvm_event#(uvm_object) that is triggered
this transaction’s actual execution on the bus
typically as a result of a driver calling
uvm_component::begin_tr.
A uvm_event#(uvm_object) that is triggered
this transaction’s actual execution on the bus
typically as a result of a driver calling
uvm_component::end_tr.
when
begins,
when
ends,
METhOds
new
function new (
string name
= "",
uvm_component initiator = null
)
Creates a new transaction object. The name is the instance name of the transaction. If
not supplied, then the object is unnamed.
accept_tr
function void accept_tr (
time accept_time = 0
)
Calling accept_tr indicates that the transaction item has been received by a consumer
component. Typically a uvm_driver #(REQ,RSP) would call uvm_component::accept_tr,
which calls this method-- upon return from a get_next_item(), get(), or peek()
call on its sequencer port, uvm_driver#(REQ,RSP)::seq_item_port.
With some protocols, the received item may not be started immediately after it is
accepted. For example, a bus driver, having accepted a request transaction, may still
have to wait for a bus grant before beginning to execute the request.
This function performs the following actions
The transaction’s internal accept time is set to the current simulation time, or to
accept_time if provided and non-zero. The accept_time may be any time, past or
future.
The transaction’s internal accept event is triggered. Any processes waiting on the
this event will resume in the next delta cycle.
The do_accept_tr method is called to allow for any post-accept action in derived
UVM 1.2 Class Reference
28
classes.
do_accept_tr
virtual protected function void do_accept_tr ()
This user-definable callback is called by accept_tr just before the accept event is
triggered. Implementations should call super.do_accept_tr to ensure correct operation.
begin_tr
function integer begin_tr (
time begin_time = 0
)
This function indicates that the transaction has been started and is not the child of
another transaction. Generally, a consumer component begins execution of a
transactions it receives.
Typically a uvm_driver #(REQ,RSP) would call uvm_component::begin_tr, which calls this
method, before actual execution of a sequence item transaction. Sequence items
received by a driver are always a child of a parent sequence. In this case, begin_tr
obtains the parent handle and delegates to begin_child_tr.
See accept_tr for more information on how the begin-time might differ from when the
transaction item was received.
This function performs the following actions
The transaction’s internal start time is set to the current simulation time, or to
begin_time if provided and non-zero. The begin_time may be any time, past or
future, but should not be less than the accept time.
If recording is enabled, then a new database-transaction is started with the same
begin time as above.
The do_begin_tr method is called to allow for any post-begin action in derived
classes.
The transaction’s internal begin event is triggered. Any processes waiting on this
event will resume in the next delta cycle.
The return value is a transaction handle, which is valid (non-zero) only if recording is
enabled. The meaning of the handle is implementation specific.
begin_child_tr
function integer begin_child_tr (
time begin_time
= 0,
integer parent_handle = 0
)
This function indicates that the transaction has been started as a child of a parent
transaction given by parent_handle. Generally, a consumer component calls this method
via uvm_component::begin_child_tr to indicate the actual start of execution of this
transaction.
The parent handle is obtained by a previous call to begin_tr or begin_child_tr. If the
parent_handle is invalid (=0), then this function behaves the same as begin_tr.
UVM 1.2 Class Reference
29
This function performs the following actions
The transaction’s internal start time is set to the current simulation time, or to
begin_time if provided and non-zero. The begin_time may be any time, past or
future, but should not be less than the accept time.
If recording is enabled, then a new database-transaction is started with the same
begin time as above. The inherited uvm_object::record method is then called,
which records the current property values to this new transaction. Finally, the
newly started transaction is linked to the parent transaction given by
parent_handle.
The do_begin_tr method is called to allow for any post-begin action in derived
classes.
The transaction’s internal begin event is triggered. Any processes waiting on this
event will resume in the next delta cycle.
The return value is a transaction handle, which is valid (non-zero) only if recording is
enabled. The meaning of the handle is implementation specific.
do_begin_tr
virtual protected function void do_begin_tr ()
This user-definable callback is called by begin_tr and begin_child_tr just before the begin
event is triggered. Implementations should call super.do_begin_tr to ensure correct
operation.
end_tr
function void end_tr (
time end_time
= 0,
bit free_handle = 1
)
This function indicates that the transaction execution has ended. Generally, a consumer
component ends execution of the transactions it receives.
You must have previously called begin_tr or begin_child_tr for this call to be successful.
Typically a uvm_driver #(REQ,RSP) would call uvm_component::end_tr, which calls this
method, upon completion of a sequence item transaction. Sequence items received by a
driver are always a child of a parent sequence. In this case, begin_tr obtain the parent
handle and delegate to begin_child_tr.
This function performs the following actions
The transaction’s internal end time is set to the current simulation time, or to
end_time if provided and non-zero. The end_time may be any time, past or
future, but should not be less than the begin time.
If recording is enabled and a database-transaction is currently active, then the
record method inherited from uvm_object is called, which records the final
property values. The transaction is then ended. If free_handle is set, the
transaction is released and can no longer be linked to (if supported by the
implementation).
The do_end_tr method is called to allow for any post-end action in derived classes.
The transaction’s internal end event is triggered. Any processes waiting on this
event will resume in the next delta cycle.
UVM 1.2 Class Reference
30
do_end_tr
virtual protected function void do_end_tr ()
This user-definable callback is called by end_tr just before the end event is triggered. Implementations should call super.do_end_tr to ensure correct operation.
get_tr_handle
function integer get_tr_handle ()
Returns the handle associated with the transaction, as set by a previous call to
begin_child_tr or begin_tr with transaction recording enabled.
disable_recording
function void disable_recording ()
Turns off recording for the transaction stream. This method does not effect a
uvm_component’s recording streams.
enable_recording
function void enable_recording (
uvm_tr_stream stream
)
Turns on recording to the stream specified.
If transaction recording is on, then a call to record is made when the transaction is
ended.
is_recording_enabled
function bit is_recording_enabled()
Returns 1 if recording is currently on, 0 otherwise.
is_active
function bit is_active ()
Returns 1 if the transaction has been started but has not yet been ended. Returns 0 if
the transaction has not been started.
get_event_pool
function uvm_event_pool get_event_pool ()
UVM 1.2 Class Reference
31
Returns the event pool associated with this transaction.
By default, the event pool contains the events: begin, accept, and end. Events can also
be added by derivative objects. An event pool is a specialization of uvm_pool#(KEY,T),
e.g. a uvm_pool#(uvm_event).
set_initiator
function void set_initiator (
uvm_component initiator
)
Sets initiator as the initiator of this transaction.
The initiator can be the component that produces the transaction. It can also be the
component that started the transaction. This or any other usage is up to the transaction
designer.
get_initiator
function uvm_component get_initiator ()
Returns the component that produced or started the transaction, as set by a previous call
to set_initiator.
get_accept_time
function time get_accept_time ()
get_begin_time
function time get_begin_time ()
get_end_time
function time get_end_time ()
Returns the time at which this transaction was accepted, begun, or ended, as by a
previous call to accept_tr, begin_tr, begin_child_tr, or end_tr.
set_transaction_id
function void set_transaction_id(
integer id
)
Sets this transaction’s numeric identifier to id. If not set via this method, the transaction
ID defaults to -1.
When using sequences to generate stimulus, the transaction ID is used along with the
sequence ID to route responses in sequencers and to correlate responses to requests.
UVM 1.2 Class Reference
32
get_transaction_id
function integer get_transaction_id()
Returns this transaction’s numeric identifier, which is -1 if not set explicitly by
set_transaction_id.
When using a uvm_sequence #(REQ,RSP) to generate stimulus, the transaction ID is
used along with the sequence ID to route responses in sequencers and to correlate
responses to requests.
VARIABLEs
events
const uvm_event_pool events = new
The event pool instance for this transaction. This pool is used to track various
milestones: by default, begin, accept, and end
begin_event
uvm_event#(
uvm_object
) begin_event
A uvm_event#(uvm_object) that is triggered when this transaction’s actual execution on
the bus begins, typically as a result of a driver calling uvm_component::begin_tr. Processes that wait on this event will block until the transaction has begun.
For more information, see the general discussion for uvm_transaction. See
uvm_event#(T) for details on the event API.
end_event
uvm_event#(
uvm_object
) end_event
A uvm_event#(uvm_object) that is triggered when this transaction’s actual execution on
the bus ends, typically as a result of a driver calling uvm_component::end_tr. Processes
that wait on this event will block until the transaction has ended.
For more information, see the general discussion for uvm_transaction. See
uvm_event#(T) for details on the event API.
virtual task my_sequence::body();
...
start_item(item);
\
item.randomize();
} `uvm_do(item)
finish_item(item);
/
// return from finish item does not always mean item is completed
item.end_event.wait_on();
...
UVM 1.2 Class Reference
33
5.4 uvm_root
The uvm_root class serves as the implicit top-level and phase controller for all UVM
components. Users do not directly instantiate uvm_root. The UVM automatically creates
a single instance of uvm_root that users can access via the global (uvm_pkg-scope)
variable, uvm_top.
The uvm_top instance of uvm_root plays several key roles in the UVM.
Implicit top-level
The uvm_top serves as an implicit top-level
component. Any component whose parent is specified
as null becomes a child of uvm_top. Thus, all UVM
components in simulation are descendants of uvm_top.
Phase control
uvm_top manages the phasing for all components.
Search
Use uvm_top to search for components based on their
hierarchical name. See find and find_all.
Report configuration
Use uvm_top to globally configure report verbosity, log
files, and actions. For example,
uvm_top.set_report_verbosity_level_hier(UVM_FULL)
would set full verbosity for all components in simulation.
Global reporter
Because uvm_top is globally accessible (in uvm_pkg
scope), UVM’s reporting mechanism is accessible from
anywhere outside uvm_component, such as in modules
and sequences. See uvm_report_error,
uvm_report_warning, and other global methods.
The uvm_top instance checks during the end_of_elaboration phase if any errors have
been generated so far. If errors are found a UVM_FATAL error is being generated as
result so that the simulation will not continue to the start_of_simulation_phase.
Summary
uvm_root
The uvm_root class serves as the implicit top-level and phase controller for all
UVM components.
get()
SIMULATION CONTROL
run_test
die
set_timeout
finish_on_completion
TOPOLOGY
top_levels
UVM 1.2 Class Reference
Static accessor for uvm_root.
Phases all components through all registered
phases.
This method is called by the report server if a report
reaches the maximum quit count or has a
UVM_EXIT action associated with it, e.g., as with
fatal errors.
Specifies the timeout for the simulation.
If set, then run_test will call $finish after all phases
are executed.
This variable is a list of all of the top level
34
find
find_all
print_topology
enable_print_topology
GLOBAL VARIABLEs
uvm_top
components in UVM.
Returns the component handle (find) or list of
components handles (find_all) matching a given
string.
Print the verification environment’s component
topology.
If set, then the entire testbench topology is printed
just after completion of the end_of_elaboration
phase.
This is the top-level that governs phase execution
and provides component search interface.
get()
static function uvm_root get()
Static accessor for uvm_root.
The static accessor is provided as a convenience wrapper around retrieving the root via
the uvm_coreservice_t::get_root method.
// Using the uvm_coreservice_t:
uvm_coreservice_t cs;
uvm_root r;
cs = uvm_coreservice_t::get();
r = cs.get_root();
// Not using the uvm_coreservice_t:
uvm_root r;
r = uvm_root::get();
SIMULATION CONTROL
run_test
virtual task run_test (
string test_name = ""
)
Phases all components through all registered phases. If the optional test_name
argument is provided, or if a command-line plusarg, +UVM_TESTNAME=TEST_NAME, is
found, then the specified component is created just prior to phasing. The test may
contain new verification components or the entire testbench, in which case the test and
testbench can be chosen from the command line without forcing recompilation. If the
global (package) variable, finish_on_completion, is set, then $finish is called after
phasing completes.
die
virtual function void die()
This method is called by the report server if a report reaches the maximum quit count or
UVM 1.2 Class Reference
35
has a UVM_EXIT action associated with it, e.g., as with fatal errors.
Calls the uvm_component::pre_abort() method on the entire uvm_component hierarchy
in a bottom-up fashion. It then calls uvm_report_server::report_summarize and
terminates the simulation with $finish.
set_timeout
function void set_timeout(
time timeout,
bit overridable = 1
)
Specifies the timeout for the simulation. Default is `UVM_DEFAULT_TIMEOUT
The timeout is simply the maximum absolute simulation time allowed before a FATAL
occurs. If the timeout is set to 20ns, then the simulation must end before 20ns, or a
FATAL timeout will occur.
This is provided so that the user can prevent the simulation from potentially consuming
too many resources (Disk, Memory, CPU, etc) when the testbench is essentially hung.
finish_on_completion
bit finish_on_completion = 1
If set, then run_test will call $finish after all phases are executed.
TOPOLOGY
top_levels
uvm_component top_levels[$]
This variable is a list of all of the top level components in UVM. It includes the
uvm_test_top component that is created by run_test as well as any other top level
components that have been instantiated anywhere in the hierarchy.
find
function uvm_component find (
string comp_match
)
find_all
function void find_all (
string comp_match, ref uvm_component comps[$], = null
input uvm_component comp
)
UVM 1.2 Class Reference
36
Returns the component handle (find) or list of components handles (find_all) matching a
given string. The string may contain the wildcards,
and ?. Strings beginning with ‘.’ are absolute path names. If the optional
argument comp is provided, then search begins from that component down
(default=all components).
print_topology
function void print_topology (
uvm_printer printer = null
)
Print the verification environment’s component topology. The printer is a uvm_printer
object that controls the format of the topology printout; a null printer prints with the
default output.
enable_print_topology
bit enable_print_topology = 0
If set, then the entire testbench topology is printed just after completion of the
end_of_elaboration phase.
GLOBAL VARIABLEs
uvm_top
const uvm_root uvm_top = uvm_root::get()
This is the top-level that governs phase execution and provides component search
interface. See uvm_root for more information.
UVM 1.2 Class Reference
37
5.5 Port Base Classes
Contents
Port Base Classes
uvm_port_component_base This class defines an interface for obtaining a port’s
connectivity lists after or during the
end_of_elaboration phase.
uvm_port_component
See description of uvm_port_component_base for
#(PORT)
information about this class
uvm_port_base #(IF)
Transaction-level communication between
components is handled via its ports, exports, and
imps, all of which derive from this class.
uvm_port_component_base
This class defines an interface for obtaining a port’s connectivity lists after or during the
end_of_elaboration phase. The sub-class, uvm_port_component #(PORT), implements
this interface.
The connectivity lists are returned in the form of handles to objects of this type. This
allowing traversal of any port’s fan-out and fan-in network through recursive calls to
get_connected_to and get_provided_to. Each port’s full name and type name can be
retrieved using get_full_name and get_type_name methods inherited from
uvm_component.
Summary
uvm_port_component_base
This class defines an interface for obtaining a port’s connectivity lists after or
during the end_of_elaboration phase.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_port_component_base
CLAss DEcLARATION
virtual class uvm_port_component_base extends
uvm_component
METhOds
get_connected_to
get_provided_to
UVM 1.2 Class Reference
For a port or export type, this function fills list with all of
the ports, exports and implementations that this port is
connected to.
For an implementation or export type, this function fills
list with all of the ports, exports and implementations
38
is_port
is_export
is_imp
that this port is provides its implementation to.
These function determine the type of port.
METhOds
get_connected_to
pure virtual function void get_connected_to(
ref uvm_port_list list
)
For a port or export type, this function fills list with all of the ports, exports and
implementations that this port is connected to.
get_provided_to
pure virtual function void get_provided_to(
ref uvm_port_list list
)
For an implementation or export type, this function fills list with all of the ports, exports
and implementations that this port is provides its implementation to.
is_port
pure virtual function bit is_port()
is_export
pure virtual function bit is_export()
is_imp
pure virtual function bit is_imp()
These function determine the type of port. The functions are mutually exclusive; one will
return 1 and the other two will return 0.
uvm_port_component #(PORT)
See description of uvm_port_component_base for information about this class
Summary
UVM 1.2 Class Reference
39
uvm_port_component #(PORT)
See description of uvm_port_component_base for information about this class
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_port_component_base
uvm_port_component#(PORT)
CLAss DEcLARATION
class uvm_port_component #(
type PORT = uvm_object
) extends uvm_port_component_base
METhOds
get_port
Retrieve the actual port object that this proxy refers to.
METhOds
get_port
function PORT get_port()
Retrieve the actual port object that this proxy refers to.
uvm_port_base #(IF)
Transaction-level communication between components is handled via its ports, exports,
and imps, all of which derive from this class.
The uvm_port_base extends IF, which is the type of the interface implemented by
derived port, export, or implementation. IF is also a type parameter to uvm_port_base.
IF
The interface type implemented by the subtype to this base port
The UVM provides a complete set of ports, exports, and imps for the OSCI- standard TLM
interfaces. They can be found in the ../src/tlm/ directory. For the TLM interfaces, the IF
parameter is always uvm_tlm_if_base #(T1,T2).
Just before uvm_component::end_of_elaboration_phase, an internal
uvm_component::resolve_bindings process occurs, after which each port and export
holds a list of all imps connected to it via hierarchical connections to other ports and
exports. In effect, we are collapsing the port’s fanout, which can span several levels up
and down the component hierarchy, into a single array held local to the port. Once the
list is determined, the port’s min and max connection settings can be checked and
enforced.
UVM 1.2 Class Reference
40
uvm_port_base possesses the properties of components in that they have a hierarchical
instance path and parent. Because SystemVerilog does not support multiple inheritance,
uvm_port_base cannot extend both the interface it implements and uvm_component. Thus, uvm_port_base contains a local instance of uvm_component, to which it delegates
such commands as get_name, get_full_name, and get_parent.
Summary
uvm_port_base #(IF)
Transaction-level communication between components is handled via its ports,
exports, and imps, all of which derive from this class.
CLAss HIERARchY
IF
uvm_port_base#(IF)
CLAss DEcLARATION
virtual class uvm_port_base #(
type IF = uvm_void
) extends IF
METhOds
new
get_name
get_full_name
get_parent
get_comp
get_type_name
min_size
max_size
is_unbounded
is_port
is_export
is_imp
size
set_default_index
connect
debug_connected_to
debug_provided_to
resolve_bindings
get_if
UVM 1.2 Class Reference
The first two arguments are the normal
uvm_component constructor arguments.
Returns the leaf name of this port.
Returns the full hierarchical name of this port.
Returns the handle to this port’s parent, or null if it
has no parent.
Returns a handle to the internal proxy component
representing this port.
Returns the type name to this port.
Returns the minimum number of implementation
ports that must be connected to this port by the
end_of_elaboration phase.
Returns the maximum number of implementation
ports that must be connected to this port by the
end_of_elaboration phase.
Returns 1 if this port has no maximum on the number
of implementation ports this port can connect to.
Returns 1 if this port is of the type given by the
method name, 0 otherwise.
Gets the number of implementation ports connected
to this port.
Sets the default implementation port to use when
calling an interface method.
Connects this port to the given provider port.
The debug_connected_to method outputs a visual
text display of the port/export/imp network to which
this port connects (i.e., the port’s fanout).
The debug_provided_to method outputs a visual
display of the port/export network that ultimately
connect to this port (i.e., the port’s fanin).
This callback is called just before entering the
end_of_elaboration phase.
Returns the implementation (imp) port at the given
index from the array of imps this port is connected
to.
41
METhOds
new
function new (
string name,
uvm_component parent,
uvm_port_type_e port_type, min_size = 0,
int int max_size = 1
)
The first two arguments are the normal uvm_component constructor arguments.
The port_type can be one of UVM_PORT, UVM_EXPORT, or UVM_IMPLEMENTATION.
The min_size and max_size specify the minimum and maximum number of
implementation (imp) ports that must be connected to this port base by the end of
elaboration. Setting max_size to UVM_UNBOUNDED_CONNECTIONS sets no maximum,
i.e., an unlimited number of connections are allowed.
By default, the parent/child relationship of any port being connected to this port is not
checked. This can be overridden by configuring the port’s check_connection_relationships
bit via uvm_config_int::set(). See connect for more information.
get_name
function string get_name()
Returns the leaf name of this port.
get_full_name
virtual function string get_full_name()
Returns the full hierarchical name of this port.
get_parent
virtual function uvm_component get_parent()
Returns the handle to this port’s parent, or null if it has no parent.
get_comp
virtual function uvm_port_component_base get_comp()
Returns a handle to the internal proxy component representing this port.
Ports are considered components. However, they do not inherit uvm_component. Instead, they contain an instance of uvm_port_component #(PORT) that serves as a
proxy to this port.
UVM 1.2 Class Reference
42
get_type_name
virtual function string get_type_name()
Returns the type name to this port. Derived port classes must implement this method to
return the concrete type. Otherwise, only a generic “uvm_port”, “uvm_export” or
“uvm_implementation” is returned.
min_size
Returns the minimum number of implementation ports that must be connected to this
port by the end_of_elaboration phase.
max_size
Returns the maximum number of implementation ports that must be connected to this
port by the end_of_elaboration phase.
is_unbounded
function bit is_unbounded ()
Returns 1 if this port has no maximum on the number of implementation ports this port
can connect to. A port is unbounded when the max_size argument in the constructor is
specified as UVM_UNBOUNDED_CONNECTIONS.
is_port
function bit is_port ()
is_export
function bit is_export ()
is_imp
function bit is_imp ()
Returns 1 if this port is of the type given by the method name, 0 otherwise.
size
function int size ()
Gets the number of implementation ports connected to this port. The value is not valid
before the end_of_elaboration phase, as port connections have not yet been resolved.
UVM 1.2 Class Reference
43
set_default_index
function void set_default_index (
int index
)
Sets the default implementation port to use when calling an interface method. This
method should only be called on UVM_EXPORT types. The value must not be set before
the end_of_elaboration phase, when port connections have not yet been resolved.
connect
virtual function void connect (
this_type provider
)
Connects this port to the given provider port. The ports must be compatible in the
following ways
Their type parameters must match
The provider’s interface type (blocking, non-blocking, analysis, etc.) must be
compatible. Each port has an interface mask that encodes the interface(s) it
supports. If the bitwise AND of these masks is equal to the this port’s mask, the
requirement is met and the ports are compatible. For example, a
uvm_blocking_put_port #(T) is compatible with a uvm_put_export #(T) and
uvm_blocking_put_imp #(T) because the export and imp provide the interface
required by the uvm_blocking_put_port.
Ports of type UVM_EXPORT can only connect to other exports or imps.
Ports of type UVM_IMPLEMENTATION cannot be connected, as they are bound to
the component that implements the interface at time of construction.
In addition to type-compatibility checks, the relationship between this port and the
provider port will also be checked if the port’s check_connection_relationships
configuration has been set. (See new for more information.)
Relationships, when enabled, are checked are as follows
If this port is a UVM_PORT type, the provider can be a parent port, or a sibling
export or implementation port.
If this port is a UVM_EXPORT type, the provider can be a child export or
implementation port.
If any relationship check is violated, a warning is issued.
Note- the uvm_component::connect_phase method is related to but not the same as this
method. The component’s connect method is a phase callback where port’s connect
method calls are made.
debug_connected_to
function void debug_connected_to (
int level
= 0,
int max_level = -1
)
The debug_connected_to method outputs a visual text display of the port/export/imp
network to which this port connects (i.e., the port’s fanout).
UVM 1.2 Class Reference
44
This method must not be called before the end_of_elaboration phase, as port connections
are not resolved until then.
debug_provided_to
function void debug_provided_to (
int level
= 0,
int max_level = -1
)
The debug_provided_to method outputs a visual display of the port/export network that
ultimately connect to this port (i.e., the port’s fanin).
This method must not be called before the end_of_elaboration phase, as port connections
are not resolved until then.
resolve_bindings
virtual function void resolve_bindings()
This callback is called just before entering the end_of_elaboration phase. It recurses
through each port’s fanout to determine all the imp destinations. It then checks against
the required min and max connections. After resolution, size returns a valid value and
get_if can be used to access a particular imp.
This method is automatically called just before the start of the end_of_elaboration
phase. Users should not need to call it directly.
get_if
function uvm_port_base #(
IF
) get_if(int index=0)
Returns the implementation (imp) port at the given index from the array of imps this
port is connected to. Use size to get the valid range for index. This method can only be
called at the end_of_elaboration phase or after, as port connections are not resolved
before then.
UVM 1.2 Class Reference
45
6. REPOrTING CLASSES
The reporting classes provide a facility for issuing reports with consistent formatting. Users can configure what actions to take and what files to send output to based on
report severity, ID, or both severity and ID. Users can also filter messages based on
their verbosity settings.
The primary interface to the UVM reporting facility is the uvm_report_object from which
all uvm_components extend. The uvm_report_object delegates most tasks to its internal
uvm_report_handler. If the report handler determines the report is not filtered based
the configured verbosity setting, it sends the report to the central uvm_report_server for
formatting and processing.
Summary
Reporting Classes
The reporting classes provide a facility for issuing reports with consistent
formatting.
UVM 1.2 Class Reference
46
6.1 uvm_report_message_element_base
Base class for report message element. Defines common interface.
Contents
uvm_report_message_element_base
uvm_report_message_int_element
uvm_report_message_string_element
uvm_report_message_object_element
uvm_report_message_element_container
uvm_report_message
Base class for report message
element.
Message element class for integral
type
Message element class for string type
Message element class for object type
A container used by report message to
contain the dynamically added
elements, with APIs to add and delete
the elements.
The uvm_report_message is the basic
UVM object message class.
METHODS
get_name
virtual function string get_name()
set_name
virtual function void set_name(
string name
)
Get or set the name of the element
get_action
virtual function uvm_action get_action()
set_action
virtual function void set_action(
uvm_action action
)
Get or set the authorized action for the element
uvm_report_message_int_element
UVM 1.2 Class Reference
47
Message element class for integral type
Summary
uvm_report_message_int_element
Message element class for integral type
CLASS HIERARcHY
uvm_report_message_element_base
uvm_report_message_int_element
CLASS DEcLARATION
class uvm_report_message_int_element extends
uvm_report_message_element_base
METHODS
get_value
set_value
Get or set the value (integral type) of the element, with size
and radix
METHODS
get_value
virtual function uvm_bitstream_t get_value(
output int size,
output uvm_radix_enum radix
)
set_value
virtual function void set_value(
uvm_bitstream_t value,
int size,
uvm_radix_enum radix
)
Get or set the value (integral type) of the element, with size and radix
uvm_report_message_string_element
Message element class for string type
Summary
uvm_report_message_string_element
Message element class for string type
UVM 1.2 Class Reference
48
CLASS HIERARcHY
uvm_report_message_element_base
uvm_report_message_string_element
CLASS DEcLARATION
class uvm_report_message_string_element extends
uvm_report_message_element_base
METHODS
get_value
set_value
Get or set the value (string type) of the element
METHODS
get_value
virtual function string get_value()
set_value
virtual function void set_value(
string value
)
Get or set the value (string type) of the element
uvm_report_message_object_element
Message element class for object type
Summary
uvm_report_message_object_element
Message element class for object type
CLASS HIERARcHY
uvm_report_message_element_base
uvm_report_message_object_element
CLASS DEcLARATION
class uvm_report_message_object_element extends
uvm_report_message_element_base
METHODS
get_value
set_value
UVM 1.2 Class Reference
Get the value (object reference) of the element
Get or set the value (object reference) of the element
49
METHODS
get_value
virtual function uvm_object get_value()
Get the value (object reference) of the element
set_value
virtual function void set_value(
uvm_object value
)
Get or set the value (object reference) of the element
uvm_report_message_element_container
A container used by report message to contain the dynamically added elements, with
APIs to add and delete the elements.
Summary
uvm_report_message_element_container
A container used by report message to contain the dynamically added elements,
with APIs to add and delete the elements.
CLASS HIERARcHY
uvm_void
uvm_object
uvm_report_message_element_container
CLASS DEcLARATION
class uvm_report_message_element_container extends
uvm_object
METHODS
new
size
delete
delete_elements
get_elements
add_int
add_string
add_object
UVM 1.2 Class Reference
Create a new uvm_report_message_element_container
object
Returns the size of the container
Delete the index-th element in the container
Delete all the elements in the container
Get all the elements from the container and put them in a
queue
This method adds an integral type of the name name and
value value to the container.
This method adds a string of the name name and value
value to the message.
This method adds a uvm_object of the name name and
50
reference obj to the message.
METHODS
new
function new(
string name = "element_container"
)
Create a new uvm_report_message_element_container object
size
virtual function int size()
Returns the size of the container, i.e. the number of elements
delete
virtual function void delete(
int index
)
Delete the index-th element in the container
delete_elements
virtual function void delete_elements()
Delete all the elements in the container
get_elements
Get all the elements from the container and put them in a queue
add_int
virtual function void add_int(
string name, uvm_bitstream_t value, size, int uvm_radix_enum radix, uvm_action action = (UVM_LOG|UVM_RM_RECORD)
)
This method adds an integral type of the name name and value value to the container. The required size field indicates the size of value. The required radix field determines
how to display and record the field. The optional print/record bit is to specify whether
the element will be printed/recorded.
UVM 1.2 Class Reference
51
add_string
virtual function void add_string(
string name, string value, uvm_action action = (UVM_LOG|UVM_RM_RECORD)
)
This method adds a string of the name name and value value to the message. The
optional print/record bit is to specify whether the element will be printed/recorded.
add_object
virtual function void add_object(
string name, uvm_object obj, uvm_action action = (UVM_LOG|UVM_RM_RECORD)
)
This method adds a uvm_object of the name name and reference obj to the message. The optional print/record bit is to specify whether the element will be printed/recorded.
uvm_report_message
The uvm_report_message is the basic UVM object message class. It provides the fields
that are common to all messages. It also has a message element container and provides
the APIs necessary to add integral types, strings and uvm_objects to the container. The
report message object can be initialized with the common fields, and passes through the
whole reporting system (i.e. report object, report handler, report server, report catcher,
etc) as an object. The additional elements can be added/deleted to/from the message
object anywhere in the reporting system, and can be printed or recorded along with the
common fields.
Summary
uvm_report_message
The uvm_report_message is the basic UVM object message class.
CLASS HIERARcHY
uvm_void
uvm_object
uvm_report_message
CLASS DEcLARATION
class uvm_report_message extends uvm_object
new
new_report_message
print
UVM 1.2 Class Reference
Creates a new uvm_report_message object.
Creates a new uvm_report_message object.
The uvm_report_message implements
uvm_object::do_print() such that print method
provides UVM printer formatted output of the
message.
52
INFRASTRUcTURE
REFERENcES
get_report_object
set_report_object
get_report_handler
set_report_handler
get_report_server
set_report_server
MESSAGE FIELDS
get_severity
set_severity
get_id
set_id
get_message
set_message
get_verbosity
set_verbosity
get_filename
set_filename
get_line
set_line
get_context
set_context
get_action
set_action
get_file
set_file
get_element_container
set_report_message
MESSAGE ELEmENT APIS
add_int
add_string
add_object
Get or set the uvm_report_object that originated
the message.
Get or set the uvm_report_handler that is
responsible for checking whether the message is
enabled, should be upgraded/downgraded, etc.
Get or set the uvm_report_server that is
responsible for servicing the message’s actions.
Get or set the severity (UVM_INFO,
UVM_WARNING, UVM_ERROR or UVM_FATAL) of
the message.
Get or set the id of the message.
Get or set the user message content string.
Get or set the message threshold value.
Get or set the file from which the message
originates.
Get or set the line in the file from which the
message originates.
Get or set the optional user-supplied string that is
meant to convey the context of the message.
Get or set the action(s) that the
uvm_report_server should perform for this
message.
Get or set the file that the message is to be written
to when the message’s action is UVM_LOG.
Get the element_container of the message
Set all the common fields of the report message in
one shot.
This method adds an integral type of the name
name and value value to the message.
This method adds a string of the name name and
value value to the message.
This method adds a uvm_object of the name name
and reference obj to the message.
new
function new(
string name = "uvm_report_message"
)
Creates a new uvm_report_message object.
new_report_message
static function uvm_report_message new_report_message(
UVM 1.2 Class Reference
53
string name = "uvm_report_message"
)
Creates a new uvm_report_message object. This function is the same as new(), but
keeps the random stability.
print
virtual function void do_print(
uvm_printer printer
)
The uvm_report_message implements uvm_object::do_print() such that print method
provides UVM printer formatted output of the message. A snippet of example output is
shown here:
-------------------------------------------------------Name
Type
Size Value
-------------------------------------------------------uvm_report_message uvm_report_message @532
severity
uvm_severity
2
UVM_INFO
id
string
10
TEST_ID
message
string
12
A message...
verbosity
uvm_verbosity
32
UVM_LOW
filename
string
7
test.sv
line
integral
32
'd58
context_name
string
0
""
color
string
3
red
my_int
integral
32
'd5
my_string
string
3
foo
my_obj
my_class
@531
foo
integral
32
'd3
bar
string
8
hi there
INFRASTRUcTURE REFERENcES
get_report_object
virtual function uvm_report_object get_report_object()
set_report_object
virtual function void set_report_object(
uvm_report_object ro
)
Get or set the uvm_report_object that originated the message.
get_report_handler
virtual function uvm_report_handler get_report_handler()
set_report_handler
UVM 1.2 Class Reference
54
virtual function void set_report_handler(
uvm_report_handler rh
)
Get or set the uvm_report_handler that is responsible for checking whether the message
is enabled, should be upgraded/downgraded, etc.
get_report_server
virtual function uvm_report_server get_report_server()
set_report_server
virtual function void set_report_server(
uvm_report_server rs
)
Get or set the uvm_report_server that is responsible for servicing the message’s actions.
MESSAGE FIELDS
get_severity
virtual function uvm_severity get_severity()
set_severity
virtual function void set_severity(
uvm_severity sev
)
Get or set the severity (UVM_INFO, UVM_WARNING, UVM_ERROR or UVM_FATAL) of the
message. The value of this field is determined via the API used (`uvm_info(),
`uvm_waring(), etc.) and populated for the user.
get_id
virtual function string get_id()
set_id
virtual function void set_id(
string id
)
Get or set the id of the message. The value of this field is completely under user
discretion. Users are recommended to follow a consistent convention. Settings in the
uvm_report_handler allow various messaging controls based on this field. See
uvm_report_handler.
UVM 1.2 Class Reference
55
get_message
virtual function string get_message()
set_message
virtual function void set_message(
string msg
)
Get or set the user message content string.
get_verbosity
virtual function int get_verbosity()
set_verbosity
virtual function void set_verbosity(
int ver
)
Get or set the message threshold value. This value is compared against settings in the
uvm_report_handler to determine whether this message should be executed.
get_filename
virtual function string get_filename()
set_filename
virtual function void set_filename(
string fname
)
Get or set the file from which the message originates. This value is automatically
populated by the messaging macros.
get_line
virtual function int get_line()
set_line
virtual function void set_line(
int ln
)
UVM 1.2 Class Reference
56
Get or set the line in the file from which the message originates. This value is
automatically populate by the messaging macros.
get_context
virtual function string get_context()
set_context
virtual function void set_context(
string cn
)
Get or set the optional user-supplied string that is meant to convey the context of the
message. It can be useful in scopes that are not inherently UVM like modules,
interfaces, etc.
get_action
virtual function uvm_action get_action()
set_action
virtual function void set_action(
uvm_action act
)
Get or set the action(s) that the uvm_report_server should perform for this message. This field is populated by the uvm_report_handler during message execution flow.
get_file
virtual function UVM_FILE get_file()
set_file
virtual function void set_file(
UVM_FILE fl
)
Get or set the file that the message is to be written to when the message’s action is
UVM_LOG. This field is populated by the uvm_report_handler during message execution
flow.
get_element_container
virtual function uvm_report_message_element_container
get_element_container()
Get the element_container of the message
UVM 1.2 Class Reference
57
set_report_message
virtual function void set_report_message(
uvm_severity severity,
string id,
string message,
int verbosity,
string filename,
int line,
string context_name
)
Set all the common fields of the report message in one shot.
MESSAGE ELEmENT APIS
add_int
virtual function void add_int(
string name, uvm_bitstream_t value, int size, uvm_radix_enum radix, uvm_action action = (UVM_LOG|UVM_RM_RECORD)
)
This method adds an integral type of the name name and value value to the message. The required size field indicates the size of value. The required radix field determines
how to display and record the field. The optional print/record bit is to specify whether
the element will be printed/recorded.
add_string
virtual function void add_string(
string name, value, string uvm_action action = (UVM_LOG|UVM_RM_RECORD)
)
This method adds a string of the name name and value value to the message. The
optional print/record bit is to specify whether the element will be printed/recorded.
add_object
virtual function void add_object(
string name, uvm_object obj, uvm_action action = (UVM_LOG|UVM_RM_RECORD)
)
This method adds a uvm_object of the name name and reference obj to the message. The optional print/record bit is to specify whether the element will be printed/recorded.
UVM 1.2 Class Reference
58
6.2 uvm_report_object
The uvm_report_object provides an interface to the UVM reporting facility. Through this
interface, components issue the various messages that occur during simulation. Users
can configure what actions are taken and what file(s) are output for individual messages
from a particular component or for all messages from all components in the
environment. Defaults are applied where there is no explicit configuration.
Most methods in uvm_report_object are delegated to an internal instance of a
uvm_report_handler, which stores the reporting configuration and determines whether an
issued message should be displayed based on that configuration. Then, to display a
message, the report handler delegates the actual formatting and production of messages
to a central uvm_report_server.
A report consists of an id string, severity, verbosity level, and the textual message
itself. They may optionally include the filename and line number from which the
message came. If the verbosity level of a report is greater than the configured
maximum verbosity level of its report object, it is ignored. If a report passes the
verbosity filter in effect, the report’s action is determined. If the action includes output
to a file, the configured file descriptor(s) are determined.
Actions
can be set for (in increasing priority) severity, id, and
(severity,id) pair. They include output to the screen
UVM_DISPLAY, whether the message counters should be
incremented UVM_COUNT, and whether a $finish should
occur UVM_EXIT.
Default Actions
The following provides the default actions assigned to each
severity. These can be overridden by any of the set_*_action
methods.
UVM_INFO UVM_WARNING UVM_ERROR UVM_FATAL -
UVM_DISPLAY
UVM_DISPLAY
UVM_DISPLAY | UVM_COUNT
UVM_DISPLAY | UVM_EXIT
File descriptors
These can be set by (in increasing priority) default,
severity level, an id, or (severity,id) pair. File descriptors
are standard SystemVerilog file descriptors; they may
refer to more than one file. It is the user’s responsibility
to open and close them.
Default file handle
The default file handle is 0, which means that reports are
not sent to a file even if a UVM_LOG attribute is set in the
action associated with the report. This can be overridden
by any of the set_*_file methods.
Summary
uvm_report_object
The uvm_report_object provides an interface to the UVM reporting facility.
CLAss HIERARchY
uvm_void
uvm_object
UVM 1.2 Class Reference
59
uvm_report_object
CLAss DEcLARATION
class uvm_report_object extends uvm_object
new
REPORTING
uvm_get_report_object
uvm_report_enabled
uvm_report
uvm_report_info
uvm_report_warning
uvm_report_error
uvm_report_fatal
uvm_process_report_message
VERBOsITY CONFIGURATION
get_report_verbosity_level
get_report_max_verbosity_level
set_report_verbosity_level
set_report_id_verbosity
set_report_severity_id_verbosity
AcTION CONFIGURATION
get_report_action
set_report_severity_action
set_report_id_action
set_report_severity_id_action
FILE CONFIGURATION
get_report_file_handle
set_report_default_file
set_report_id_file
set_report_severity_file
set_report_severity_id_file
OvERRIdE CONFIGURATION
set_report_severity_override
set_report_severity_id_override
REPORT HANdLER CONFIGURATION
set_report_handler
get_report_handler
reset_report_handler
UVM 1.2 Class Reference
Creates a new report object with the given
name.
Returns the nearest uvm_report_object
when called.
Returns 1 if the configured verbosity for
this severity/id is greater than or equal to
verbosity else returns 0.
These are the primary reporting methods
in the UVM.
This method takes a preformed
uvm_report_message, populates it with
the report object and passes it to the
report handler for processing.
Gets the verbosity level in effect for this
object.
Gets the maximum verbosity level in
effect for this report object.
This method sets the maximum verbosity
level for reports for this component.
These methods associate the specified
verbosity threshold with reports of the
given severity, id, or severity-id pair.
Gets the action associated with reports
having the given severity and id.
These methods associate the specified
action or actions with reports of the given
severity, id, or severity-id pair.
Gets the file descriptor associated with
reports having the given severity and id.
These methods configure the report
handler to direct some or all of its output
to the given file descriptor.
These methods provide the ability to
upgrade or downgrade a message in
terms of severity given severity and id.
Sets the report handler, overwriting the
default instance.
Returns the underlying report handler to
which most reporting tasks are
delegated.
Resets the underlying report handler to
its default settings.
60
new
function new(
string name = ""
)
Creates a new report object with the given name. This method also creates a new
uvm_report_handler object to which most tasks are delegated.
REPORTING
uvm_get_report_object
function uvm_report_object uvm_get_report_object()
Returns the nearest uvm_report_object when called. From inside a uvm_component, the
method simply returns this.
See also the global version of uvm_get_report_object.
uvm_report_enabled
function int uvm_report_enabled(
int verbosity, uvm_severity severity = UVM_INFO,
string id
= ""
)
Returns 1 if the configured verbosity for this severity/id is greater than or equal to
verbosity else returns 0.
See also get_report_verbosity_level and the global version of uvm_report_enabled.
uvm_report
virtual function void uvm_report(
uvm_severity severity,
id,
string string message,
verbosity
int string int string bit )
= (severity ==
uvm_severity'(UVM_ERROR)) ?
UVM_LOW : (severity ==
uvm_severity'(UVM_FATAL)) ?
UVM_NONE : UVM_MEDIUM,
filename
= "",
line
= 0,
context_name
= "",
report_enabled_checked = 0
uvm_report_info
virtual function void uvm_report_info(
UVM 1.2 Class Reference
61
string id,
string message,
verbosity
= UVM_MEDIUM,
int string filename
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
uvm_report_warning
virtual function void uvm_report_warning(
string id,
string message,
int verbosity
= UVM_MEDIUM,
string filename
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
uvm_report_error
virtual function void uvm_report_error(
string id,
string message,
int verbosity
= UVM_LOW,
string filename
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
uvm_report_fatal
virtual function void uvm_report_fatal(
string id,
string message,
int verbosity
= UVM_NONE,
string filename
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
These are the primary reporting methods in the UVM. Using these instead of $display
and other ad hoc approaches ensures consistent output and central control over where
output is directed and any actions that result. All reporting methods have the same
arguments, although each has a different default verbosity:
id
a unique id for the report or report group that can
be used for identification and therefore targeted
filtering. You can configure an individual report’s
actions and output file(s) using this id string.
message
the message body, preformatted if necessary to a
single string.
verbosity
the verbosity of the message, indicating its relative
importance. If this number is less than or equal to
the effective verbosity level, see
set_report_verbosity_level, then the report is issued,
subject to the configured action and file descriptor
settings. Verbosity is ignored for warnings, errors,
UVM 1.2 Class Reference
62
and fatals. However, if a warning, error or fatal is
demoted to an info message using the
uvm_report_catcher, then the verbosity is taken
into account.
filename/line
(Optional) The location from which the report was
issued. Use the predefined macros, `__FILE__ and
`__LINE__. If specified, it is displayed in the
output.
context_name
(Optional) The string context from where the
message is originating. This can be the %m of a
module, a specific method, etc.
report_enabled_checked
(Optional) This bit indicates whether the currently
provided message has been checked as to whether
the message should be processed. If it hasn’t been
checked, it will be checked inside the uvm_report
function.
uvm_process_report_message
virtual function void uvm_process_report_message(
uvm_report_message report_message
)
This method takes a preformed uvm_report_message, populates it with the report object
and passes it to the report handler for processing. It is expected to be checked for
verbosity and populated.
VERBOsITY CONFIGURATION
get_report_verbosity_level
function int get_report_verbosity_level(
uvm_severity severity = UVM_INFO,
string id
= ""
)
Gets the verbosity level in effect for this object. Reports issued with verbosity greater
than this will be filtered out. The severity and tag arguments check if the verbosity level
has been modified for specific severity/tag combinations.
get_report_max_verbosity_level
function int get_report_max_verbosity_level()
Gets the maximum verbosity level in effect for this report object. Any report from this
component whose verbosity exceeds this maximum will be ignored.
set_report_verbosity_level
function void set_report_verbosity_level (
int verbosity_level
UVM 1.2 Class Reference
63
)
This method sets the maximum verbosity level for reports for this component. Any
report from this component whose verbosity exceeds this maximum will be ignored.
set_report_id_verbosity
function void set_report_id_verbosity (
string id,
int verbosity
)
set_report_severity_id_verbosity
function void set_report_severity_id_verbosity (
uvm_severity severity,
string id,
int verbosity
)
These methods associate the specified verbosity threshold with reports of the given
severity, id, or severity-id pair. This threshold is compared with the verbosity originally
assigned to the report to decide whether it gets processed. A verbosity threshold
associated with a particular severity-id pair takes precedence over a verbosity threshold
associated with id, which takes precedence over a verbosity threshold associated with a
severity.
The verbosity argument can be any integer, but is most commonly a predefined
uvm_verbosity value, UVM_NONE, UVM_LOW, UVM_MEDIUM, UVM_HIGH, UVM_FULL.
AcTION CONFIGURATION
get_report_action
function int get_report_action(
uvm_severity severity,
string id
)
Gets the action associated with reports having the given severity and id.
set_report_severity_action
function void set_report_severity_action (
uvm_severity severity,
uvm_action action
)
set_report_id_action
function void set_report_id_action (
string id,
uvm_action action
)
UVM 1.2 Class Reference
64
set_report_severity_id_action
function void set_report_severity_id_action (
uvm_severity severity,
string id,
uvm_action action
)
These methods associate the specified action or actions with reports of the given
severity, id, or severity-id pair. An action associated with a particular severity-id pair
takes precedence over an action associated with id, which takes precedence over an
action associated with a severity.
The action argument can take the value UVM_NO_ACTION, or it can be a bitwise OR of
any combination of UVM_DISPLAY, UVM_LOG, UVM_COUNT, UVM_STOP, UVM_EXIT, and
UVM_CALL_HOOK.
FILE CONFIGURATION
get_report_file_handle
function int get_report_file_handle(
uvm_severity severity,
string id
)
Gets the file descriptor associated with reports having the given severity and id.
set_report_default_file
function void set_report_default_file (
UVM_FILE file
)
set_report_id_file
function void set_report_id_file (
string id,
UVM_FILE file
)
set_report_severity_file
function void set_report_severity_file (
uvm_severity severity,
UVM_FILE file
)
set_report_severity_id_file
UVM 1.2 Class Reference
65
function void set_report_severity_id_file (
uvm_severity severity,
string id,
UVM_FILE file
)
These methods configure the report handler to direct some or all of its output to the
given file descriptor. The file argument must be a multi-channel descriptor (mcd) or file
id compatible with $fdisplay.
A FILE descriptor can be associated with reports of the given severity, id, or severity-id
pair. A FILE associated with a particular severity-id pair takes precedence over a FILE
associated with id, which take precedence over an a FILE associated with a severity,
which takes precedence over the default FILE descriptor.
When a report is issued and its associated action has the UVM_LOG bit set, the report
will be sent to its associated FILE descriptor. The user is responsible for opening and
closing these files.
OvERRIdE CONFIGURATION
set_report_severity_override
function void set_report_severity_override(
uvm_severity cur_severity,
uvm_severity new_severity
)
set_report_severity_id_override
function void set_report_severity_id_override(
uvm_severity cur_severity,
string id,
uvm_severity new_severity
)
These methods provide the ability to upgrade or downgrade a message in terms of
severity given severity and id. An upgrade or downgrade for a specific id takes
precedence over an upgrade or downgrade associated with a severity.
REPORT HANdLER CONFIGURATION
set_report_handler
function void set_report_handler(
uvm_report_handler handler
)
Sets the report handler, overwriting the default instance. This allows more than one
component to share the same report handler.
get_report_handler
UVM 1.2 Class Reference
66
function uvm_report_handler get_report_handler()
Returns the underlying report handler to which most reporting tasks are delegated.
reset_report_handler
function void reset_report_handler
Resets the underlying report handler to its default settings. This clears any settings
made with the set_report_* methods (see below).
UVM 1.2 Class Reference
67
6.3 uvm_report_handler
The uvm_report_handler is the class to which most methods in uvm_report_object
delegate. It stores the maximum verbosity, actions, and files that affect the way reports
are handled.
The report handler is not intended for direct use. See uvm_report_object for information
on the UVM reporting mechanism.
The relationship between uvm_report_object (a base class for uvm_component) and
uvm_report_handler is typically one to one, but it can be many to one if several
uvm_report_objects are configured to use the same uvm_report_handler_object. See
uvm_report_object::set_report_handler.
The relationship between uvm_report_handler and uvm_report_server is many to one.
Summary
uvm_report_handler
The uvm_report_handler is the class to which most methods in
uvm_report_object delegate.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_handler
CLAss DEcLARATION
class uvm_report_handler extends uvm_object
new
print
MEssAGE PROcEssING
process_report_message
CONVENIENcE METhOds
format_action
Creates and initializes a new uvm_report_handler
object.
The uvm_report_handler implements the
uvm_object::do_print() such that print method
provides UVM printer formatted output of the
current configuration.
This is the common handler method used by the
four core reporting methods (e.g.
Returns a string representation of the action,
e.g., “DISPLAY”.
new
function new(
string name = "uvm_report_handler"
)
Creates and initializes a new uvm_report_handler object.
print
UVM 1.2 Class Reference
68
virtual function void do_print (
uvm_printer printer
)
The uvm_report_handler implements the uvm_object::do_print() such that print method
provides UVM printer formatted output of the current configuration. A snippet of
example output is shown here:
uvm_test_top
max_verbosity_level
id_verbosities
[ID1]
severity_id_verbosities
[UVM_INFO:ID4]
id_actions
[ACT_ID]
severity_actions
[UVM_INFO]
[UVM_WARNING]
COUNT
[UVM_ERROR]
[UVM_FATAL]
default_file_handle
uvm_report_handler
uvm_verbosity
uvm_pool
uvm_verbosity
array
int
uvm_pool
uvm_action
array
uvm_action
uvm_action
uvm_action
uvm_action
int
32
3
32
4
32
2
32
4
32
32
32
32
32
@555
UVM_FULL
UVM_LOW
501
DISPLAY LOG COUNT
DISPLAY
DISPLAY RM_RECORD
DISPLAY COUNT
DISPLAY EXIT
'h1
MEssAGE PROcEssING
process_report_message
virtual function void process_report_message(
uvm_report_message report_message
)
This is the common handler method used by the four core reporting methods (e.g. uvm_report_error) in uvm_report_object.
CONVENIENcE METhOds
format_action
static function string format_action(
uvm_action action
)
Returns a string representation of the action, e.g., “DISPLAY”.
UVM 1.2 Class Reference
69
6.4 UVM Report Server
This page covers the classes that define the UVM report server facility.
Contents
UVM Report Server
This page covers the classes that define the UVM
report server facility.
uvm_report_server
uvm_report_server is a global server that processes
all of the reports generated by a
uvm_report_handler.
Default implementation of the UVM report server.
uvm_default_report_server
uvm_report_server
uvm_report_server is a global server that processes all of the reports generated by a
uvm_report_handler.
The uvm_report_server is an abstract class which declares many of its methods as pure
virtual. The UVM uses the uvm_default_report_server class as its default report server
implementation.
Summary
uvm_report_server
uvm_report_server is a global server that processes all of the reports generated
by a uvm_report_handler.
METHODs
set_max_quit_count
get_max_quit_count
set_quit_count
get_quit_count
set_severity_count
get_severity_count
set_id_count
get_id_count
get_id_set
get_severity_set
set_message_database
get_message_database
do_copy
UVM 1.2 Class Reference
count is the maximum number of UVM_QUIT
actions the uvm_report_server will tolerate
before invoking client.die().
returns the currently configured max quit count
sets the current number of UVM_QUIT actions
already passed through this uvm_report_server
returns the current number of UVM_QUIT
actions already passed through this server
sets the count of already passed messages with
severity severity to count
returns the count of already passed messages
with severity severity
sets the count of already passed messages with
id to count
returns the count of already passed messages
with id
returns the set of id’s already used by this
uvm_report_server
returns the set of severities already used by this
uvm_report_server
sets the uvm_tr_database used for recording
messages
returns the uvm_tr_database used for recording
messages
copies all message statistic severity,id counts to
70
execute_report_message
compose_report_message
report_summarize
set_server
get_server
the destination uvm_report_server the copy is
cummulative (only items from the source are
transferred, already existing entries are not
deleted, existing entries/counts are overridden
when they exist in the source set)
Processes the provided message per the actions
contained within.
Constructs the actual string sent to the file or
command line from the severity, component
name, report id, and the message itself.
Outputs statistical information on the reports
issued by this central report server.
Sets the global report server to use for
reporting.
Gets the global report server used for reporting.
METHODs
set_max_quit_count
pure virtual function void set_max_quit_count(
int count,
bit overridable = 1
)
count is the maximum number of UVM_QUIT actions the uvm_report_server will tolerate
before invoking client.die(). when overridable = 0 is passed, the set quit count cannot be
changed again
get_max_quit_count
pure virtual function int get_max_quit_count()
returns the currently configured max quit count
set_quit_count
pure virtual function void set_quit_count(
int quit_count
)
sets the current number of UVM_QUIT actions already passed through this
uvm_report_server
get_quit_count
pure virtual function int get_quit_count()
returns the current number of UVM_QUIT actions already passed through this server
set_severity_count
UVM 1.2 Class Reference
71
pure virtual function void set_severity_count(
uvm_severity severity,
int count
)
sets the count of already passed messages with severity severity to count
get_severity_count
pure virtual function int get_severity_count(
uvm_severity severity
)
returns the count of already passed messages with severity severity
set_id_count
pure virtual function void set_id_count(
string id,
int count
)
sets the count of already passed messages with id to count
get_id_count
pure virtual function int get_id_count(
string id
)
returns the count of already passed messages with id
get_id_set
pure virtual function void get_id_set(
output string q[$]
)
returns the set of id’s already used by this uvm_report_server
get_severity_set
pure virtual function void get_severity_set(
output uvm_severity q[$]
)
returns the set of severities already used by this uvm_report_server
set_message_database
pure virtual function void set_message_database(
uvm_tr_database database
)
UVM 1.2 Class Reference
72
sets the uvm_tr_database used for recording messages
get_message_database
pure virtual function uvm_tr_database get_message_database()
returns the uvm_tr_database used for recording messages
do_copy
function void do_copy (
uvm_object rhs
)
copies all message statistic severity,id counts to the destination uvm_report_server the
copy is cummulative (only items from the source are transferred, already existing entries
are not deleted, existing entries/counts are overridden when they exist in the source set)
execute_report_message
pure virtual function void execute_report_message(
uvm_report_message report_message,
string composed_message
)
Processes the provided message per the actions contained within.
Expert users can overload this method to customize action processing.
compose_report_message
pure virtual function string compose_report_message(
uvm_report_message report_message,
report_object_name = ""
string )
Constructs the actual string sent to the file or command line from the severity,
component name, report id, and the message itself.
Expert users can overload this method to customize report formatting.
report_summarize
pure virtual function void report_summarize(
UVM_FILE file = 0
)
Outputs statistical information on the reports issued by this central report server. This
information will be sent to the command line if file is 0, or to the file descriptor file if it
is not 0.
The run_test method in uvm_top calls this method.
UVM 1.2 Class Reference
73
set_server
static function void set_server(
uvm_report_server server
)
Sets the global report server to use for reporting.
This method is provided as a convenience wrapper around setting the report server via
the uvm_coreservice_t::set_report_server method.
In addition to setting the server this also copies the severity/id counts from the current
report_server to the new one
// Using the uvm_coreservice_t:
uvm_coreservice_t cs;
cs = uvm_coreservice_t::get();
your_server.copy(cs.get_report_server());
cs.set_report_server(your_server);
// Not using the uvm_coreservice_t:
uvm_report_server::set_server(your_server);
get_server
static function uvm_report_server get_server()
Gets the global report server used for reporting.
This method is provided as a convenience wrapper around retrieving the report server via
the uvm_coreservice_t::get_report_server method.
// Using the uvm_coreservice_t:
uvm_coreservice_t cs;
uvm_report_server rs;
cs = uvm_coreservice_t::get();
rs = cs.get_report_server();
// Not using the uvm_coreservice_t:
uvm_report_server rs;
rs = uvm_report_server::get_server();
uvm_default_report_server
Default implementation of the UVM report server.
Summary
uvm_default_report_server
Default implementation of the UVM report server.
CLAss HIErArcHY
uvm_report_server
UVM 1.2 Class Reference
74
uvm_default_report_server
CLAss DEcLArATION
class uvm_default_report_server extends uvm_report_server
enable_report_id_count_summary
record_all_messages
show_verbosity
show_terminator
new
print
QuIT COuNT
get_max_quit_count
set_max_quit_count
get_quit_count
set_quit_count
incr_quit_count
reset_quit_count
is_quit_count_reached
SEvErITY COuNT
get_severity_count
set_severity_count
incr_severity_count
reset_severity_counts
COuNT
get_id_count
set_id_count
incr_id_count
A flag to enable report count summary for
each ID
A flag to force recording of all messages
(add UVM_RM_RECORD action)
A flag to include verbosity in the
messages, e.g.
A flag to add a terminator in the
messages, e.g.
Creates an instance of the class.
The uvm_report_server implements the
uvm_object::do_print() such that print
method provides UVM printer formatted
output of the current configuration.
Get or set the maximum number of
COUNT actions that can be tolerated
before a UVM_EXIT action is taken.
Set, get, increment, or reset to 0 the quit
count, i.e., the number of COUNT actions
issued.
If is_quit_count_reached returns 1, then
the quit counter has reached the
maximum.
Set, get, or increment the counter for the
given severity, or reset all severity
counters to 0.
ID
mEssAGE rEcOrDING
set_message_database
get_message_database
MEssAGE PrOcEssING
execute_report_message
compose_report_message
report_summarize
UVM 1.2 Class Reference
Set, get, or increment the counter for
reports with the given id.
The uvm_default_report_server will record
messages into the message database,
using one transaction per message, and
one stream per report object/handler pair.
sets the uvm_tr_database used for
recording messages
returns the uvm_tr_database used for
recording messages
Processes the provided message per the
actions contained within.
Constructs the actual string sent to the
file or command line from the severity,
component name, report id, and the
message itself.
Outputs statistical information on the
reports issued by this central report
server.
75
enable_report_id_count_summary
bit enable_report_id_count_summary=1
A flag to enable report count summary for each ID
record_all_messages
bit record_all_messages = 0
A flag to force recording of all messages (add UVM_RM_RECORD action)
show_verbosity
bit show_verbosity = 0
A flag to include verbosity in the messages, e.g.
”UVM_INFO(UVM_MEDIUM) file.v(3) @ 60: reporter [ID0] Message 0”
show_terminator
bit show_terminator = 0
A flag to add a terminator in the messages, e.g.
”UVM_INFO file.v(3) @ 60: reporter [ID0] Message 0 -UVM_INFO”
new
function new(
string name = "uvm_report_server"
)
Creates an instance of the class.
print
The uvm_report_server implements the uvm_object::do_print() such that print method
provides UVM printer formatted output of the current configuration. A snippet of
example output is shown here:
uvm_report_server
quit_count
max_quit_count
max_quit_overridable
severity_count
[UVM_INFO]
[UVM_WARNING]
[UVM_ERROR]
[UVM_FATAL]
id_count
[ID1]
[ID2]
[RNTST]
enable_report_id_count_summary
UVM 1.2 Class Reference
uvm_report_server
int
int
bit
severity counts
integral
integral
integral
integral
id counts
integral
integral
integral
bit
32
32
1
4
32
32
32
32
4
32
32
32
1
@13
'd0
'd5
'b1
'd4
'd2
'd50
'd10
'd1
'd2
'd1
'b1
76
record_all_messages
show_verbosity
show_terminator
bit
bit
bit
1
1
1
`b0
`b0
`b0
QuIT COuNT
get_max_quit_count
function int get_max_quit_count()
set_max_quit_count
function void set_max_quit_count(
int count,
bit overridable = 1
)
Get or set the maximum number of COUNT actions that can be tolerated before a
UVM_EXIT action is taken. The default is 0, which specifies no maximum.
get_quit_count
function int get_quit_count()
set_quit_count
function void set_quit_count(
int quit_count
)
incr_quit_count
function void incr_quit_count()
reset_quit_count
function void reset_quit_count()
Set, get, increment, or reset to 0 the quit count, i.e., the number of COUNT actions
issued.
is_quit_count_reached
function bit is_quit_count_reached()
If is_quit_count_reached returns 1, then the quit counter has reached the maximum.
UVM 1.2 Class Reference
77
SEvErITY COuNT
get_severity_count
function int get_severity_count(
uvm_severity severity
)
set_severity_count
function void set_severity_count(
uvm_severity severity,
int count
)
incr_severity_count
function void incr_severity_count(
uvm_severity severity
)
reset_severity_counts
function void reset_severity_counts()
Set, get, or increment the counter for the given severity, or reset all severity counters to
0.
ID
COuNT
get_id_count
function int get_id_count(
string id
)
set_id_count
function void set_id_count(
string id,
int count
)
incr_id_count
function void incr_id_count(
UVM 1.2 Class Reference
78
string id
)
Set, get, or increment the counter for reports with the given id.
mEssAGE rEcOrDING
The uvm_default_report_server will record messages into the message database, using
one transaction per message, and one stream per report object/handler pair.
set_message_database
virtual function void set_message_database(
uvm_tr_database database
)
sets the uvm_tr_database used for recording messages
get_message_database
virtual function uvm_tr_database get_message_database()
returns the uvm_tr_database used for recording messages
MEssAGE PrOcEssING
execute_report_message
virtual function void execute_report_message(
uvm_report_message report_message,
string composed_message
)
Processes the provided message per the actions contained within.
Expert users can overload this method to customize action processing.
compose_report_message
virtual function string compose_report_message(
uvm_report_message report_message,
report_object_name = ""
string )
Constructs the actual string sent to the file or command line from the severity,
component name, report id, and the message itself.
Expert users can overload this method to customize report formatting.
report_summarize
UVM 1.2 Class Reference
79
virtual function void report_summarize(
UVM_FILE file = 0
)
Outputs statistical information on the reports issued by this central report server. This
information will be sent to the command line if file is 0, or to the file descriptor file if it
is not 0.
The run_test method in uvm_top calls this method.
UVM 1.2 Class Reference
80
6.5 uvm_report_catcher
The uvm_report_catcher is used to catch messages issued by the uvm report server. Catchers are uvm_callbacks#(uvm_report_object,uvm_report_catcher) objects, so all
facilities in the uvm_callback and uvm_callbacks#(T,CB) classes are available for
registering catchers and controlling catcher state. The
uvm_callbacks#(uvm_report_object,uvm_report_catcher) class is aliased to
uvm_report_cb to make it easier to use. Multiple report catchers can be registered with
a report object. The catchers can be registered as default catchers which catch all
reports on all uvm_report_object reporters, or catchers can be attached to specific report
objects (i.e. components).
User extensions of uvm_report_catcher must implement the catch method in which the
action to be taken on catching the report is specified. The catch method can return
CAUGHT, in which case further processing of the report is immediately stopped, or return
THROW in which case the (possibly modified) report is passed on to other registered
catchers. The catchers are processed in the order in which they are registered.
On catching a report, the catch method can modify the severity, id, action, verbosity or
the report string itself before the report is finally issued by the report server. The report
can be immediately issued from within the catcher class by calling the issue method.
The catcher maintains a count of all reports with FATAL,ERROR or WARNING severity and
a count of all reports with FATAL, ERROR or WARNING severity whose severity was
lowered. These statistics are reported in the summary of the uvm_report_server.
This example shows the basic concept of creating a report catching callback and
attaching it to all messages that get emitted:
class my_error_demoter extends uvm_report_catcher;
function new(string name="my_error_demoter");
super.new(name);
endfunction
//This example demotes "MY_ID" errors to an info message
function action_e catch();
if(get_severity() == UVM_ERROR && get_id() == "MY_ID")
set_severity(UVM_INFO);
return THROW;
endfunction
endclass
my_error_demoter demoter = new;
initial begin
// Catchers are callbacks on report objects (components are report
// objects, so catchers can be attached to components).
// To affect all reporters, use ~null~ for the object
uvm_report_cb::add(null, demoter);
// To affect some specific object use the specific reporter
uvm_report_cb::add(mytest.myenv.myagent.mydriver, demoter);
// To affect some set of components (any "*driver" under mytest.myenv)
// using the component name
uvm_report_cb::add_by_name("*driver", demoter, mytest.myenv);
end
Summary
uvm_report_catcher
The uvm_report_catcher is used to catch messages issued by the uvm report
server.
CLAss HIERARchY
UVM 1.2 Class Reference
81
uvm_void
uvm_object
uvm_callback
uvm_report_catcher
CLAss DEcLARATION
virtual class uvm_report_catcher extends uvm_callback
new
CURRENT MEssAGE STATE
get_client
get_severity
get_context
get_verbosity
get_id
get_message
get_action
get_fname
get_line
get_element_container
ChANGE MEssAGE STATE
set_severity
set_verbosity
set_id
set_message
set_action
set_context
add_int
add_string
add_object
DEBUG
get_report_catcher
print_catcher
CALLBAcK INTERFAcE
catch
REPORTING
uvm_report_fatal
uvm_report_error
uvm_report_warning
uvm_report_info
uvm_report
issue
summarize
UVM 1.2 Class Reference
Create a new report catcher.
Returns the uvm_report_object that has generated
the message that is currently being processed.
Returns the uvm_severity of the message that is
currently being processed.
Returns the context name of the message that is
currently being processed.
Returns the verbosity of the message that is
currently being processed.
Returns the string id of the message that is
currently being processed.
Returns the string message of the message that is
currently being processed.
Returns the uvm_action of the message that is
currently being processed.
Returns the file name of the message.
Returns the line number of the message.
Returns the element container of the message.
Change the severity of the message to severity.
Change the verbosity of the message to verbosity.
Change the id of the message to id.
Change the text of the message to message.
Change the action of the message to action.
Change the context of the message to context_str.
Add an integral type of the name name and value
value to the message.
Adds a string of the name name and value value to
the message.
Adds a uvm_object of the name name and
reference obj to the message.
Returns the first report catcher that has name.
Prints information about all of the report catchers
that are registered.
This is the method that is called for each registered
report catcher.
Issues a fatal message using the current message’s
report object.
Issues an error message using the current
message’s report object.
Issues a warning message using the current
message’s report object.
Issues a info message using the current message’s
report object.
Issues a message using the current message’s
report object.
Immediately issues the message which is currently
being processed.
This function is called automatically by
uvm_report_server::report_summarize().
82
new
function new(
string name = "uvm_report_catcher"
)
Create a new report catcher. The name argument is optional, but should generally be
provided to aid in debugging.
CURRENT MEssAGE STATE
get_client
function uvm_report_object get_client()
Returns the uvm_report_object that has generated the message that is currently being
processed.
get_severity
function uvm_severity get_severity()
Returns the uvm_severity of the message that is currently being processed. If the
severity was modified by a previously executed catcher object (which re-threw the
message), then the returned severity is the modified value.
get_context
function string get_context()
Returns the context name of the message that is currently being processed. This is
typically the full hierarchical name of the component that issued the message. However,
if user-defined context is set from a uvm_report_message, the user-defined context will
be returned.
get_verbosity
function int get_verbosity()
Returns the verbosity of the message that is currently being processed. If the verbosity
was modified by a previously executed catcher (which re-threw the message), then the
returned verbosity is the modified value.
get_id
function string get_id()
UVM 1.2 Class Reference
83
Returns the string id of the message that is currently being processed. If the id was
modified by a previously executed catcher (which re-threw the message), then the
returned id is the modified value.
get_message
function string get_message()
Returns the string message of the message that is currently being processed. If the
message was modified by a previously executed catcher (which re-threw the message),
then the returned message is the modified value.
get_action
function uvm_action get_action()
Returns the uvm_action of the message that is currently being processed. If the action
was modified by a previously executed catcher (which re-threw the message), then the
returned action is the modified value.
get_fname
function string get_fname()
Returns the file name of the message.
get_line
function int get_line()
Returns the line number of the message.
get_element_container
function uvm_report_message_element_container get_element_container()
Returns the element container of the message.
ChANGE MEssAGE STATE
set_severity
protected function void set_severity(
uvm_severity severity
)
Change the severity of the message to severity. Any other report catchers will see the
modified value.
UVM 1.2 Class Reference
84
set_verbosity
protected function void set_verbosity(
int verbosity
)
Change the verbosity of the message to verbosity. Any other report catchers will see
the modified value.
set_id
protected function void set_id(
string id
)
Change the id of the message to id. Any other report catchers will see the modified
value.
set_message
protected function void set_message(
string message
)
Change the text of the message to message. Any other report catchers will see the
modified value.
set_action
protected function void set_action(
uvm_action action
)
Change the action of the message to action. Any other report catchers will see the
modified value.
set_context
protected function void set_context(
string context_str
)
Change the context of the message to context_str. Any other report catchers will see
the modified value.
add_int
protected function void add_int(
string name, uvm_bitstream_t value, size, int uvm_radix_enum radix, uvm_action action = (UVM_LOG|UVM_RM_RECORD)
)
UVM 1.2 Class Reference
85
Add an integral type of the name name and value value to the message. The required
size field indicates the size of value. The required radix field determines how to display
and record the field. Any other report catchers will see the newly added element.
add_string
protected function void add_string(
string name, string value, uvm_action action = (UVM_LOG|UVM_RM_RECORD)
)
Adds a string of the name name and value value to the message. Any other report
catchers will see the newly added element.
add_object
protected function void add_object(
string name, uvm_object obj, uvm_action action = (UVM_LOG|UVM_RM_RECORD)
)
Adds a uvm_object of the name name and reference obj to the message. Any other
report catchers will see the newly added element.
DEBUG
get_report_catcher
static function uvm_report_catcher get_report_catcher(
string name
)
Returns the first report catcher that has name.
print_catcher
static function void print_catcher(
UVM_FILE file = 0
)
Prints information about all of the report catchers that are registered. For finer grained
detail, the uvm_callbacks #(T,CB)::display method can be used by calling
uvm_report_cb::display(uvm_report_object).
CALLBAcK INTERFAcE
catch
UVM 1.2 Class Reference
86
pure virtual function action_e catch()
This is the method that is called for each registered report catcher. There are no
arguments to this function. The Current Message State interface methods can be used to
access information about the current message being processed.
REPORTING
uvm_report_fatal
protected function void uvm_report_fatal(
string id,
string message,
int verbosity,
= "",
string fname
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
Issues a fatal message using the current message’s report object. This message will
bypass any message catching callbacks.
uvm_report_error
protected function void uvm_report_error(
string id,
string message,
int verbosity,
= "",
string fname
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
Issues an error message using the current message’s report object. This message will
bypass any message catching callbacks.
uvm_report_warning
protected function void uvm_report_warning(
string id,
string message,
int verbosity,
= "",
string fname
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
Issues a warning message using the current message’s report object. This message will
bypass any message catching callbacks.
uvm_report_info
protected function void uvm_report_info(
string id,
string message,
UVM 1.2 Class Reference
87
int verbosity,
string fname
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
Issues a info message using the current message’s report object. This message will
bypass any message catching callbacks.
uvm_report
protected function void uvm_report(
uvm_severity severity,
string id,
string message,
verbosity,
int string fname
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
Issues a message using the current message’s report object. This message will bypass
any message catching callbacks.
issue
protected function void issue()
Immediately issues the message which is currently being processed. This is useful if the
message is being CAUGHT but should still be emitted.
Issuing a message will update the report_server stats, possibly multiple times if the
message is not CAUGHT.
summarize
static function void summarize()
This function is called automatically by uvm_report_server::report_summarize(). It prints
the statistics for the active catchers.
UVM 1.2 Class Reference
88
7. TRANSACtION RECORDING CLASSES
The recording classes provide a facility to record transactions into a database using a
consistent API. Users can configure what gets sent to the backend database, without
knowing exactly how the connection to that database is established.
The primary interface to the UVM recording facility is the uvm_recorder class, which
serves as a reference to the transaction in the database, as well as the policy which is
used to record information into the database.
The UVM provides a default implementation of the recording API, which creates textual
logs. This is primarily intended to be used as an example of how to create a recording
implementation without the user needing to have tool and/or vendor specific code in their
testbench.
Summary
Transaction Recording Classes
The recording classes provide a facility to record transactions into a database
using a consistent API.
UVM 1.2 Class Reference
89
7.1 Transaction Recording Databases
The UVM “Transaction Recording Database” classes are an abstract representation of the
backend tool which is recording information for the user. Usually this tool would be
dumping information such that it can be viewed with the waves of the DUT.
Contents
Transaction
Recording
Databases
The UVM “Transaction Recording Database” classes are
an abstract representation of the backend tool which is
recording information for the user.
uvm_tr_database
The uvm_tr_database class is intended to hide the
underlying database implementation from the end user,
as these details are often vendor or tool-specific.
The uvm_text_tr_database is the default implementation
for the uvm_tr_database.
uvm_text_tr_database
uvm_tr_database
The uvm_tr_database class is intended to hide the underlying database implementation
from the end user, as these details are often vendor or tool-specific.
The uvm_tr_database class is pure virtual, and must be extended with an
implementation. A default text-based implementation is provided via the
uvm_text_tr_database class.
Summary
uvm_tr_database
The uvm_tr_database class is intended to hide the underlying database
implementation from the end user, as these details are often vendor or toolspecific.
CLAss HIErArchY
uvm_void
uvm_object
uvm_tr_database
CLAss DEcLArAtION
virtual class uvm_tr_database extends uvm_object
new
DAtABAsE API
open_db
close_db
is_open
StrEAM API
open_stream
get_streams
UVM 1.2 Class Reference
Constructor
Open the backend connection to the database.
Closes the backend connection to the database.
Returns the open/closed status of the database.
Provides a reference to a stream within the
database.
Provides a queue of all streams within the
90
database.
LINK API
establish_link
IMpLEMENtAtION AGNOstIc
API
do_open_db
do_close_db
do_open_stream
do_establish_link
Establishes a link between two elements in the
database
Backend
Backend
Backend
Backend
implementation
implementation
implementation
implementation
of
of
of
of
open_db
close_db
open_stream
establish_link
new
function new(
string name = "unnamed-uvm_tr_database"
)
Constructor
Parameters
name
Instance name
DAtABAsE API
open_db
function bit open_db()
Open the backend connection to the database.
If the database is already open, then this method will return 1.
Otherwise, the method will call do_open_db, and return the result.
close_db
function bit close_db()
Closes the backend connection to the database.
Closing a database implicitly closes and frees all uvm_tr_streams within the database.
If the database is already closed, then this method will return 1.
Otherwise, this method will trigger a do_close_db call, and return the result.
is_open
function bit is_open()
Returns the open/closed status of the database.
UVM 1.2 Class Reference
91
This method returns 1 if the database has been successfully opened, but not yet closed.
StrEAM API
open_stream
function uvm_tr_stream open_stream(
string name,
string scope
= "",
string type_name = ""
)
Provides a reference to a stream within the database.
Parameters
name
A string name for the stream. This is the name associated with
the stream in the database.
scope
An optional scope for the stream.
type_name
An optional name describing the type of records which will be
created in this stream.
The method returns a reference to a uvm_tr_stream object if successful, null otherwise.
This method will trigger a do_open_stream call, and if a non null stream is returned,
then uvm_tr_stream::do_open will be called.
Streams can only be opened if the database is open (per is_open). Otherwise the
request will be ignored, and null will be returned.
get_streams
function unsigned get_streams(
ref uvm_tr_stream q[$]
)
Provides a queue of all streams within the database.
Parameters
q
A reference to a queue of uvm_tr_streams
The get_streams method returns the size of the queue, such that the user can
conditionally process the elements.
uvm_tr_stream stream_q[$];
if (my_db.get_streams(stream_q)) begin
// Process the queue...
end
LINK API
UVM 1.2 Class Reference
92
establish_link
function void establish_link(
uvm_link_base link
)
Establishes a link between two elements in the database
Links are only supported between streams and records within a single database.
This method will trigger a do_establish_link call.
IMpLEMENtAtION AGNOstIc API
do_open_db
pure virtual protected function bit do_open_db()
Backend implementation of open_db
do_close_db
pure virtual protected function bit do_close_db()
Backend implementation of close_db
do_open_stream
pure virtual protected function uvm_tr_stream do_open_stream(
string name,
string scope,
string type_name
)
Backend implementation of open_stream
do_establish_link
pure virtual protected function void do_establish_link(
uvm_link_base link
)
Backend implementation of establish_link
uvm_text_tr_database
The uvm_text_tr_database is the default implementation for the uvm_tr_database. It
provides the ability to store recording information into a textual log file.
UVM 1.2 Class Reference
93
Summary
uvm_text_tr_database
The uvm_text_tr_database is the default implementation for the
uvm_tr_database.
CLAss HIErArchY
uvm_void
uvm_object
uvm_tr_database
uvm_text_tr_database
CLAss DEcLArAtION
class uvm_text_tr_database extends uvm_tr_database
new
Constructor
IMpLEMENtAtION AGNOstIc
API
do_open_db
do_close_db
do_open_stream
do_establish_link
IMpLEMENtAtION SpEcIFIc
API
set_file_name
Open the backend connection to the database.
Close the backend connection to the database.
Provides a reference to a stream within the
database.
Establishes a link between two elements in the
database
Sets the file name which will be used for output.
new
function new(
string name = "unnamed-uvm_text_tr_database"
)
Constructor
Parameters
name
Instance name
IMpLEMENtAtION AGNOstIc API
do_open_db
protected virtual function bit do_open_db()
Open the backend connection to the database.
Text-Backend implementation of uvm_tr_database::open_db.
UVM 1.2 Class Reference
94
The text-backend will open a text file to dump all records in to. The name of this text
file is controlled via set_file_name.
This will also lock the file_name, so that it cannot be modified while the connection is
open.
do_close_db
protected virtual function bit do_close_db()
Close the backend connection to the database.
Text-Backend implementation of uvm_tr_database::close_db.
The text-backend will close the text file used to dump all records in to, if it is currently
opened.
This unlocks the file_name, allowing it to be modified again.
do_open_stream
protected virtual function uvm_tr_stream do_open_stream(
string name,
string scope,
string type_name
)
Provides a reference to a stream within the database.
Text-Backend implementation of uvm_tr_database::open_stream
do_establish_link
protected virtual function void do_establish_link(
uvm_link_base link
)
Establishes a link between two elements in the database
Text-Backend implementation of uvm_tr_database::establish_link.
IMpLEMENtAtION SpEcIFIc API
set_file_name
function void set_file_name(
string filename
)
Sets the file name which will be used for output.
The set_file_name method can only be called prior to open_db.
By default, the database will use a file named “tr_db.log”.
UVM 1.2 Class Reference
95
7.2 Transaction Recording Streams
Contents
Transaction
Recording
Streams
uvm_tr_stream
uvm_text_tr_stream
The uvm_tr_stream base class is a representation of a
stream of records within a uvm_tr_database.
The uvm_text_tr_stream is the default stream
implementation for the uvm_text_tr_database.
uvm_tr_stream
The uvm_tr_stream base class is a representation of a stream of records within a
uvm_tr_database.
The record stream is intended to hide the underlying database implementation from the
end user, as these details are often vendor or tool-specific.
The uvm_tr_stream class is pure virtual, and must be extended with an implementation. A default text-based implementation is provided via the uvm_text_tr_stream class.
Summary
uvm_tr_stream
The uvm_tr_stream base class is a representation of a stream of records within a
uvm_tr_database.
CLAss HIErArchY
uvm_void
uvm_object
uvm_tr_stream
CLAss DEcLArAtION
virtual class uvm_tr_stream extends uvm_object
new
CONFIGUrAtION API
get_db
get_scope
get_stream_type_name
StrEAM API
close
free
is_open
UVM 1.2 Class Reference
Constructor
Returns a reference to the database which
contains this stream.
Returns the scope supplied when opening this
stream.
Returns a reference to the database which
contains this stream.
Once a stream has been opened via
uvm_tr_database::open_stream, the user can
close the stream.
Closes this stream.
Frees this stream.
Returns true if this uvm_tr_stream was opened
96
is_closed
TrANsActION REcOrdEr API
open_recorder
get_recorders
HANdLEs
get_handle
get_stream_from_handle
IMpLEMENtAtION AGNOstIc
API
do_open
do_close
do_free
do_open_recorder
on the database, but has not yet been closed.
Returns true if this uvm_tr_stream was closed on
the database, but has not yet been freed.
New recorders can be opened prior to the stream
being closed.
Marks the opening of a new transaction recorder
on the stream.
Provides a queue of all transactions within the
stream.
Returns a unique ID for this stream.
Static accessor, returns a stream reference for a
given unique id.
Callback triggered via
uvm_tr_database::open_stream.
Callback triggered via close.
Callback triggered via free.
Marks the beginning of a new record in the
stream.
new
function new(
string name = "unnamed-uvm_tr_stream"
)
Constructor
Parameters
name
Stream instance name
CONFIGUrAtION API
get_db
function uvm_tr_database get_db()
Returns a reference to the database which contains this stream.
A warning will be asserted if get_db is called prior to the stream being initialized via
do_open.
get_scope
function string get_scope()
Returns the scope supplied when opening this stream.
A warning will be asserted if get_scope is called prior to the stream being initialized via
do_open.
UVM 1.2 Class Reference
97
get_stream_type_name
function string get_stream_type_name()
Returns a reference to the database which contains this stream.
A warning will be asserted if get_stream_type_name is called prior to the stream being
initialized via do_open.
StrEAM API
Once a stream has been opened via uvm_tr_database::open_stream, the user can close
the stream.
Due to the fact that many database implementations will require crossing a language
boundary, an additional step of freeing the stream is required.
A link can be established within the database any time between “Open” and “Free”,
however it is illegal to establish a link after “Freeing” the stream.
close
function void close()
Closes this stream.
Closing a stream closes all open recorders in the stream.
This method will trigger a do_close call, followed by uvm_recorder::close on all open
recorders within the stream.
free
function void free()
Frees this stream.
Freeing a stream indicates that the database can free any references to the stream
(including references to records within the stream).
This method will trigger a do_free call, followed by uvm_recorder::free on all recorders
within the stream.
is_open
function bit is_open()
Returns true if this uvm_tr_stream was opened on the database, but has not yet been
closed.
is_closed
UVM 1.2 Class Reference
98
function bit is_closed()
Returns true if this uvm_tr_stream was closed on the database, but has not yet been
freed.
TrANsActION REcOrdEr API
New recorders can be opened prior to the stream being closed.
Once a stream has been closed, requests to open a new recorder will be ignored
(open_recorder will return null).
open_recorder
function uvm_recorder open_recorder(
string name,
time open_time = 0,
string type_name = ""
)
Marks the opening of a new transaction recorder on the stream.
Parameters
name
A name for the new transaction
open_time
Optional time to record as the opening of this transaction
type_name
Optional type name for the transaction
If open_time is omitted (or set to 0), then the stream will use the current time.
This method will trigger a do_open_recorder call. If do_open_recorder returns a non-null
value, then the uvm_recorder::do_open method will be called in the recorder.
Transaction recorders can only be opened if the stream is open on the database (per
is_open). Otherwise the request will be ignored, and null will be returned.
get_recorders
function unsigned get_recorders(
ref uvm_recorder q[$]
)
Provides a queue of all transactions within the stream.
Parameters
q
A reference to the queue of uvm_recorders
The get_recorders method returns the size of the queue, such that the user can
conditionally process the elements.
uvm_recorder tr_q[$];
if (my_stream.get_recorders(tr_q)) begin
// Process the queue...
end
UVM 1.2 Class Reference
99
HANdLEs
get_handle
function integer get_handle()
Returns a unique ID for this stream.
A value of 0 indicates that the recorder has been freed, and no longer has a valid ID.
get_stream_from_handle
static function uvm_tr_stream get_stream_from_handle(
integer id
)
Static accessor, returns a stream reference for a given unique id.
If no stream exists with the given id, or if the stream with that id has been freed, then
null is returned.
IMpLEMENtAtION AGNOstIc API
do_open
protected virtual function void do_open(
uvm_tr_database db,
string scope,
string stream_type_name
)
Callback triggered via uvm_tr_database::open_stream.
Parameters
db
Database which the stream belongs to
scope
Optional scope
stream_type_name
Optional type name for the stream
The do_open callback can be used to initialize any internal state within the stream, as
well as providing a location to record any initial information about the stream.
do_close
protected virtual function void do_close()
Callback triggered via close.
UVM 1.2 Class Reference
100
The do_close callback can be used to set internal state within the stream, as well as
providing a location to record any closing information.
do_free
protected virtual function void do_free()
Callback triggered via free.
The do_free callback can be used to release the internal state within the stream, as well
as providing a location to record any “freeing” information.
do_open_recorder
protected virtual function uvm_recorder do_open_recorder(
string name,
time open_time,
string type_name
)
Marks the beginning of a new record in the stream.
Backend implementation of open_recorder
uvm_text_tr_stream
The uvm_text_tr_stream is the default stream implementation for the
uvm_text_tr_database.
Summary
uvm_text_tr_stream
The uvm_text_tr_stream is the default stream implementation for the
uvm_text_tr_database.
CLAss HIErArchY
uvm_void
uvm_object
uvm_tr_stream
uvm_text_tr_stream
CLAss DEcLArAtION
class uvm_text_tr_stream extends uvm_tr_stream
new
IMpLEMENtAtION AGNOstIc
API
do_open
do_close
do_free
UVM 1.2 Class Reference
Constructor
Callback triggered via
uvm_tr_database::open_stream.
Callback triggered via uvm_tr_stream::close.
Callback triggered via uvm_tr_stream::free.
101
do_open_recorder
Marks the beginning of a new record in the stream
new
function new(
string name = "unnamed-uvm_text_tr_stream"
)
Constructor
Parameters
name
Instance name
IMpLEMENtAtION AGNOstIc API
do_open
protected virtual function void do_open(
uvm_tr_database db,
string scope,
string stream_type_name
)
Callback triggered via uvm_tr_database::open_stream.
do_close
protected virtual function void do_close()
Callback triggered via uvm_tr_stream::close.
do_free
protected virtual function void do_free()
Callback triggered via uvm_tr_stream::free.
do_open_recorder
protected virtual function uvm_recorder do_open_recorder(
string name,
time open_time,
string type_name
)
Marks the beginning of a new record in the stream
Text-backend specific implementation.
UVM 1.2 Class Reference
102
8. Factory Classes
As the name implies, the uvm_factory is used to manufacture (create) UVM objects and
components. Only one instance of the factory is present in a given simulation.
User-defined object and component types are registered with the factory via typedef or
macro invocation, as explained in uvm_default_factory::Usage. The factory generates
and stores lightweight proxies to the user-defined objects and components:
uvm_object_registry #(T,Tname) for objects and uvm_component_registry #(T,Tname)
for components. Each proxy only knows how to create an instance of the object or
component it represents, and so is very efficient in terms of memory usage.
When the user requests a new object or component from the factory (e.g. uvm_factory::create_object_by_type), the factory will determine what type of object to
create based on its configuration, then ask that type’s proxy to create an instance of the
type, which is returned to the user.
Summary
Factory Classes
As the name implies, the uvm_factory is used to manufacture (create) UVM
objects and components.
UVM 1.2 Class Reference
103
8.1 Factory Component and Object Wrappers
Contents
Factory Component
and Object Wrappers
Intro
uvm_component_registry
#(T,Tname)
uvm_object_registry
#(T,Tname)
This section defines the proxy component and object
classes used by the factory.
The uvm_component_registry serves as a lightweight
proxy for a component of type T and type name
Tname, a string.
The uvm_object_registry serves as a lightweight proxy
for a uvm_object of type T and type name Tname, a
string.
Intro
This section defines the proxy component and object classes used by the factory. To
avoid the overhead of creating an instance of every component and object that get
registered, the factory holds lightweight wrappers, or proxies. When a request for a new
object is made, the factory calls upon the proxy to create the object it represents.
uvm_component_registry #(T,Tname)
The uvm_component_registry serves as a lightweight proxy for a component of type T
and type name Tname, a string. The proxy enables efficient registration with the
uvm_factory. Without it, registration would require an instance of the component itself.
See Usage section below for information on using uvm_component_registry.
Summary
uvm_component_registry #(T,Tname)
The uvm_component_registry serves as a lightweight proxy for a component of
type T and type name Tname, a string.
CLAss HiERARchY
uvm_object_wrapper
uvm_component_registry#(T,Tname)
CLAss DEcLARAtioN
class uvm_component_registry #(
type T
= uvm_component,
string Tname = "<unknown>"
) extends uvm_object_wrapper
MEthods
create_component
get_type_name
UVM 1.2 Class Reference
Creates a component of type T having the provided
name and parent.
Returns the value given by the string parameter,
104
get
create
set_type_override
set_inst_override
Tname.
Returns the singleton instance of this type.
Returns an instance of the component type, T,
represented by this proxy, subject to any factory
overrides based on the context provided by the parent’s
full name.
Configures the factory to create an object of the type
represented by override_type whenever a request is
made to create an object of the type, T, represented by
this proxy, provided no instance override applies.
Configures the factory to create a component of the
type represented by override_type whenever a request
is made to create an object of the type, T, represented
by this proxy, with matching instance paths.
MEthods
create_component
virtual function uvm_component create_component (
string name,
uvm_component parent
)
Creates a component of type T having the provided name and parent. This is an
override of the method in uvm_object_wrapper. It is called by the factory after
determining the type of object to create. You should not call this method directly. Call
create instead.
get_type_name
virtual function string get_type_name()
Returns the value given by the string parameter, Tname. This method overrides the
method in uvm_object_wrapper.
get
static function this_type get()
Returns the singleton instance of this type. Type-based factory operation depends on
there being a single proxy instance for each registered type.
create
static function T create(
string name, uvm_component parent, contxt = ""
string )
Returns an instance of the component type, T, represented by this proxy, subject to any
factory overrides based on the context provided by the parent’s full name. The contxt
argument, if supplied, supersedes the parent’s context. The new instance will have the
UVM 1.2 Class Reference
105
given leaf name and parent.
set_type_override
static function void set_type_override (
uvm_object_wrapper override_type, bit replace
= 1
)
Configures the factory to create an object of the type represented by override_type
whenever a request is made to create an object of the type, T, represented by this
proxy, provided no instance override applies. The original type, T, is typically a super
class of the override type.
set_inst_override
static function void set_inst_override(
uvm_object_wrapper override_type, string inst_path,
uvm_component parent
= null
)
Configures the factory to create a component of the type represented by override_type
whenever a request is made to create an object of the type, T, represented by this
proxy, with matching instance paths. The original type, T, is typically a super class of
the override type.
If parent is not specified, inst_path is interpreted as an absolute instance path, which
enables instance overrides to be set from outside component classes. If parent is
specified, inst_path is interpreted as being relative to the parent’s hierarchical instance
path, i.e. {parent.get_full_name(),”.”,inst_path} is the instance path that is registered
with the override. The inst_path may contain wildcards for matching against multiple
contexts.
uvm_object_registry #(T,Tname)
The uvm_object_registry serves as a lightweight proxy for a uvm_object of type T and
type name Tname, a string. The proxy enables efficient registration with the
uvm_factory. Without it, registration would require an instance of the object itself.
See Usage section below for information on using uvm_component_registry.
Summary
uvm_object_registry #(T,Tname)
The uvm_object_registry serves as a lightweight proxy for a uvm_object of type T
and type name Tname, a string.
CLAss HiERARchY
uvm_object_wrapper
uvm_object_registry#(T,Tname)
UVM 1.2 Class Reference
106
CLAss DEcLARAtioN
class uvm_object_registry #(
type T
= uvm_object,
string Tname = "<unknown>"
) extends uvm_object_wrapper
create_object
get_type_name
get
create
set_type_override
set_inst_override
UsAGE
Creates an object of type T and returns it as a handle to a
uvm_object.
Returns the value given by the string parameter, Tname.
Returns the singleton instance of this type.
Returns an instance of the object type, T, represented by
this proxy, subject to any factory overrides based on the
context provided by the parent’s full name.
Configures the factory to create an object of the type
represented by override_type whenever a request is made
to create an object of the type represented by this proxy,
provided no instance override applies.
Configures the factory to create an object of the type
represented by override_type whenever a request is made
to create an object of the type represented by this proxy,
with matching instance paths.
This section describes usage for the uvm_*_registry
classes.
create_object
virtual function uvm_object create_object(
string name = ""
)
Creates an object of type T and returns it as a handle to a uvm_object. This is an
override of the method in uvm_object_wrapper. It is called by the factory after
determining the type of object to create. You should not call this method directly. Call
create instead.
get_type_name
virtual function string get_type_name()
Returns the value given by the string parameter, Tname. This method overrides the
method in uvm_object_wrapper.
get
static function this_type get()
Returns the singleton instance of this type. Type-based factory operation depends on
there being a single proxy instance for each registered type.
create
static function T create (
string name = "",
uvm_component parent = null,
string contxt = ""
)
UVM 1.2 Class Reference
107
Returns an instance of the object type, T, represented by this proxy, subject to any
factory overrides based on the context provided by the parent’s full name. The contxt
argument, if supplied, supersedes the parent’s context. The new instance will have the
given leaf name, if provided.
set_type_override
static function void set_type_override (
uvm_object_wrapper override_type, bit replace
= 1
)
Configures the factory to create an object of the type represented by override_type
whenever a request is made to create an object of the type represented by this proxy,
provided no instance override applies. The original type, T, is typically a super class of
the override type.
set_inst_override
static function void set_inst_override(
uvm_object_wrapper override_type, inst_path,
string uvm_component parent
= null
)
Configures the factory to create an object of the type represented by override_type
whenever a request is made to create an object of the type represented by this proxy,
with matching instance paths. The original type, T, is typically a super class of the
override type.
If parent is not specified, inst_path is interpreted as an absolute instance path, which
enables instance overrides to be set from outside component classes. If parent is
specified, inst_path is interpreted as being relative to the parent’s hierarchical instance
path, i.e. {parent.get_full_name(),”.”,inst_path} is the instance path that is registered
with the override. The inst_path may contain wildcards for matching against multiple
contexts.
UsAGE
This section describes usage for the uvm_*_registry classes.
The wrapper classes are used to register lightweight proxies of objects and components.
To register a particular component type, you need only typedef a specialization of its
proxy class, which is typically done inside the class.
For example, to register a UVM component of type mycomp
class mycomp extends uvm_component;
typedef uvm_component_registry #(mycomp,"mycomp") type_id;
endclass
However, because of differences between simulators, it is necessary to use a macro to
ensure vendor interoperability with factory registration. To register a UVM component of
type mycomp in a vendor-independent way, you would write instead:
UVM 1.2 Class Reference
108
class mycomp extends uvm_component;
`uvm_component_utils(mycomp);
...
endclass
The `uvm_component_utils macro is for non-parameterized classes. In this example, the
typedef underlying the macro specifies the Tname parameter as “mycomp”, and
mycomp’s get_type_name() is defined to return the same. With Tname defined, you can
use the factory’s name-based methods to set overrides and create objects and
components of non-parameterized types.
For parameterized types, the type name changes with each specialization, so you cannot
specify a Tname inside a parameterized class and get the behavior you want; the same
type name string would be registered for all specializations of the class! (The factory
would produce warnings for each specialization beyond the first.) To avoid the warnings
and simulator interoperability issues with parameterized classes, you must register
parameterized classes with a different macro.
For example, to register a UVM component of type driver #(T), you would write:
class driver #(type T=int) extends uvm_component;
`uvm_component_param_utils(driver #(T));
...
endclass
The `uvm_component_param_utils and `uvm_object_param_utils macros are used to
register parameterized classes with the factory. Unlike the non-param versions, these
macros do not specify the Tname parameter in the underlying uvm_component_registry
typedef, and they do not define the get_type_name method for the user class. Consequently, you will not be able to use the factory’s name-based methods for
parameterized classes.
The primary purpose for adding the factory’s type-based methods was to accommodate
registration of parameterized types and eliminate the many sources of errors associated
with string-based factory usage. Thus, use of name-based lookup in uvm_factory is no
longer recommended.
UVM 1.2 Class Reference
109
8.2 UVM Factory
This page covers the classes that define the UVM factory facility.
Contents
UVM Factory
This page covers the classes that define the UVM factory
facility.
uvm_factory
As the name implies, uvm_factory is used to manufacture
(create) UVM objects and components.
Default implementation of the UVM factory.
The uvm_object_wrapper provides an abstract interface for
creating object and component proxies.
uvm_default_factory
uvm_object_wrapper
uvm_factory
As the name implies, uvm_factory is used to manufacture (create) UVM objects and
components. Object and component types are registered with the factory using
lightweight proxies to the actual objects and components being created. The
uvm_object_registry #(T,Tname) and uvm_component_registry #(T,Tname) class are
used to proxy uvm_objects and uvm_components.
The factory provides both name-based and type-based interfaces.
type-based
The type-based interface is far less prone to errors in usage. When errors do occur, they are caught at compile-time.
name-based
The name-based interface is dominated by string arguments
that can be misspelled and provided in the wrong order. Errors
in name-based requests might only be caught at the time of the
call, if at all. Further, the name-based interface is not portable
across simulators when used with parameterized classes.
The uvm_factory is an abstract class which declares many of its methods as pure
virtual. The UVM uses the uvm_default_factory class as its default factory
implementation.
See uvm_default_factory::Usage section for details on configuring and using the factory.
Summary
uvm_factory
As the name implies, uvm_factory is used to manufacture (create) UVM objects
and components.
CLAss DEcLARATION
virtual class uvm_factory
RETRIEvING
get
THE fAcTORY
REGIsTERING TYPEs
register
UVM 1.2 Class Reference
Static accessor for uvm_factory
Registers the given proxy object, obj, with
110
the factory.
TYPE & INsTANcE OvERRIdEs
set_inst_override_by_type
set_inst_override_by_name
set_type_override_by_type
set_type_override_by_name
CREATION
create_object_by_type
create_component_by_type
create_object_by_name
create_component_by_name
DEBuG
debug_create_by_type
debug_create_by_name
find_override_by_type
find_override_by_name
find_wrapper_by_name
print
RETRIEvING
Configures the factory to create an object of
the override’s type whenever a request is
made to create an object of the original type
using a context that matches full_inst_path.
Configures the factory to create an object of
the override’s type whenever a request is
made to create an object of the original type,
provided no instance override applies.
Creates and returns a component or object of
the requested type, which may be specified
by type or by name.
These methods perform the same search
algorithm as the create_* methods, but they
do not create new objects.
These methods return the proxy to the
object that would be created given the
arguments.
This method returns the uvm_object_wrapper
associated with a given type_name.
Prints the state of the uvm_factory, including
registered types, instance overrides, and
type overrides.
THE fAcTORY
get
static function uvm_factory get()
Static accessor for uvm_factory
The static accessor is provided as a convenience wrapper around retrieving the factory
via the uvm_coreservice_t::get_factory method.
// Using the uvm_coreservice_t:
uvm_coreservice_t cs;
uvm_factory f;
cs = uvm_coreservice_t::get();
f = cs.get_factory();
// Not using the uvm_coreservice_t:
uvm_factory f;
f = uvm_factory::get();
UVM 1.2 Class Reference
111
REGIsTERING TYPEs
register
pure virtual function void register (
uvm_object_wrapper obj
)
Registers the given proxy object, obj, with the factory. The proxy object is a lightweight
substitute for the component or object it represents. When the factory needs to create
an object of a given type, it calls the proxy’s create_object or create_component method
to do so.
When doing name-based operations, the factory calls the proxy’s get_type_name method
to match against the requested_type_name argument in subsequent calls to
create_component_by_name and create_object_by_name. If the proxy object’s
get_type_name method returns the empty string, name-based lookup is effectively
disabled.
TYPE & INsTANcE OvERRIdEs
set_inst_override_by_type
pure virtual function void set_inst_override_by_type (
uvm_object_wrapper original_type,
uvm_object_wrapper override_type,
string full_inst_path
)
set_inst_override_by_name
pure virtual function void set_inst_override_by_name (
string original_type_name,
string override_type_name,
string full_inst_path
)
Configures the factory to create an object of the override’s type whenever a request is
made to create an object of the original type using a context that matches
full_inst_path. The original type is typically a super class of the override type.
When overriding by type, the original_type and override_type are handles to the types’
proxy objects. Preregistration is not required.
When overriding by name, the original_type_name typically refers to a preregistered type
in the factory. It may, however, be any arbitrary string. Future calls to any of the
create_* methods with the same string and matching instance path will produce the type
represented by override_type_name, which must be preregistered with the factory.
The full_inst_path is matched against the concatenation of {parent_inst_path, “.”, name}
provided in future create requests. The full_inst_path may include wildcards (* and ?)
such that a single instance override can be applied in multiple contexts. A full_inst_path
of “*” is effectively a type override, as it will match all contexts.
UVM 1.2 Class Reference
112
When the factory processes instance overrides, the instance queue is processed in order
of override registrations, and the first override match prevails. Thus, more specific
overrides should be registered first, followed by more general overrides.
set_type_override_by_type
pure virtual function void set_type_override_by_type (
uvm_object_wrapper original_type, uvm_object_wrapper override_type, bit replace
= 1
)
set_type_override_by_name
pure virtual function void set_type_override_by_name (
string original_type_name, string override_type_name, bit replace
= 1
)
Configures the factory to create an object of the override’s type whenever a request is
made to create an object of the original type, provided no instance override applies. The
original type is typically a super class of the override type.
When overriding by type, the original_type and override_type are handles to the types’
proxy objects. Preregistration is not required.
When overriding by name, the original_type_name typically refers to a preregistered type
in the factory. It may, however, be any arbitrary string. Future calls to any of the
create_* methods with the same string and matching instance path will produce the type
represented by override_type_name, which must be preregistered with the factory.
When replace is 1, a previous override on original_type_name is replaced, otherwise a
previous override, if any, remains intact.
CREATION
create_object_by_type
pure virtual function uvm_object create_object_by_type (
uvm_object_wrapper requested_type, parent_inst_path = "",
string string name
= ""
)
create_component_by_type
pure virtual function uvm_component create_component_by_type (
uvm_object_wrapper requested_type, parent_inst_path = "",
string string name,
uvm_component parent
)
UVM 1.2 Class Reference
113
create_object_by_name
pure virtual function uvm_object create_object_by_name (
string requested_type_name, string parent_inst_path
= "",
string name
= ""
)
create_component_by_name
pure virtual function uvm_component create_component_by_name (
string requested_type_name, string parent_inst_path
= "",
string name,
uvm_component parent
)
Creates and returns a component or object of the requested type, which may be
specified by type or by name. A requested component must be derived from the
uvm_component base class, and a requested object must be derived from the
uvm_object base class.
When requesting by type, the requested_type is a handle to the type’s proxy object. Preregistration is not required.
When requesting by name, the request_type_name is a string representing the requested
type, which must have been registered with the factory with that name prior to the
request. If the factory does not recognize the requested_type_name, an error is
produced and a null handle returned.
If the optional parent_inst_path is provided, then the concatenation, {parent_inst_path,
“.”,~name~}, forms an instance path (context) that is used to search for an instance
override. The parent_inst_path is typically obtained by calling the
uvm_component::get_full_name on the parent.
If no instance override is found, the factory then searches for a type override.
Once the final override is found, an instance of that component or object is returned in
place of the requested type. New components will have the given name and parent. New objects will have the given name, if provided.
Override searches are recursively applied, with instance overrides taking precedence over
type overrides. If foo overrides bar, and xyz overrides foo, then a request for bar will
produce xyz. Recursive loops will result in an error, in which case the type returned will
be that which formed the loop. Using the previous example, if bar overrides xyz, then
bar is returned after the error is issued.
DEBuG
debug_create_by_type
pure virtual function void debug_create_by_type (
uvm_object_wrapper requested_type, parent_inst_path = "",
string string name
= ""
)
UVM 1.2 Class Reference
114
debug_create_by_name
pure virtual function void debug_create_by_name (
string requested_type_name, string parent_inst_path
= "",
string name
= ""
)
These methods perform the same search algorithm as the create_* methods, but they do
not create new objects. Instead, they provide detailed information about what type of
object it would return, listing each override that was applied to arrive at the result. Interpretation of the arguments are exactly as with the create_* methods.
find_override_by_type
pure virtual function uvm_object_wrapper find_override_by_type (
uvm_object_wrapper requested_type,
string full_inst_path
)
find_override_by_name
pure virtual function uvm_object_wrapper find_override_by_name (
string requested_type_name,
string full_inst_path
)
These methods return the proxy to the object that would be created given the
arguments. The full_inst_path is typically derived from the parent’s instance path and
the leaf name of the object to be created, i.e. { parent.get_full_name(), “.”, name }.
find_wrapper_by_name
pure virtual function uvm_object_wrapper find_wrapper_by_name (
string type_name
)
This method returns the uvm_object_wrapper associated with a given type_name.
print
pure virtual function void print (
int all_types = 1
)
Prints the state of the uvm_factory, including registered types, instance overrides, and
type overrides.
When all_types is 0, only type and instance overrides are displayed. When all_types is 1
(default), all registered user-defined types are printed as well, provided they have names
associated with them. When all_types is 2, the UVM types (prefixed with uvm_) are
included in the list of registered types.
uvm_default_factory
UVM 1.2 Class Reference
115
Default implementation of the UVM factory.
Summary
uvm_default_factory
Default implementation of the UVM factory.
CLAss HIERARcHY
uvm_factory
uvm_default_factory
CLAss DEcLARATION
class uvm_default_factory extends uvm_factory
REGIsTERING TYPEs
register
TYPE & INsTANcE OvERRIdEs
set_inst_override_by_type
set_inst_override_by_name
set_type_override_by_type
set_type_override_by_name
CREATION
create_object_by_type
create_component_by_type
create_object_by_name
create_component_by_name
DEBuG
debug_create_by_type
debug_create_by_name
find_override_by_type
find_override_by_name
print
UsAGE
Registers the given proxy object, obj, with
the factory.
Configures the factory to create an object of
the override’s type whenever a request is
made to create an object of the original type
using a context that matches full_inst_path.
Configures the factory to create an object of
the override’s type whenever a request is
made to create an object of the original type,
provided no instance override applies.
Creates and returns a component or object of
the requested type, which may be specified
by type or by name.
These methods perform the same search
algorithm as the create_* methods, but they
do not create new objects.
These methods return the proxy to the
object that would be created given the
arguments.
Prints the state of the uvm_factory, including
registered types, instance overrides, and
type overrides.
Using the factory involves three basic
operations
REGIsTERING TYPEs
register
UVM 1.2 Class Reference
116
virtual function void register (
uvm_object_wrapper obj
)
Registers the given proxy object, obj, with the factory.
TYPE & INsTANcE OvERRIdEs
set_inst_override_by_type
virtual function void set_inst_override_by_type (
uvm_object_wrapper original_type,
uvm_object_wrapper override_type,
string full_inst_path
)
set_inst_override_by_name
virtual function void set_inst_override_by_name (
string original_type_name,
string override_type_name,
string full_inst_path
)
Configures the factory to create an object of the override’s type whenever a request is
made to create an object of the original type using a context that matches
full_inst_path.
set_type_override_by_type
virtual function void set_type_override_by_type (
uvm_object_wrapper original_type, uvm_object_wrapper override_type, bit replace
= 1
)
set_type_override_by_name
virtual function void set_type_override_by_name (
string original_type_name, string override_type_name, bit replace
= 1
)
Configures the factory to create an object of the override’s type whenever a request is
made to create an object of the original type, provided no instance override applies.
CREATION
create_object_by_type
UVM 1.2 Class Reference
117
virtual function uvm_object create_object_by_type (
uvm_object_wrapper requested_type, parent_inst_path = "",
string string name
= ""
)
create_component_by_type
virtual function uvm_component create_component_by_type (
uvm_object_wrapper requested_type, string parent_inst_path = "",
string name,
parent
uvm_component )
create_object_by_name
virtual function uvm_object create_object_by_name (
string requested_type_name, string parent_inst_path
= "",
string name
= ""
)
create_component_by_name
virtual function uvm_component create_component_by_name (
string requested_type_name, parent_inst_path
= "",
string string name,
uvm_component parent
)
Creates and returns a component or object of the requested type, which may be
specified by type or by name.
DEBuG
debug_create_by_type
virtual function void debug_create_by_type (
uvm_object_wrapper requested_type, parent_inst_path = "",
string string name
= ""
)
debug_create_by_name
virtual function void debug_create_by_name (
string requested_type_name, = "",
string parent_inst_path
string name
= ""
)
These methods perform the same search algorithm as the create_* methods, but they do
not create new objects.
UVM 1.2 Class Reference
118
find_override_by_type
virtual function uvm_object_wrapper find_override_by_type (
uvm_object_wrapper requested_type,
string full_inst_path
)
find_override_by_name
virtual function uvm_object_wrapper find_override_by_name (
string requested_type_name,
string full_inst_path
)
These methods return the proxy to the object that would be created given the
arguments.
print
virtual function void print (
int all_types = 1
)
Prints the state of the uvm_factory, including registered types, instance overrides, and
type overrides.
UsAGE
Using the factory involves three basic operations
1
Registering objects and components types with the factory
2
Designing components to use the factory to create objects or components
3
Configuring the factory with type and instance overrides, both within and
outside components
We’ll briefly cover each of these steps here. More reference information can be found at
Utility Macros, uvm_component_registry #(T,Tname), uvm_object_registry #(T,Tname),
uvm_component.
1 -- Registering objects and component types with the factory
When defining uvm_object and uvm_component-based classes, simply invoke the
appropriate macro. Use of macros are required to ensure portability across different
vendors’ simulators.
Objects that are not parameterized are declared as
class packet extends uvm_object;
`uvm_object_utils(packet)
endclass
class packetD extends packet;
`uvm_object_utils(packetD)
endclass
UVM 1.2 Class Reference
119
Objects that are parameterized are declared as
class packet #(type T=int, int WIDTH=32) extends uvm_object;
`uvm_object_param_utils(packet #(T,WIDTH))
endclass
Components that are not parameterized are declared as
class comp extends uvm_component;
`uvm_component_utils(comp)
endclass
Components that are parameterized are declared as
class comp #(type T=int, int WIDTH=32) extends uvm_component;
`uvm_component_param_utils(comp #(T,WIDTH))
endclass
The `uvm_*_utils macros for simple, non-parameterized classes will register the type
with the factory and define the get_type, get_type_name, and create virtual methods
inherited from uvm_object. It will also define a static type_name variable in the class,
which will allow you to determine the type without having to allocate an instance.
The `uvm_*_param_utils macros for parameterized classes differ from `uvm_*_utils
classes in the following ways:
The get_type_name method and static type_name variable are not defined. You will need to implement these manually.
A type name is not associated with the type when registering with the factory, so
the factory’s *_by_name operations will not work with parameterized classes.
The factory’s print, debug_create_by_type, and debug_create_by_name methods,
which depend on type names to convey information, will list parameterized types
as ‘<unknown>’.
It is worth noting that environments that exclusively use the type-based factory methods
(*_by_type) do not require type registration. The factory’s type-based methods will
register the types involved “on the fly,” when first used. However, registering with the
`uvm_*_utils macros enables name-based factory usage and implements some useful
utility functions.
2 -- Designing components that defer creation to the factory
Having registered your objects and components with the factory, you can now make
requests for new objects and components via the factory. Using the factory instead of
allocating them directly (via new) allows different objects to be substituted for the
original without modifying the requesting class. The following code defines a driver class
that is parameterized.
class driverB #(type T=uvm_object) extends uvm_driver;
// parameterized classes must use the _param_utils version
`uvm_component_param_utils(driverB #(T))
// our packet type; this can be overridden via the factory
T pkt;
UVM 1.2 Class Reference
120
// standard component constructor
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
// get_type_name not implemented by macro for parameterized classes
const static string type_name = {"driverB #(",T::type_name,")"};
virtual function string get_type_name();
return type_name;
endfunction
// using the factory allows pkt overrides from outside the class
virtual function void build_phase(uvm_phase phase);
pkt = packet::type_id::create("pkt",this);
endfunction
// print the packet so we can confirm its type when printing
virtual function void do_print(uvm_printer printer);
printer.print_object("pkt",pkt);
endfunction
endclass
For purposes of illustrating type and instance overrides, we define two subtypes of the
driverB class. The subtypes are also parameterized, so we must again provide an
implementation for uvm_object::get_type_name, which we recommend writing in terms
of a static string constant.
class driverD1 #(type T=uvm_object) extends driverB #(T);
`uvm_component_param_utils(driverD1 #(T))
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
const static string type_name = {"driverD1 #(",T::type_name,")"};
virtual function string get_type_name();
...return type_name;
endfunction
endclass
class driverD2 #(type T=uvm_object) extends driverB #(T);
`uvm_component_param_utils(driverD2 #(T))
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
const static string type_name = {"driverD2 #(",T::type_name,")"};
virtual function string get_type_name();
return type_name;
endfunction
endclass
// typedef some specializations for convenience
typedef driverB #(packet) B_driver;
// the base driver
typedef driverD1 #(packet) D1_driver; // a derived driver
typedef driverD2 #(packet) D2_driver; // another derived driver
Next, we’ll define a agent component, which requires a utils macro for nonparameterized types. Before creating the drivers using the factory, we override driver0’s
packet type to be packetD.
class agent extends uvm_agent;
`uvm_component_utils(agent)
...
B_driver driver0;
B_driver driver1;
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
virtual function void build_phase(uvm_phase phase);
UVM 1.2 Class Reference
121
// override the packet type for driver0 and below
packet::type_id::set_inst_override(packetD::get_type(),"driver0.*");
// create using the factory; actual driver types may be different
driver0 = B_driver::type_id::create("driver0",this);
driver1 = B_driver::type_id::create("driver1",this);
endfunction
endclass
Finally we define an environment class, also not parameterized. Its build_phase
method shows three methods for setting an instance override on a grandchild component
with relative path name, agent1.driver1, all equivalent.
class env extends uvm_env;
`uvm_component_utils(env)
agent agent0;
agent agent1;
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
virtual function void build_phase(uvm_phase phase);
// three methods to set an instance override for agent1.driver1
// - via component convenience method...
set_inst_override_by_type("agent1.driver1",
B_driver::get_type(),
D2_driver::get_type());
// - via the component's proxy (same approach as create)...
B_driver::type_id::set_inst_override(D2_driver::get_type(),
"agent1.driver1",this);
// - via a direct call to a factory method...
factory.set_inst_override_by_type(B_driver::get_type(),
D2_driver::get_type(),
{get_full_name(),".agent1.driver1"});
// create agents using the factory; actual agent types may be different
agent0 = agent::type_id::create("agent0",this);
agent1 = agent::type_id::create("agent1",this);
endfunction
// at end_of_elaboration, print topology and factory state to verify
virtual function void end_of_elaboration_phase(uvm_phase phase);
uvm_top.print_topology();
endfunction
virtual task run_phase(uvm_phase phase);
#100 global_stop_request();
endfunction
endclass
3 -- Configuring the factory with type and instance overrides
In the previous step, we demonstrated setting instance overrides and creating
components using the factory within component classes. Here, we will demonstrate
setting overrides from outside components, as when initializing the environment prior to
running the test.
module top;
env env0;
initial begin
// Being registered first, the following overrides take precedence
// over any overrides made within env0's construction & build.
// Replace all base drivers with derived drivers...
UVM 1.2 Class Reference
122
B_driver::type_id::set_type_override(D_driver::get_type());
// ...except for agent0.driver0, whose type remains a base driver.
//
(Both methods below have the equivalent result.)
// - via the component's proxy (preferred)
B_driver::type_id::set_inst_override(B_driver::get_type(),
"env0.agent0.driver0");
// - via a direct call to a factory method
factory.set_inst_override_by_type(B_driver::get_type(),
B_driver::get_type(),
{get_full_name(),"env0.agent0.driver0"});
// now, create the environment; our factory configuration will
// govern what topology gets created
env0 = new("env0");
// run the test (will execute build phase)
run_test();
end
endmodule
When the above example is run, the resulting topology (displayed via a call to
uvm_root::print_topology in env’s uvm_component::end_of_elaboration_phase method)
is similar to the following:
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
UVM_INFO @ 0 [RNTST] Running test ...
UVM_INFO @ 0 [UVMTOP] UVM testbench topology:
---------------------------------------------------------------------Name
Type
Size
Value
---------------------------------------------------------------------env0
env
env0@2
agent0
agent
agent0@4
driver0
driverB #(packet)
driver0@8
pkt
packet
pkt@21
driver1
driverD #(packet)
driver1@14
pkt
packet
pkt@23
agent1
agent
agent1@6
driver0
driverD #(packet)
driver0@24
pkt
packet
pkt@37
driver1
driverD2 #(packet) driver1@30
pkt
packet
pkt@39
----------------------------------------------------------------------
uvm_object_wrapper
The uvm_object_wrapper provides an abstract interface for creating object and
component proxies. Instances of these lightweight proxies, representing every
uvm_object-based and uvm_component-based object available in the test environment,
are registered with the uvm_factory. When the factory is called upon to create an object
or component, it finds and delegates the request to the appropriate proxy.
Summary
uvm_object_wrapper
The uvm_object_wrapper provides an abstract interface for creating object and
component proxies.
CLAss DEcLARATION
virtual class uvm_object_wrapper
METHOds
UVM 1.2 Class Reference
123
create_object
create_component
get_type_name
Creates a new object with the optional name.
Creates a new component, passing to its constructor
the given name and parent.
Derived classes implement this method to return the
type name of the object created by create_component
or create_object.
METHOds
create_object
virtual function uvm_object create_object (
string name = ""
)
Creates a new object with the optional name. An object proxy (e.g.,
uvm_object_registry #(T,Tname)) implements this method to create an object of a
specific type, T.
create_component
virtual function uvm_component create_component (
string name,
uvm_component parent
)
Creates a new component, passing to its constructor the given name and parent. A
component proxy (e.g. uvm_component_registry #(T,Tname)) implements this method
to create a component of a specific type, T.
get_type_name
pure virtual function string get_type_name()
Derived classes implement this method to return the type name of the object created by
create_component or create_object. The factory uses this name when matching against
the requested type in name-based lookups.
UVM 1.2 Class Reference
124
9. Phasing Overview
UVM implements an automated mechanism for phasing the execution of the various
components in a testbench.
Summary
Phasing Overview
UVM implements an automated mechanism for phasing the execution of the
various components in a testbench.
Phasing Implementation
The API described here provides a general purpose testbench phasing solution, consisting
of a phaser machine, traversing a master schedule graph, which is built by the integrator
from one or more instances of template schedules provided by UVM or by 3rd-party VIP,
and which supports implicit or explicit synchronization, runtime control of threads and
jumps.
Each schedule leaf node refers to a single phase that is compatible with that VIP’s
components and which executes the required behavior via a functor or delegate
extending the phase into component context as required.
Execution threads are tracked on a per-component basis.
Class hierarchy
A single class represents both the definition, the state, and the context of a phase. It is
instantiated once as a singleton IMP and one or more times as nodes in a graph which
represents serial and parallel phase relationships and stores current state as the phaser
progresses, and the phase implementation which specifies required component behavior
(by extension into component context if non-default behavior required.)
The following classes related to phasing are defined herein
uvm_phase : The base class for defining a phase’s behavior, state, context
UVM 1.2 Class Reference
125
uvm_domain : Phasing schedule node representing an independent branch of the
schedule
uvm_bottomup_phase : A phase implementation for bottom up function phases.
uvm_topdown_phase : A phase implementation for topdown function phases.
uvm_task_phase : A phase implementation for task phases.
Common, Run-Time and User-Defined Phases
The common phases to all uvm_components are described in UVM Common Phases.
The run-time phases are described in UVM Run-Time Phases.
The ability to create user-defined phases is described User-Defined Phases.
Summary
Phasing Implementation
The API described here provides a general purpose testbench phasing solution,
consisting of a phaser machine, traversing a master schedule graph, which is built
by the integrator from one or more instances of template schedules provided by
UVM or by 3rd-party VIP, and which supports implicit or explicit synchronization,
runtime control of threads and jumps.
UVM 1.2 Class Reference
126
9.1 Phasing Definition classes
The following class are used to specify a phase and its implied functionality.
Contents
Phasing Definition
classes
The following class are used to specify a phase and its
implied functionality.
uvm_phase
This base class defines everything about a phase:
behavior, state, and context.
Phase state transition descriptor.
This class defines a callback method that is invoked
by the phaser during the execution of a specific node
in the phase graph or all phase nodes.
Convenience type for the
uvm_callbacks#(uvm_phase, uvm_phase_cb) class.
uvm_phase_state_change
uvm_phase_cb
uvm_phase_cb_pool
uvm_phase
This base class defines everything about a phase: behavior, state, and context.
To define behavior, it is extended by UVM or the user to create singleton objects which
capture the definition of what the phase does and how it does it. These are then cloned
to produce multiple nodes which are hooked up in a graph structure to provide context:
which phases follow which, and to hold the state of the phase throughout its lifetime. UVM provides default extensions of this class for the standard runtime phases. VIP
Providers can likewise extend this class to define the phase functor for a particular
component context as required.
This base class defines everything about a phase: behavior, state, and context.
To define behavior, it is extended by UVM or the user to create singleton objects which
capture the definition of what the phase does and how it does it. These are then cloned
to produce multiple nodes which are hooked up in a graph structure to provide context:
which phases follow which, and to hold the state of the phase throughout its lifetime. UVM provides default extensions of this class for the standard runtime phases. VIP
Providers can likewise extend this class to define the phase functor for a particular
component context as required.
Phase Definition
Singleton instances of those extensions are provided as package variables. These
instances define the attributes of the phase (not what state it is in) They are then cloned
into schedule nodes which point back to one of these implementations, and calls its
virtual task or function methods on each participating component. It is the base class
for phase functors, for both predefined and user-defined phases. Per-component
overrides can use a customized imp.
To create custom phases, do not extend uvm_phase directly: see the three predefined
extended classes below which encapsulate behavior for different phase types: task,
bottom-up function and top-down function.
Extend the appropriate one of these to create a uvm_YOURNAME_phase class (or
YOURPREFIX_NAME_phase class) for each phase, containing the default implementation
UVM 1.2 Class Reference
127
of the new phase, which must be a uvm_component-compatible delegate, and which may
be a null implementation. Instantiate a singleton instance of that class for your code to
use when a phase handle is required. If your custom phase depends on methods that
are not in uvm_component, but are within an extended class, then extend the base
YOURPREFIX_NAME_phase class with parameterized component class context as required,
to create a specialized functor which calls your extended component class methods. This
scheme ensures compile-safety for your extended component classes while providing
homogeneous base types for APIs and underlying data structures.
Phase Context
A schedule is a coherent group of one or mode phase/state nodes linked together by a
graph structure, allowing arbitrary linear/parallel relationships to be specified, and
executed by stepping through them in the graph order. Each schedule node points to a
phase and holds the execution state of that phase, and has optional links to other nodes
for synchronization.
The main operations are: construct, add phases, and instantiate hierarchically within
another schedule.
Structure is a DAG (Directed Acyclic Graph). Each instance is a node connected to
others to form the graph. Hierarchy is overlaid with m_parent. Each node in the graph
has zero or more successors, and zero or more predecessors. No nodes are completely
isolated from others. Exactly one node has zero predecessors. This is the root node. Also the graph is acyclic, meaning for all nodes in the graph, by following the forward
arrows you will never end up back where you started but you will eventually reach a
node that has no successors.
Phase State
A given phase may appear multiple times in the complete phase graph, due to the
multiple independent domain feature, and the ability for different VIP to customize their
own phase schedules perhaps reusing existing phases. Each node instance in the graph
maintains its own state of execution.
Phase Handle
Handles of this type uvm_phase are used frequently in the API, both by the user, to
access phasing-specific API, and also as a parameter to some APIs. In many cases, the
singleton phase handles can be used (eg. uvm_run_phase::get()) in APIs. For those
APIs that need to look up that phase in the graph, this is done automatically.
Summary
uvm_phase
This base class defines everything about a phase: behavior, state, and context.
CLAss HIERARchY
uvm_void
uvm_object
uvm_phase
CLAss DEcLARATION
class uvm_phase extends uvm_object
CONsTRUcTION
new
UVM 1.2 Class Reference
Create a new phase node, with a name
and a note of its type name - name of
128
get_phase_type
STATE
get_state
get_run_count
find_by_name
find
is
is_before
is_after
CALLBAcKs
exec_func
exec_task
SchEdULE
add
get_parent
get_full_name
get_schedule
get_schedule_name
get_domain
get_imp
get_domain_name
get_adjacent_predecessor_nodes
get_adjacent_successor_nodes
PhAsE DONE OBJEcTION
get_objection
raise_objection
drop_objection
get_objection_count
UVM 1.2 Class Reference
this phase type - a value in
uvm_phase_type
Returns the phase type as defined by
uvm_phase_type
Accessor to return current state of this
phase
Accessor to return the integer number of
times this phase has executed
Locate a phase node with the specified
name and return its handle.
Locate the phase node with the specified
phase IMP and return its handle.
returns 1 if the containing uvm_phase
refers to the same phase as the phase
argument, 0 otherwise
Returns 1 if the containing uvm_phase
refers to a phase that is earlier than the
phase argument, 0 otherwise
returns 1 if the containing uvm_phase
refers to a phase that is later than the
phase argument, 0 otherwise
Implements the functor/delegate
functionality for a function phase type
comp - the component to execute the
functionality upon phase - the phase
schedule that originated this phase call
Implements the functor/delegate
functionality for a task phase type comp
- the component to execute the
functionality upon phase - the phase
schedule that originated this phase call
Build up a schedule structure inserting
phase by phase, specifying linkage
Returns the parent schedule node, if any,
for hierarchical graph traversal
Returns the full path from the enclosing
domain down to this node.
Returns the topmost parent schedule
node, if any, for hierarchical graph
traversal
Returns the schedule name associated
with this phase node
Returns the enclosing domain
Returns the phase implementation for
this this node.
Returns the domain name associated
with this phase node
Provides an array of nodes which are
predecessors to this phase node.
Provides an array of nodes which are
successors to this phase node.
Task-based phase nodes within the
phasing graph provide a uvm_objection
based interface for prolonging the
execution of the phase.
Return the uvm_objection that gates the
termination of the phase.
Raise an objection to ending this phase
Provides components with greater control
over the phase flow for processes which
are not implicit objectors to the phase.
Drop an objection to ending this phase
Returns the current number of objections
129
to ending this phase raised by the given
object.
SYNchRONIZATION
sync
unsync
wait_for_state
The functions ‘sync’ and ‘unsync’ add soft
sync relationships between nodes
Synchronize two domains, fully or
partially
Remove synchronization between two
domains, fully or partially
Wait until this phase compares with the
given state and op operand.
JUMpING
jump
set_jump_phase
end_prematurely
get_jump_target
Jump to a specified phase.
Specify a phase to transition to when
phase is complete.
Set a flag to cause the phase to end
prematurely.
Return handle to the target phase of the
current jump, or null if no jump is in
progress.
CONsTRUcTION
new
function new(
string name
= "uvm_phase",
uvm_phase_type phase_type = UVM_PHASE_SCHEDULE,
uvm_phase parent
= null
)
Create a new phase node, with a name and a note of its type name - name of this phase
type - a value in uvm_phase_type
get_phase_type
function uvm_phase_type get_phase_type()
Returns the phase type as defined by uvm_phase_type
STATE
get_state
function uvm_phase_state get_state()
Accessor to return current state of this phase
get_run_count
function int get_run_count()
UVM 1.2 Class Reference
130
Accessor to return the integer number of times this phase has executed
find_by_name
function uvm_phase find_by_name(
string name,
bit stay_in_scope = 1
)
Locate a phase node with the specified name and return its handle. With stay_in_scope
set, searches only within this phase’s schedule or domain.
find
function uvm_phase find(
uvm_phase phase,
bit stay_in_scope = 1
)
Locate the phase node with the specified phase IMP and return its handle. With
stay_in_scope set, searches only within this phase’s schedule or domain.
is
function bit is(
uvm_phase phase
)
returns 1 if the containing uvm_phase refers to the same phase as the phase argument,
0 otherwise
is_before
function bit is_before(
uvm_phase phase
)
Returns 1 if the containing uvm_phase refers to a phase that is earlier than the phase
argument, 0 otherwise
is_after
function bit is_after(
uvm_phase phase
)
returns 1 if the containing uvm_phase refers to a phase that is later than the phase
argument, 0 otherwise
CALLBAcKs
UVM 1.2 Class Reference
131
exec_func
virtual function void exec_func(
uvm_component comp,
uvm_phase phase
)
Implements the functor/delegate functionality for a function phase type comp - the
component to execute the functionality upon phase - the phase schedule that originated
this phase call
exec_task
virtual task exec_task(
uvm_component comp,
uvm_phase phase
)
Implements the functor/delegate functionality for a task phase type comp - the
component to execute the functionality upon phase - the phase schedule that originated
this phase call
SchEdULE
add
function void add(
uvm_phase phase,
uvm_phase with_phase = null,
uvm_phase after_phase = null,
uvm_phase before_phase = null
)
Build up a schedule structure inserting phase by phase, specifying linkage
Phases can be added anywhere, in series or parallel with existing nodes
phase
handle of singleton derived imp containing actual functor. by
default the new phase is appended to the schedule
with_phase
specify to add the new phase in parallel with this one
after_phase
specify to add the new phase as successor to this one
before_phase
specify to add the new phase as predecessor to this one
get_parent
function uvm_phase get_parent()
Returns the parent schedule node, if any, for hierarchical graph traversal
get_full_name
virtual function string get_full_name()
UVM 1.2 Class Reference
132
Returns the full path from the enclosing domain down to this node. The singleton IMP
phases have no hierarchy.
get_schedule
function uvm_phase get_schedule(
bit hier = 0
)
Returns the topmost parent schedule node, if any, for hierarchical graph traversal
get_schedule_name
function string get_schedule_name(
bit hier = 0
)
Returns the schedule name associated with this phase node
get_domain
function uvm_domain get_domain()
Returns the enclosing domain
get_imp
function uvm_phase get_imp()
Returns the phase implementation for this this node. Returns null if this phase type is
not a UVM_PHASE_LEAF_NODE.
get_domain_name
function string get_domain_name()
Returns the domain name associated with this phase node
get_adjacent_predecessor_nodes
function void get_adjacent_predecessor_nodes(
ref uvm_phase pred[]
)
Provides an array of nodes which are predecessors to this phase node. A ‘predecessor
node’ is defined as any phase node which lies prior to this node in the phase graph, with
no nodes between this node and the predecessor node.
get_adjacent_successor_nodes
UVM 1.2 Class Reference
133
function void get_adjacent_successor_nodes(
ref uvm_phase succ[]
)
Provides an array of nodes which are successors to this phase node. A ‘successor’s
node’ is defined as any phase node which comes after this node in the phase graph, with
no nodes between this node and the successor node.
PhAsE DONE OBJEcTION
Task-based phase nodes within the phasing graph provide a uvm_objection based
interface for prolonging the execution of the phase. All other phase types do not contain
an objection, and will report a fatal error if the user attempts to raise, drop, or
get_objection_count.
get_objection
function uvm_objection get_objection()
Return the uvm_objection that gates the termination of the phase.
raise_objection
virtual function void raise_objection (
uvm_object obj,
description = "",
string int count
= 1
)
Raise an objection to ending this phase Provides components with greater control over
the phase flow for processes which are not implicit objectors to the phase.
while(1) begin
some_phase.raise_objection(this);
...
some_phase.drop_objection(this);
end
...
drop_objection
virtual function void drop_objection (
uvm_object obj,
description = "",
string int count
= 1
)
Drop an objection to ending this phase
The drop is expected to be matched with an earlier raise.
get_objection_count
UVM 1.2 Class Reference
134
virtual function int get_objection_count(
uvm_object obj = null
)
Returns the current number of objections to ending this phase raised by the given
object.
SYNchRONIZATION
The functions ‘sync’ and ‘unsync’ add soft sync relationships between nodes
Summary of usage
my_phase.sync(.target(domain)
[,.phase(phase)[,.with_phase(phase)]]);
my_phase.unsync(.target(domain)
[,.phase(phase)[,.with_phase(phase)]]);
Components in different schedule domains can be phased independently or in sync with
each other. An API is provided to specify synchronization rules between any two
domains. Synchronization can be done at any of three levels:
the domain’s whole phase schedule can be synchronized
a phase can be specified, to sync that phase with a matching counterpart
or a more detailed arbitrary synchronization between any two phases
Each kind of synchronization causes the same underlying data structures to be
managed. Like other APIs, we use the parameter dot-notation to set optional
parameters.
When a domain is synced with another domain, all of the matching phases in the two
domains get a ‘with’ relationship between them. Likewise, if a domain is unsynched, all
of the matching phases that have a ‘with’ relationship have the dependency removed. It
is possible to sync two domains and then just remove a single phase from the
dependency relationship by unsyncing just the one phase.
sync
function void sync(
uvm_domain target,
= null,
uvm_phase phase
uvm_phase with_phase = null
)
Synchronize two domains, fully or partially
target
handle of target domain to synchronize this one to
phase
optional single phase in this domain to synchronize, otherwise
sync all
with_phase
optional different target-domain phase to synchronize with,
otherwise use phase in the target domain
unsync
UVM 1.2 Class Reference
135
function void unsync(
uvm_domain target,
= null,
uvm_phase phase
uvm_phase with_phase = null
)
Remove synchronization between two domains, fully or partially
target
handle of target domain to remove synchronization from
phase
optional single phase in this domain to un-synchronize, otherwise
unsync all
with_phase
optional different target-domain phase to un-synchronize with,
otherwise use phase in the target domain
wait_for_state
task wait_for_state(
uvm_phase_state state, uvm_wait_op op
= UVM_EQ
)
Wait until this phase compares with the given state and op operand. For UVM_EQ and
UVM_NE operands, several uvm_phase_states can be supplied by ORing their enum
constants, in which case the caller will wait until the phase state is any of (UVM_EQ) or
none of (UVM_NE) the provided states.
To wait for the phase to be at the started state or after
wait_for_state(UVM_PHASE_STARTED, UVM_GTE);
To wait for the phase to be either started or executing
wait_for_state(UVM_PHASE_STARTED | UVM_PHASE_EXECUTING, UVM_EQ);
JUMpING
jump
function void jump(
uvm_phase phase
)
Jump to a specified phase. If the destination phase is within the current phase schedule,
a simple local jump takes place. If the jump-to phase is outside of the current schedule
then the jump affects other schedules which share the phase.
set_jump_phase
function void set_jump_phase(
uvm_phase phase
UVM 1.2 Class Reference
136
)
Specify a phase to transition to when phase is complete. Note that this function is part
of what jump() does; unlike jump() it does not set the flag to terminate the phase
prematurely.
end_prematurely
function void end_prematurely()
Set a flag to cause the phase to end prematurely. Note that this function is part of what
jump() does; unlike jump() it does not set a jump_phase to go to after the phase ends.
get_jump_target
function uvm_phase get_jump_target()
Return handle to the target phase of the current jump, or null if no jump is in progress. Valid for use during the phase_ended() callback
uvm_phase_state_change
Phase state transition descriptor. Used to describe the phase transition that caused a
uvm_phase_state_changed() callback to be invoked.
Summary
uvm_phase_state_change
Phase state transition descriptor.
CLAss HIERARchY
uvm_void
uvm_object
uvm_phase_state_change
CLAss DEcLARATION
class uvm_phase_state_change extends uvm_object
METhOds
get_state()
get_prev_state()
jump_to()
Returns the state the phase just transitioned to.
Returns the state the phase just transitioned from.
If the current state is UVM_PHASE_ENDED or
UVM_PHASE_JUMPING because of a phase jump, returns
the phase that is the target of jump.
METhOds
UVM 1.2 Class Reference
137
get_state()
virtual function uvm_phase_state get_state()
Returns the state the phase just transitioned to. Functionally equivalent to
uvm_phase::get_state().
get_prev_state()
virtual function uvm_phase_state get_prev_state()
Returns the state the phase just transitioned from.
jump_to()
function uvm_phase jump_to()
If the current state is UVM_PHASE_ENDED or UVM_PHASE_JUMPING because of a phase
jump, returns the phase that is the target of jump. Returns null otherwise.
uvm_phase_cb
This class defines a callback method that is invoked by the phaser during the execution
of a specific node in the phase graph or all phase nodes. User-defined callback
extensions can be used to integrate data types that are not natively phase-aware with
the UVM phasing.
Summary
uvm_phase_cb
This class defines a callback method that is invoked by the phaser during the
execution of a specific node in the phase graph or all phase nodes.
CLAss HIERARchY
uvm_void
uvm_object
uvm_callback
uvm_phase_cb
CLAss DEcLARATION
class uvm_phase_cb extends uvm_callback
METhOds
new
phase_state_change
UVM 1.2 Class Reference
Constructor
Called whenever a phase changes state.
138
METhOds
new
function new(
string name = "unnamed-uvm_phase_cb"
)
Constructor
phase_state_change
virtual function void phase_state_change(
uvm_phase phase,
uvm_phase_state_change change
)
Called whenever a phase changes state. The change descriptor describes the transition
that was just completed. The callback method is invoked immediately after the phase
state has changed, but before the phase implementation is executed.
An extension may interact with the phase, such as raising the phase objection to prolong
the phase, in a manner that is consistent with the current phase state.
By default, the callback method does nothing. Unless otherwise specified, modifying the
phase transition descriptor has no effect on the phasing schedule or execution.
uvm_phase_cb_pool
Convenience type for the uvm_callbacks#(uvm_phase, uvm_phase_cb) class.
Summary
uvm_phase_cb_pool
Convenience type for the uvm_callbacks#(uvm_phase, uvm_phase_cb) class.
CLAss DEcLARATION
typedef uvm_callbacks#(
uvm_phase,
uvm_phase_cb
) uvm_phase_cb_pool
UVM 1.2 Class Reference
139
9.2 uvm_domain
Phasing schedule node representing an independent branch of the schedule. Handle used
to assign domains to components or hierarchies in the testbench
Summary
uvm_domain
Phasing schedule node representing an independent branch of the schedule.
CLAss HIERARchY
uvm_void
uvm_object
uvm_phase
uvm_domain
CLAss DEcLARATION
class uvm_domain extends uvm_phase
METhOds
get_domains
get_uvm_schedule
get_common_domain
add_uvm_phases
get_uvm_domain
new
jump
Provides a list of all domains in the provided domains
argument.
Get the “UVM” schedule, which consists of the runtime phases that all components execute when
participating in the “UVM” domain.
Get the “common” domain, which consists of the
common phases that all components execute in sync
with each other.
Appends to the given schedule the built-in UVM
phases.
Get a handle to the singleton uvm domain
Create a new instance of a phase domain.
jumps all active phases of this domain to to-phase if
there is a path between active-phase and to-phase
METhOds
get_domains
static function void get_domains(
output uvm_domain domains[string]
)
Provides a list of all domains in the provided domains argument.
get_uvm_schedule
static function uvm_phase get_uvm_schedule()
Get the “UVM” schedule, which consists of the run-time phases that all components
UVM 1.2 Class Reference
140
execute when participating in the “UVM” domain.
get_common_domain
static function uvm_domain get_common_domain()
Get the “common” domain, which consists of the common phases that all components
execute in sync with each other. Phases in the “common” domain are build, connect,
end_of_elaboration, start_of_simulation, run, extract, check, report, and final.
add_uvm_phases
static function void add_uvm_phases(
uvm_phase schedule
)
Appends to the given schedule the built-in UVM phases.
get_uvm_domain
static function uvm_domain get_uvm_domain()
Get a handle to the singleton uvm domain
new
function new(
string name
)
Create a new instance of a phase domain.
jump
function void jump(
uvm_phase phase
)
jumps all active phases of this domain to to-phase if there is a path between activephase and to-phase
UVM 1.2 Class Reference
141
9.3 uvm_bottomup_phase
Virtual base class for function phases that operate bottom-up. The pure virtual function
execute() is called for each component. This is the default traversal so is included only
for naming.
A bottom-up function phase completes when the execute() method has been called and
returned on all applicable components in the hierarchy.
Summary
uvm_bottomup_phase
Virtual base class for function phases that operate bottom-up.
CLAss HIERARchY
uvm_void
uvm_object
uvm_phase
uvm_bottomup_phase
CLAss DEcLARATION
virtual class uvm_bottomup_phase extends uvm_phase
METhOds
new
traverse
execute
Create a new instance of a bottom-up phase.
Traverses the component tree in bottom-up order, calling execute
for each component.
Executes the bottom-up phase phase for the component comp.
METhOds
new
function new(
string name
)
Create a new instance of a bottom-up phase.
traverse
virtual function void traverse(
uvm_component comp,
uvm_phase phase,
uvm_phase_state state
)
Traverses the component tree in bottom-up order, calling execute for each component.
UVM 1.2 Class Reference
142
execute
virtual function void execute(
uvm_component comp,
uvm_phase phase
)
Executes the bottom-up phase phase for the component comp.
UVM 1.2 Class Reference
143
9.4 uvm_task_phase
Base class for all task phases. It forks a call to uvm_phase::exec_task() for each
component in the hierarchy.
The completion of the task does not imply, nor is it required for, the end of phase. Once
the phase completes, any remaining forked uvm_phase::exec_task() threads are forcibly
and immediately killed.
By default, the way for a task phase to extend over time is if there is at least one
component that raises an objection.
class my_comp extends uvm_component;
task main_phase(uvm_phase phase);
phase.raise_objection(this, "Applying stimulus")
...
phase.drop_objection(this, "Applied enough stimulus")
endtask
endclass
There is however one scenario wherein time advances within a task-based phase without
any objections to the phase being raised. If two (or more) phases share a common
successor, such as the uvm_run_phase and the uvm_post_shutdown_phase sharing the
uvm_extract_phase as a successor, then phase advancement is delayed until all
predecessors of the common successor are ready to proceed. Because of this, it is
possible for time to advance between uvm_component::phase_started and
uvm_component::phase_ended of a task phase without any participants in the phase
raising an objection.
Summary
uvm_task_phase
Base class for all task phases.
CLAss HIERARchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
CLAss DEcLARATION
virtual class uvm_task_phase extends uvm_phase
METhOds
new
traverse
execute
Create a new instance of a task-based phase
Traverses the component tree in bottom-up order, calling execute
for each component.
Fork the task-based phase phase for the component comp.
METhOds
UVM 1.2 Class Reference
144
new
function new(
string name
)
Create a new instance of a task-based phase
traverse
virtual function void traverse(
uvm_component comp,
uvm_phase phase,
uvm_phase_state state
)
Traverses the component tree in bottom-up order, calling execute for each component. The actual order for task-based phases doesn’t really matter, as each component task is
executed in a separate process whose starting order is not deterministic.
execute
virtual function void execute(
uvm_component comp,
uvm_phase phase
)
Fork the task-based phase phase for the component comp.
UVM 1.2 Class Reference
145
9.5 uvm_topdown_phase
Virtual base class for function phases that operate top-down. The pure virtual function
execute() is called for each component.
A top-down function phase completes when the execute() method has been called and
returned on all applicable components in the hierarchy.
Summary
uvm_topdown_phase
Virtual base class for function phases that operate top-down.
CLAss HIERARchY
uvm_void
uvm_object
uvm_phase
uvm_topdown_phase
CLAss DEcLARATION
virtual class uvm_topdown_phase extends uvm_phase
METhOds
new
traverse
execute
Create a new instance of a top-down phase
Traverses the component tree in top-down order, calling execute
for each component.
Executes the top-down phase phase for the component comp.
METhOds
new
function new(
string name
)
Create a new instance of a top-down phase
traverse
virtual function void traverse(
uvm_component comp,
uvm_phase phase,
uvm_phase_state state
)
Traverses the component tree in top-down order, calling execute for each component.
UVM 1.2 Class Reference
146
execute
virtual function void execute(
uvm_component comp,
uvm_phase phase
)
Executes the top-down phase phase for the component comp.
UVM 1.2 Class Reference
147
9.6 UVM Common Phases
The common phases are the set of function and task phases that all uvm_components
execute together. All uvm_components are always synchronized with respect to the
common phases.
The names of the UVM phases (which will be returned by get_name() for a phase
instance) match the class names specified below with the “uvm_” and “_phase”
removed. For example, the build phase corresponds to the uvm_build_phase class below
and has the name “build”, which means that the following can be used to call foo() at
the end of the build phase (after all lower levels have finished build):
function void phase_ended(uvm_phase phase) ;
if (phase.get_name()=="build") foo() ;
endfunction
The common phases are executed in the sequence they are specified below.
Contents
UVM Common Phases
The common phases are the set of function and
task phases that all uvm_components execute
together.
uvm_build_phase
uvm_connect_phase
uvm_end_of_elaboration_phase
uvm_start_of_simulation_phase
uvm_run_phase
uvm_extract_phase
Create and configure of testbench structure
Establish cross-component connections.
Fine-tune the testbench.
Get ready for DUT to be simulated.
Stimulate the DUT.
Extract data from different points of the
verification environment.
Check for any unexpected conditions in the
verification environment.
Report results of the test.
Tie up loose ends.
uvm_check_phase
uvm_report_phase
uvm_final_phase
uvm_build_phase
Create and configure of testbench structure
uvm_topdown_phase that calls the uvm_component::build_phase method.
Upon entry
The top-level components have been instantiated under uvm_root.
Current simulation time is still equal to 0 but some “delta cycles” may have
occurred
Typical Uses
Instantiate sub-components.
Instantiate register model.
Get configuration values for the component being built.
UVM 1.2 Class Reference
148
Set configuration values for sub-components.
Exit Criteria
All uvm_components have been instantiated.
Summary
uvm_build_phase
Create and configure of testbench structure
CLAss HIeRARchY
uvm_void
uvm_object
uvm_phase
uvm_topdown_phase
uvm_build_phase
CLAss DecLARAtION
class uvm_build_phase extends uvm_topdown_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_build_phase get()
Returns the singleton phase handle
uvm_connect_phase
Establish cross-component connections.
uvm_bottomup_phase that calls the uvm_component::connect_phase method.
Upon Entry
All components have been instantiated.
Current simulation time is still equal to 0 but some “delta cycles” may have
occurred.
Typical Uses
Connect TLM ports and exports.
UVM 1.2 Class Reference
149
Connect TLM initiator sockets and target sockets.
Connect register model to adapter components.
Setup explicit phase domains.
Exit Criteria
All cross-component connections have been established.
All independent phase domains are set.
Summary
uvm_connect_phase
Establish cross-component connections.
CLAss HIeRARchY
uvm_void
uvm_object
uvm_phase
uvm_bottomup_phase
uvm_connect_phase
CLAss DecLARAtION
class uvm_connect_phase extends uvm_bottomup_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_connect_phase get()
Returns the singleton phase handle
uvm_end_of_elaboration_phase
Fine-tune the testbench.
uvm_bottomup_phase that calls the uvm_component::end_of_elaboration_phase method.
Upon Entry
The verification environment has been completely assembled.
Current simulation time is still equal to 0 but some “delta cycles” may have
occurred.
UVM 1.2 Class Reference
150
Typical Uses
Display environment topology.
Open files.
Define additional configuration settings for components.
Exit Criteria
None.
Summary
uvm_end_of_elaboration_phase
Fine-tune the testbench.
CLAss HIeRARchY
uvm_void
uvm_object
uvm_phase
uvm_bottomup_phase
uvm_end_of_elaboration_phase
CLAss DecLARAtION
class uvm_end_of_elaboration_phase extends
uvm_bottomup_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_end_of_elaboration_phase get()
Returns the singleton phase handle
uvm_start_of_simulation_phase
Get ready for DUT to be simulated.
uvm_bottomup_phase that calls the uvm_component::start_of_simulation_phase method.
Upon Entry
Other simulation engines, debuggers, hardware assisted platforms and all other
run-time tools have been started and synchronized.
UVM 1.2 Class Reference
151
The verification environment has been completely configured and is ready to start.
Current simulation time is still equal to 0 but some “delta cycles” may have
occurred.
Typical Uses
Display environment topology
Set debugger breakpoint
Set initial run-time configuration values.
Exit Criteria
None.
Summary
uvm_start_of_simulation_phase
Get ready for DUT to be simulated.
CLAss HIeRARchY
uvm_void
uvm_object
uvm_phase
uvm_bottomup_phase
uvm_start_of_simulation_phase
CLAss DecLARAtION
class uvm_start_of_simulation_phase extends
uvm_bottomup_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_start_of_simulation_phase get()
Returns the singleton phase handle
uvm_run_phase
Stimulate the DUT.
This uvm_task_phase calls the uvm_component::run_phase virtual method. This phase
runs in parallel to the runtime phases, uvm_pre_reset_phase through
UVM 1.2 Class Reference
152
uvm_post_shutdown_phase. All components in the testbench are synchronized with
respect to the run phase regardless of the phase domain they belong to.
Upon Entry
Indicates that power has been applied.
There should not have been any active clock edges before entry into this phase
(e.g. x->1 transitions via initial blocks).
Current simulation time is still equal to 0 but some “delta cycles” may have
occurred.
Typical Uses
Components implement behavior that is exhibited for the entire run-time, across
the various run-time phases.
Backward compatibility with OVM.
Exit Criteria
The DUT no longer needs to be simulated, and
The uvm_post_shutdown_phase is ready to end
The run phase terminates in one of two ways.
1. All run_phase objections are dropped
When all objections on the run_phase objection have been dropped, the phase ends and
all of its threads are killed. If no component raises a run_phase objection immediately
upon entering the phase, the phase ends immediately.
2. Timeout
The phase ends if the timeout expires before all objections are dropped. By default, the
timeout is set to 9200 seconds. You may override this via uvm_root::set_timeout.
If a timeout occurs in your simulation, or if simulation never ends despite completion of
your test stimulus, then it usually indicates that a component continues to object to the
end of a phase.
Summary
uvm_run_phase
Stimulate the DUT.
CLAss HIeRARchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_run_phase
CLAss DecLARAtION
class uvm_run_phase extends uvm_task_phase
MethOds
UVM 1.2 Class Reference
153
get
Returns the singleton phase handle
MethOds
get
static function uvm_run_phase get()
Returns the singleton phase handle
uvm_extract_phase
Extract data from different points of the verification environment.
uvm_bottomup_phase that calls the uvm_component::extract_phase method.
Upon Entry
The DUT no longer needs to be simulated.
Simulation time will no longer advance.
Typical Uses
Extract any remaining data and final state information from scoreboard and
testbench components
Probe the DUT (via zero-time hierarchical references and/or backdoor accesses)
for final state information.
Compute statistics and summaries.
Display final state information
Close files.
Exit Criteria
All data has been collected and summarized.
Summary
uvm_extract_phase
Extract data from different points of the verification environment.
CLAss HIeRARchY
uvm_void
uvm_object
uvm_phase
uvm_bottomup_phase
uvm_extract_phase
UVM 1.2 Class Reference
154
CLAss DecLARAtION
class uvm_extract_phase extends uvm_bottomup_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_extract_phase get()
Returns the singleton phase handle
uvm_check_phase
Check for any unexpected conditions in the verification environment.
uvm_bottomup_phase that calls the uvm_component::check_phase method.
Upon Entry
All data has been collected.
Typical Uses
Check that no unaccounted-for data remain.
Exit Criteria
Test is known to have passed or failed.
Summary
uvm_check_phase
Check for any unexpected conditions in the verification environment.
CLAss HIeRARchY
uvm_void
uvm_object
uvm_phase
uvm_bottomup_phase
uvm_check_phase
CLAss DecLARAtION
class uvm_check_phase extends uvm_bottomup_phase
MethOds
UVM 1.2 Class Reference
155
get
Returns the singleton phase handle
MethOds
get
static function uvm_check_phase get()
Returns the singleton phase handle
uvm_report_phase
Report results of the test.
uvm_bottomup_phase that calls the uvm_component::report_phase method.
Upon Entry
Test is known to have passed or failed.
Typical Uses
Report test results.
Write results to file.
Exit Criteria
End of test.
Summary
uvm_report_phase
Report results of the test.
CLAss HIeRARchY
uvm_void
uvm_object
uvm_phase
uvm_bottomup_phase
uvm_report_phase
CLAss DecLARAtION
class uvm_report_phase extends uvm_bottomup_phase
MethOds
get
UVM 1.2 Class Reference
Returns the singleton phase handle
156
MethOds
get
static function uvm_report_phase get()
Returns the singleton phase handle
uvm_final_phase
Tie up loose ends.
uvm_topdown_phase that calls the uvm_component::final_phase method.
Upon Entry
All test-related activity has completed.
Typical Uses
Close files.
Terminate co-simulation engines.
Exit Criteria
Ready to exit simulator.
Summary
uvm_final_phase
Tie up loose ends.
CLAss HIeRARchY
uvm_void
uvm_object
uvm_phase
uvm_topdown_phase
uvm_final_phase
CLAss DecLARAtION
class uvm_final_phase extends uvm_topdown_phase
MethOds
get
Returns the singleton phase handle
MethOds
UVM 1.2 Class Reference
157
get
static function uvm_final_phase get()
Returns the singleton phase handle
UVM 1.2 Class Reference
158
9.7 UVM Run-Time Phases
The run-time schedule is the pre-defined phase schedule which runs concurrently to the
uvm_run_phase global run phase. By default, all uvm_components using the run-time
schedule are synchronized with respect to the pre-defined phases in the schedule. It is
possible for components to belong to different domains in which case their schedules can
be unsynchronized.
The names of the UVM phases (which will be returned by get_name() for a phase
instance) match the class names specified below with the “uvm_” and “_phase”
removed. For example, the main phase corresponds to the uvm_main_phase class below
and has the name “main”, which means that the following can be used to call foo() at
the start of main phase:
function void phase_started(uvm_phase phase) ;
if (phase.get_name()=="main") foo() ;
endfunction
The run-time phases are executed in the sequence they are specified below.
Contents
UVM Run-Time Phases
The run-time schedule is the pre-defined phase
schedule which runs concurrently to the
uvm_run_phase global run phase.
uvm_pre_reset_phase
uvm_reset_phase
uvm_post_reset_phase
uvm_pre_configure_phase
uvm_configure_phase
uvm_post_configure_phase
uvm_pre_main_phase
uvm_main_phase
uvm_post_main_phase
uvm_pre_shutdown_phase
uvm_shutdown_phase
uvm_post_shutdown_phase
Before reset is asserted.
Reset is asserted.
After reset is de-asserted.
Before the DUT is configured by the SW.
The SW configures the DUT.
After the SW has configured the DUT.
Before the primary test stimulus starts.
Primary test stimulus.
After enough of the primary test stimulus.
Before things settle down.
Letting things settle down.
After things have settled down.
uvm_pre_reset_phase
Before reset is asserted.
uvm_task_phase that calls the uvm_component::pre_reset_phase method. This phase
starts at the same time as the uvm_run_phase unless a user defined phase is inserted in
front of this phase.
Upon Entry
Indicates that power has been applied but not necessarily valid or stable.
There should not have been any active clock edges before entry into this phase.
Typical Uses
UVM 1.2 Class Reference
159
Wait for power good.
Components connected to virtual interfaces should initialize their output to X’s or
Z’s.
Initialize the clock signals to a valid value
Assign reset signals to X (power-on reset).
Wait for reset signal to be asserted if not driven by the verification environment.
Exit Criteria
Reset signal, if driven by the verification environment, is ready to be asserted.
Reset signal, if not driven by the verification environment, is asserted.
Summary
uvm_pre_reset_phase
Before reset is asserted.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_pre_reset_phase
CLAss DecLArAtION
class uvm_pre_reset_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_pre_reset_phase get()
Returns the singleton phase handle
uvm_reset_phase
Reset is asserted.
uvm_task_phase that calls the uvm_component::reset_phase method.
Upon Entry
UVM 1.2 Class Reference
160
Indicates that the hardware reset signal is ready to be asserted.
Typical Uses
Assert reset signals.
Components connected to virtual interfaces should drive their output to their
specified reset or idle value.
Components and environments should initialize their state variables.
Clock generators start generating active edges.
De-assert the reset signal(s) just before exit.
Wait for the reset signal(s) to be de-asserted.
Exit Criteria
Reset signal has just been de-asserted.
Main or base clock is working and stable.
At least one active clock edge has occurred.
Output signals and state variables have been initialized.
Summary
uvm_reset_phase
Reset is asserted.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_reset_phase
CLAss DecLArAtION
class uvm_reset_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_reset_phase get()
Returns the singleton phase handle
UVM 1.2 Class Reference
161
uvm_post_reset_phase
After reset is de-asserted.
uvm_task_phase that calls the uvm_component::post_reset_phase method.
Upon Entry
Indicates that the DUT reset signal has been de-asserted.
Typical Uses
Components should start behavior appropriate for reset being inactive. For
example, components may start to transmit idle transactions or interface training
and rate negotiation. This behavior typically continues beyond the end of this
phase.
Exit Criteria
The testbench and the DUT are in a known, active state.
Summary
uvm_post_reset_phase
After reset is de-asserted.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_post_reset_phase
CLAss DecLArAtION
class uvm_post_reset_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_post_reset_phase get()
Returns the singleton phase handle
uvm_pre_configure_phase
UVM 1.2 Class Reference
162
Before the DUT is configured by the SW.
uvm_task_phase that calls the uvm_component::pre_configure_phase method.
Upon Entry
Indicates that the DUT has been completed reset and is ready to be configured.
Typical Uses
Procedurally modify the DUT configuration information as described in the
environment (and that will be eventually uploaded into the DUT).
Wait for components required for DUT configuration to complete training and rate
negotiation.
Exit Criteria
DUT configuration information is defined.
Summary
uvm_pre_configure_phase
Before the DUT is configured by the SW.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_pre_configure_phase
CLAss DecLArAtION
class uvm_pre_configure_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_pre_configure_phase get()
Returns the singleton phase handle
uvm_configure_phase
UVM 1.2 Class Reference
163
The SW configures the DUT.
uvm_task_phase that calls the uvm_component::configure_phase method.
Upon Entry
Indicates that the DUT is ready to be configured.
Typical Uses
Components required for DUT configuration execute transactions normally.
Set signals and program the DUT and memories (e.g. read/write operations and
sequences) to match the desired configuration for the test and environment.
Exit Criteria
The DUT has been configured and is ready to operate normally.
Summary
uvm_configure_phase
The SW configures the DUT.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_configure_phase
CLAss DecLArAtION
class uvm_configure_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_configure_phase get()
Returns the singleton phase handle
uvm_post_configure_phase
After the SW has configured the DUT.
UVM 1.2 Class Reference
164
uvm_task_phase that calls the uvm_component::post_configure_phase method.
Upon Entry
Indicates that the configuration information has been fully uploaded.
Typical Uses
Wait for configuration information to fully propagate and take effect.
Wait for components to complete training and rate negotiation.
Enable the DUT.
Sample DUT configuration coverage.
Exit Criteria
The DUT has been fully configured and enabled and is ready to start operating
normally.
Summary
uvm_post_configure_phase
After the SW has configured the DUT.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_post_configure_phase
CLAss DecLArAtION
class uvm_post_configure_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_post_configure_phase get()
Returns the singleton phase handle
uvm_pre_main_phase
Before the primary test stimulus starts.
UVM 1.2 Class Reference
165
uvm_task_phase that calls the uvm_component::pre_main_phase method.
Upon Entry
Indicates that the DUT has been fully configured.
Typical Uses
Wait for components to complete training and rate negotiation.
Exit Criteria
All components have completed training and rate negotiation.
All components are ready to generate and/or observe normal stimulus.
Summary
uvm_pre_main_phase
Before the primary test stimulus starts.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_pre_main_phase
CLAss DecLArAtION
class uvm_pre_main_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_pre_main_phase get()
Returns the singleton phase handle
uvm_main_phase
Primary test stimulus.
uvm_task_phase that calls the uvm_component::main_phase method.
UVM 1.2 Class Reference
166
Upon Entry
The stimulus associated with the test objectives is ready to be applied.
Typical Uses
Components execute transactions normally.
Data stimulus sequences are started.
Wait for a time-out or certain amount of time, or completion of stimulus
sequences.
Exit Criteria
Enough stimulus has been applied to meet the primary stimulus objective of the
test.
Summary
uvm_main_phase
Primary test stimulus.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_main_phase
CLAss DecLArAtION
class uvm_main_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_main_phase get()
Returns the singleton phase handle
uvm_post_main_phase
After enough of the primary test stimulus.
uvm_task_phase that calls the uvm_component::post_main_phase method.
UVM 1.2 Class Reference
167
Upon Entry
The primary stimulus objective of the test has been met.
Typical Uses
Included for symmetry.
Exit Criteria
None.
Summary
uvm_post_main_phase
After enough of the primary test stimulus.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_post_main_phase
CLAss DecLArAtION
class uvm_post_main_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_post_main_phase get()
Returns the singleton phase handle
uvm_pre_shutdown_phase
Before things settle down.
uvm_task_phase that calls the uvm_component::pre_shutdown_phase method.
Upon Entry
None.
UVM 1.2 Class Reference
168
Typical Uses
Included for symmetry.
Exit Criteria
None.
Summary
uvm_pre_shutdown_phase
Before things settle down.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_pre_shutdown_phase
CLAss DecLArAtION
class uvm_pre_shutdown_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_pre_shutdown_phase get()
Returns the singleton phase handle
uvm_shutdown_phase
Letting things settle down.
uvm_task_phase that calls the uvm_component::shutdown_phase method.
Upon Entry
None.
Typical Uses
Wait for all data to be drained out of the DUT.
Extract data still buffered in the DUT, usually through read/write operations or
UVM 1.2 Class Reference
169
sequences.
Exit Criteria
All data has been drained or extracted from the DUT.
All interfaces are idle.
Summary
uvm_shutdown_phase
Letting things settle down.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_shutdown_phase
CLAss DecLArAtION
class uvm_shutdown_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_shutdown_phase get()
Returns the singleton phase handle
uvm_post_shutdown_phase
After things have settled down.
uvm_task_phase that calls the uvm_component::post_shutdown_phase method. The end
of this phase is synchronized to the end of the uvm_run_phase phase unless a user
defined phase is added after this phase.
Upon Entry
No more “data” stimulus is applied to the DUT.
Typical Uses
Perform final checks that require run-time access to the DUT (e.g. read accounting
UVM 1.2 Class Reference
170
registers or dump the content of memories).
Exit Criteria
All run-time checks have been satisfied.
The uvm_run_phase phase is ready to end.
Summary
uvm_post_shutdown_phase
After things have settled down.
CLAss HIerArchY
uvm_void
uvm_object
uvm_phase
uvm_task_phase
uvm_post_shutdown_phase
CLAss DecLArAtION
class uvm_post_shutdown_phase extends uvm_task_phase
MethOds
get
Returns the singleton phase handle
MethOds
get
static function uvm_post_shutdown_phase get()
Returns the singleton phase handle
UVM 1.2 Class Reference
171
9.8 User-Defined Phases
To define your own custom phase, use the following pattern.
1. Extend the appropriate base class for your phase type.
class my_PHASE_phase extends uvm_task_phase;
class my_PHASE_phase extends uvm_topdown_phase;
class my_PHASE_phase extends uvm_bottomup_phase;
2. Optionally, implement your exec_task or exec_func method.
task exec_task(uvm_component comp, uvm_phase schedule);
function void exec_func(uvm_component comp, uvm_phase schedule);
If implemented, these methods usually call the related method on the component
comp.PHASE_phase(uvm_phase phase);
3. Since the phase class is a singleton, providing an accessor method allows for easy
global use, and protecting the constructor prevents misuse.
class my_PHASE_phase extends uvm_topdown_phase; or
uvm_task_phase/uvm_bottomum_phase
static local my_PHASE_phase m_inst;
Local reference to global IMP
protected function new(string name="PHASE");
Protected constructor for
singleton
super.new(name);
endfunction : new
static function my_PHASE_phase get();
Static method for accessing
singleton
if (m_imp == null)
m_imp = new();
return m_imp;
endfunction : get
Optionally implement exec_func/exec_task
endclass : my_PHASE_phase
4. Insert the phase in a phase schedule or domain using the uvm_phase::add method:
my_schedule.add(my_PHASE_class::get());
Summary
User-Defined Phases
To define your own custom phase, use the following pattern.
UVM 1.2 Class Reference
172
10. Configuration and Resource Classes
The configuration and resources classes provide access to a centralized database where
type specific information can be stored and received. The uvm_resource_db is the low
level resource database which users can write to or read from. The uvm_config_db is
layered on top of the resoure database and provides a typed interface for configuration
setting that is consistent with the uvm_component::Configuration Interface.
Information can be read from or written to the database at any time during simulation. A resource may be associated with a specific hierarchical scope of a uvm_component or it
may be visible to all components regardless of their hierarchical position.
Summary
Configuration and Resource Classes
The configuration and resources classes provide access to a centralized database
where type specific information can be stored and received.
UVM 1.2 Class Reference
173
10.1 Resources
Contents
Resources
Intro
uvm_resource_types
uvm_resource_options
uvm_resource_base
uvm_resource_pool
uvm_resource #(T)
A resource is a parameterized container that holds
arbitrary data.
Provides typedefs and enums used throughout the
resources facility.
Provides a namespace for managing options for the
resources facility.
Non-parameterized base class for resources.
The global (singleton) resource database.
Parameterized resource.
Intro
A resource is a parameterized container that holds arbitrary data. Resources can be used
to configure components, supply data to sequences, or enable sharing of information
across disparate parts of a testbench. They are stored using scoping information so their
visibility can be constrained to certain parts of the testbench. Resource containers can
hold any type of data, constrained only by the data types available in SystemVerilog. Resources can contain scalar objects, class handles, queues, lists, or even virtual
interfaces.
Resources are stored in a resource database so that each resource can be retrieved by
name or by type. The database has both a name table and a type table and each
resource is entered into both. The database is globally accessible.
Each resource has a set of scopes over which it is visible. The set of scopes is
represented as a regular expression. When a resource is looked up the scope of the
entity doing the looking up is supplied to the lookup function. This is called the current
scope. If the current scope is in the set of scopes over which a resource is visible then
the resource can be retuned in the lookup.
Resources can be looked up by name or by type. To support type lookup each resource
has a static type handle that uniquely identifies the type of each specialized resource
container.
Multiple resources that have the same name are stored in a queue. Each resource is
pushed into a queue with the first one at the front of the queue and each subsequent
one behind it. The same happens for multiple resources that have the same type. The
resource queues are searched front to back, so those placed earlier in the queue have
precedence over those placed later.
The precedence of resources with the same name or same type can be altered. One way
is to set the precedence member of the resource container to any arbitrary value. The
search algorithm will return the resource with the highest precedence. In the case where
there are multiple resources that match the search criteria and have the same (highest)
precedence, the earliest one located in the queue will be one returned. Another way to
change the precedence is to use the set_priority function to move a resource to either
the front or back of the queue.
The classes defined here form the low level layer of the resource database. The classes
include the resource container and the database that holds the containers. The following
set of classes are defined here:
UVM 1.2 Class Reference
174
uvm_resource_types: A class without methods or members, only typedefs and enums. These types and enums are used throughout the resources facility. Putting the types in
a class keeps them confined to a specific name space.
uvm_resource_options: policy class for setting options, such as auditing, which effect
resources.
uvm_resource_base: the base (untyped) resource class living in the resource database. This class includes the interface for setting a resource as read-only, notification, scope
management, altering search priority, and managing auditing.
uvm_resource#(T): parameterized resource container. This class includes the interfaces
for reading and writing each resource. Because the class is parameterized, all the access
functions are type safe.
uvm_resource_pool: the resource database. This is a singleton class object.
uvm_resource_types
Provides typedefs and enums used throughout the resources facility. This class has no
members or methods, only typedefs. It’s used in lieu of package-scope types. When
needed, other classes can use these types by prefixing their usage with
uvm_resource_types::. E.g.
uvm_resource_types::rsrc_q_t queue;
Summary
uvm_resource_types
Provides typedefs and enums used throughout the resources facility.
CLAss DEcLArATiON
class uvm_resource_types
uvm_resource_options
Provides a namespace for managing options for the resources facility. The only thing
allowed in this class is static local data members and static functions for manipulating
and retrieving the value of the data members. The static local data members represent
options and settings that control the behavior of the resources facility.
Summary
uvm_resource_options
Provides a namespace for managing options for the resources facility.
UVM 1.2 Class Reference
175
METHOds
turn_on_auditing
turn_off_auditing
is_auditing
Turn auditing on for the resource database.
Turn auditing off for the resource database.
Returns 1 if the auditing facility is on and 0 if it is off.
METHOds
turn_on_auditing
static function void turn_on_auditing()
Turn auditing on for the resource database. This causes all reads and writes to the
database to store information about the accesses. Auditing is turned on by default.
turn_off_auditing
static function void turn_off_auditing()
Turn auditing off for the resource database. If auditing is turned off, it is not possible to
get extra information about resource database accesses.
is_auditing
static function bit is_auditing()
Returns 1 if the auditing facility is on and 0 if it is off.
uvm_resource_base
Non-parameterized base class for resources. Supports interfaces for scope matching,
and virtual functions for printing the resource and for printing the accessor list
Summary
uvm_resource_base
Non-parameterized base class for resources.
CLAss HiErArcHY
uvm_void
uvm_object
uvm_resource_base
CLAss DEcLArATiON
virtual class uvm_resource_base extends uvm_object
UVM 1.2 Class Reference
176
precedence
default_precedence
new
get_type_handle
REAd-ONLY INTErFAcE
set_read_only
is_read_only
NOTiFicATiON
wait_modified
ScOPE INTErFAcE
set_scope
get_scope
match_scope
PriOriTY
set priority
UTiLiTY FuNcTiONs
do_print
AudiT TrAiL
record_read_access
record_write_access
print_accessors
init_access_record
This variable is used to associate a precedence that a
resource has with respect to other resources which
match the same scope and name.
The default precedence for an resource that has been
created.
constructor for uvm_resource_base.
Pure virtual function that returns the type handle of the
resource container.
Establishes this resource as a read-only resource.
Returns one if this resource has been set to readonly, zero otherwise
This task blocks until the resource has been modified
-- that is, a uvm_resource#(T)::write operation has
been performed.
Each resource has a name, a value and a set of scopes
over which it is visible.
Set the value of the regular expression that identifies
the set of scopes over which this resource is visible.
Retrieve the regular expression string that identifies
the set of scopes over which this resource is visible.
Using the regular expression facility, determine if this
resource is visible in a scope.
Functions for manipulating the search priority of
resources.
Change the search priority of the resource based on
the value of the priority enum argument.
Implementation of do_print which is called by print().
To find out what is happening as the simulation
proceeds, an audit trail of each read and write is kept.
Dump the access records for this resource
Initialize a new access record
precedence
int unsigned precedence
This variable is used to associate a precedence that a resource has with respect to other
resources which match the same scope and name. Resources are set to the
default_precedence initially, and may be set to a higher or lower precedence as desired.
default_precedence
static int unsigned default_precedence = 1000
The default precedence for an resource that has been created. When two resources have
the same precedence, the first resource found has precedence.
new
function new(
UVM 1.2 Class Reference
177
string name = "",
string s
= "*"
)
constructor for uvm_resource_base. The constructor takes two arguments, the name of
the resource and a regular expression which represents the set of scopes over which this
resource is visible.
get_type_handle
pure virtual function uvm_resource_base get_type_handle()
Pure virtual function that returns the type handle of the resource container.
REAd- ONLY INTErFAcE
set_read_only
function void set_read_only()
Establishes this resource as a read-only resource. An attempt to call
uvm_resource#(T)::write on the resource will cause an error.
is_read_only
function bit is_read_only()
Returns one if this resource has been set to read-only, zero otherwise
NOTiFicATiON
wait_modified
task wait_modified()
This task blocks until the resource has been modified -- that is, a
uvm_resource#(T)::write operation has been performed. When a
uvm_resource#(T)::write is performed the modified bit is set which releases the block. Wait_modified() then clears the modified bit so it can be called repeatedly.
ScOPE INTErFAcE
Each resource has a name, a value and a set of scopes over which it is visible. A scope
is a hierarchical entity or a context. A scope name is a multi-element string that
identifies a scope. Each element refers to a scope context and the elements are
separated by dots (.).
UVM 1.2 Class Reference
178
top.env.agent.monitor
Consider the example above of a scope name. It consists of four elements: “top”, “env”,
“agent”, and “monitor”. The elements are strung together with a dot separating each
element. top.env.agent is the parent of top.env.agent.monitor, top.env is the parent of
top.env.agent, and so on. A set of scopes can be represented by a set of scope name
strings. A very straightforward way to represent a set of strings is to use regular
expressions. A regular expression is a special string that contains placeholders which can
be substituted in various ways to generate or recognize a particular set of strings. Here
are a few simple examples:
top\..*
top\.env\..*\.monitor
.*\.monitor
top\.u[1-5]\.*
all of the scopes whose top-level component
is top
all of the scopes in env that end in monitor;
i.e. all the monitors two levels down from env
all of the scopes that end in monitor; i.e.
all the monitors (assuming a naming convention
was used where all monitors are named "monitor")
all of the scopes rooted and named u1, u2, u3,
u4, or u5, and any of their subscopes.
The examples above use POSIX regular expression notation. This is a very general and
expressive notation. It is not always the case that so much expressiveness is required. Sometimes an expression syntax that is easy to read and easy to write is useful, even if
the syntax is not as expressive as the full power of POSIX regular expressions. A
popular substitute for regular expressions is globs. A glob is a simplified regular
expression. It only has three metacharacters -- *, +, and ?. Character ranges are not
allowed and dots are not a metacharacter in globs as they are in regular expressions. The following table shows glob metacharacters.
char meaning
*
+
?
regular expression
equivalent
.*
.+
.
0 or more characters
1 or more characters
exactly one character
Of the examples above, the first three can easily be translated into globs. The last one
cannot. It relies on notation that is not available in glob syntax.
regular expression
glob equivalent
-------------------------------------top\..*
top.*
top\.env\..*\.monitor
top.env.*.monitor
.*\.monitor
*.monitor
The resource facility supports both regular expression and glob syntax. Regular
expressions are identified as such when they surrounded by ‘/’ characters. For example,
/^top\.*/ is interpreted as the regular expression ^top\.*, where the surrounding ‘/’
characters have been removed. All other expressions are treated as glob expressions. They are converted from glob notation to regular expression notation internally. Regular
expression compilation and matching as well as glob-to-regular expression conversion
are handled by two DPI functions:
function int uvm_re_match(string re, string str);
function string uvm_glob_to_re(string glob);
UVM 1.2 Class Reference
179
uvm_re_match both compiles and matches the regular expression. All of the matching is
done using regular expressions, so globs are converted to regular expressions and then
processed.
set_scope
function void set_scope(
string s
)
Set the value of the regular expression that identifies the set of scopes over which this
resource is visible. If the supplied argument is a glob it will be converted to a regular
expression before it is stored.
get_scope
function string get_scope()
Retrieve the regular expression string that identifies the set of scopes over which this
resource is visible.
match_scope
function bit match_scope(
string s
)
Using the regular expression facility, determine if this resource is visible in a scope. Return one if it is, zero otherwise.
PriOriTY
Functions for manipulating the search priority of resources. The function definitions here
are pure virtual and are implemented in derived classes. The definitions serve as a
priority management interface.
set priority
Change the search priority of the resource based on the value of the priority enum
argument.
UTiLiTY FuNcTiONs
do_print
function void do_print (
uvm_printer printer
UVM 1.2 Class Reference
180
)
Implementation of do_print which is called by print().
AudiT TrAiL
To find out what is happening as the simulation proceeds, an audit trail of each read and
write is kept. The uvm_resource#(T)::read and uvm_resource#(T)::write methods each
take an accessor argument. This is a handle to the object that performed that resource
access.
function T read(uvm_object accessor = null);
function void write(T t, uvm_object accessor = null);
The accessor can by anything as long as it is derived from uvm_object. The accessor
object can be a component or a sequence or whatever object from which a read or write
was invoked. Typically the this handle is used as the accessor. For example:
uvm_resource#(int) rint;
int i;
...
rint.write(7, this);
i = rint.read(this);
The accessor’s get_full_name() is stored as part of the audit trail. This way you can find
out what object performed each resource access. Each audit record also includes the
time of the access (simulation time) and the particular operation performed (read or
write).
Auditing is controlled through the uvm_resource_options class.
record_read_access
function void record_read_access(
uvm_object accessor = null
)
record_write_access
function void record_write_access(
uvm_object accessor = null
)
print_accessors
virtual function void print_accessors()
Dump the access records for this resource
UVM 1.2 Class Reference
181
init_access_record
function void init_access_record (
inout uvm_resource_types::access_t access_record
)
Initialize a new access record
uvm_resource_pool
The global (singleton) resource database.
Each resource is stored both by primary name and by type handle. The resource pool
contains two associative arrays, one with name as the key and one with the type handle
as the key. Each associative array contains a queue of resources. Each resource has a
regular expression that represents the set of scopes over which it is visible.
+------+------------+
+------------+------+
| name | rsrc queue |
| rsrc queue | type |
+------+------------+
+------------+------+
|
|
|
|
|
|
+------+------------+
+-+-+
+------------+------+
|
|
|
| | |<--+---*
| T
|
+------+------------+
+-+-+
+-+-+
+------------+------+
| A
|
*---+-->| | |
|
|
|
|
+------+------------+
+-+-+
|
+------------+------+
|
|
|
|
|
|
|
|
+------+------------+
+-------+ +-+
+------------+------+
|
|
|
| |
|
|
|
+------+------------+
| |
+------------+------+
|
|
|
V V
|
|
|
+------+------------+
+------+
+------------+------+
|
|
|
| rsrc |
|
|
|
+------+------------+
+------+
+------------+------+
The above diagrams illustrates how a resource whose name is A and type is T is stored
in the pool. The pool contains an entry in the type map for type T and an entry in the
name map for name A. The queues in each of the arrays each contain an entry for the
resource A whose type is T. The name map can contain in its queue other resources
whose name is A which may or may not have the same type as our resource A. Similarly, the type map can contain in its queue other resources whose type is T and
whose name may or may not be A.
Resources are added to the pool by calling set; they are retrieved from the pool by
calling get_by_name or get_by_type. When an object creates a new resource and calls
set the resource is made available to be retrieved by other objects outside of itself; an
object gets a resource when it wants to access a resource not currently available in its
scope.
The scope is stored in the resource itself (not in the pool) so whether you get by name
or by type the resource’s visibility is the same.
As an auditing capability, the pool contains a history of gets. A record of each get,
whether by get_by_type or get_by_name, is stored in the audit record. Both successful
and failed gets are recorded. At the end of simulation, or any time for that matter, you
can dump the history list. This will tell which resources were successfully located and
which were not. You can use this information to determine if there is some error in
name, type, or scope that has caused a resource to not be located or to be incorrectly
located (i.e. the wrong resource is located).
Summary
UVM 1.2 Class Reference
182
uvm_resource_pool
The global (singleton) resource database.
CLAss DEcLArATiON
class uvm_resource_pool
get
spell_check
SET
set
set_override
set_name_override
set_type_override
LOOKuP
lookup_name
get_highest_precedence
sort_by_precedence
get_by_name
lookup_type
get_by_type
lookup_regex_names
lookup_regex
lookup_scope
SET PriOriTY
set_priority_type
set_priority_name
set_priority
DEBuG
find_unused_resources
print_resources
dump
Returns the singleton handle to the resource pool
Invokes the spell checker for a string s.
Add a new resource to the resource pool.
The resource provided as an argument will be
entered into the pool and will override both by
name and type.
The resource provided as an argument will
entered into the pool using normal precedence in
the type map and will override the name.
The resource provided as an argument will be
entered into the pool using normal precedence in
the name map and will override the type.
This group of functions is for finding resources in
the resource database.
Lookup resources by name.
Traverse a queue, q, of resources and return the
one with the highest precedence.
Given a list of resources, obtained for example
from lookup_scope, sort the resources in
precedence order.
Lookup a resource by name, scope, and
type_handle.
Lookup resources by type.
Lookup a resource by type_handle and scope.
This utility function answers the question, for a
given name, scope, and type_handle, what are all
of the resources with requested name, a matching
scope (where the resource scope may be a
regular expression), and a matching type? Looks for all the resources whose name matches
the regular expression argument and whose scope
matches the current scope.
This is a utility function that answers the
question: For a given scope, what resources are
visible to it? Functions for altering the search priority of
resources.
Change the priority of the rsrc based on the value
of pri, the priority enum argument.
Change the priority of the rsrc based on the value
of pri, the priority enum argument.
Change the search priority of the rsrc based on
the value of pri, the priority enum argument.
Locate all the resources that have at least one
write and no reads
Print the resources that are in a single queue, rq.
dump the entire resource pool.
get
static function uvm_resource_pool get()
UVM 1.2 Class Reference
183
Returns the singleton handle to the resource pool
spell_check
function bit spell_check(
string s
)
Invokes the spell checker for a string s. The universe of correctly spelled strings -- i.e.
the dictionary -- is the name map.
SET
set
function void set (
uvm_resource_base rsrc,
override = 0
uvm_resource_types::override_t )
Add a new resource to the resource pool. The resource is inserted into both the name
map and type map so it can be located by either.
An object creates a resources and sets it into the resource pool. Later, other objects
that want to access the resource must get it from the pool
Overrides can be specified using this interface. Either a name override, a type override
or both can be specified. If an override is specified then the resource is entered at the
front of the queue instead of at the back. It is not recommended that users specify the
override parameter directly, rather they use the set_override, set_name_override, or
set_type_override functions.
set_override
function void set_override(
uvm_resource_base rsrc
)
The resource provided as an argument will be entered into the pool and will override
both by name and type.
set_name_override
function void set_name_override(
uvm_resource_base rsrc
)
The resource provided as an argument will entered into the pool using normal
precedence in the type map and will override the name.
set_type_override
UVM 1.2 Class Reference
184
function void set_type_override(
uvm_resource_base rsrc
)
The resource provided as an argument will be entered into the pool using normal
precedence in the name map and will override the type.
LOOKuP
This group of functions is for finding resources in the resource database.
lookup_name and lookup_type locate the set of resources that matches the name or
type (respectively) and is visible in the current scope. These functions return a queue of
resources.
get_highest_precedence traverse a queue of resources and returns the one with the
highest precedence -- i.e. the one whose precedence member has the highest value.
get_by_name and get_by_type use lookup_name and lookup_type (respectively) and
get_highest_precedence to find the resource with the highest priority that matches the
other search criteria.
lookup_name
function uvm_resource_types::rsrc_q_t lookup_name(
string scope
= "",
string name,
uvm_resource_base type_handle = null,
bit rpterr
= 1
)
Lookup resources by name. Returns a queue of resources that match the name, scope,
and type_handle. If no resources match the queue is returned empty. If rpterr is set
then a warning is issued if no matches are found, and the spell checker is invoked on
name. If type_handle is null then a type check is not made and resources are returned
that match only name and scope.
get_highest_precedence
function uvm_resource_base get_highest_precedence(
ref uvm_resource_types::rsrc_q_t q
)
Traverse a queue, q, of resources and return the one with the highest precedence. In
the case where there exists more than one resource with the highest precedence value,
the first one that has that precedence will be the one that is returned.
sort_by_precedence
static function void sort_by_precedence(
ref uvm_resource_types::rsrc_q_t q
)
Given a list of resources, obtained for example from lookup_scope, sort the resources in
precedence order. The highest precedence resource will be first in the list and the lowest
precedence will be last. Resources that have the same precedence and the same name
UVM 1.2 Class Reference
185
will be ordered by most recently set first.
get_by_name
function uvm_resource_base get_by_name(
string scope
= "",
string name,
uvm_resource_base type_handle, rpterr
= 1
bit )
Lookup a resource by name, scope, and type_handle. Whether the get succeeds or fails,
save a record of the get attempt. The rpterr flag indicates whether to report errors or
not. Essentially, it serves as a verbose flag. If set then the spell checker will be invoked
and warnings about multiple resources will be produced.
lookup_type
function uvm_resource_types::rsrc_q_t lookup_type(
string scope
= "",
uvm_resource_base type_handle )
Lookup resources by type. Return a queue of resources that match the type_handle and
scope. If no resources match then the returned queue is empty.
get_by_type
function uvm_resource_base get_by_type(
string scope
= "",
uvm_resource_base type_handle )
Lookup a resource by type_handle and scope. Insert a record into the get history list
whether or not the get succeeded.
lookup_regex_names
function uvm_resource_types::rsrc_q_t lookup_regex_names(
string scope,
name,
string uvm_resource_base type_handle = null
)
This utility function answers the question, for a given name, scope, and type_handle,
what are all of the resources with requested name, a matching scope (where the
resource scope may be a regular expression), and a matching type? name and scope
are explicit values.
lookup_regex
function uvm_resource_types::rsrc_q_t lookup_regex(
string re,
scope
)
UVM 1.2 Class Reference
186
Looks for all the resources whose name matches the regular expression argument and
whose scope matches the current scope.
lookup_scope
function uvm_resource_types::rsrc_q_t lookup_scope(
string scope
)
This is a utility function that answers the question: For a given scope, what resources are
visible to it? Locate all the resources that are visible to a particular scope. This
operation could be quite expensive, as it has to traverse all of the resources in the
database.
SET PriOriTY
Functions for altering the search priority of resources. Resources are stored in queues in
the type and name maps. When retrieving resources, either by type or by name, the
resource queue is search from front to back. The first one that matches the search
criteria is the one that is returned. The set_priority functions let you change the order in
which resources are searched. For any particular resource, you can set its priority to
UVM_HIGH, in which case the resource is moved to the front of the queue, or to
UVM_LOW in which case the resource is moved to the back of the queue.
set_priority_type
function void set_priority_type(
uvm_resource_base rsrc,
uvm_resource_types::priority_e pri
)
Change the priority of the rsrc based on the value of pri, the priority enum argument. This function changes the priority only in the type map, leaving the name map
untouched.
set_priority_name
function void set_priority_name(
uvm_resource_base rsrc,
uvm_resource_types::priority_e pri
)
Change the priority of the rsrc based on the value of pri, the priority enum argument. This function changes the priority only in the name map, leaving the type map
untouched.
set_priority
function void set_priority (
uvm_resource_base rsrc,
uvm_resource_types::priority_e pri
)
Change the search priority of the rsrc based on the value of pri, the priority enum
UVM 1.2 Class Reference
187
argument. This function changes the priority in both the name and type maps.
DEBuG
find_unused_resources
function uvm_resource_types::rsrc_q_t find_unused_resources()
Locate all the resources that have at least one write and no reads
print_resources
function void print_resources(
uvm_resource_types::rsrc_q_t rq, bit audit = 0
)
Print the resources that are in a single queue, rq. This is a utility function that can be
used to print any collection of resources stored in a queue. The audit flag determines
whether or not the audit trail is printed for each resource along with the name, value,
and scope regular expression.
dump
function void dump(
bit audit = 0
)
dump the entire resource pool. The resource pool is traversed and each resource is
printed. The utility function print_resources() is used to initiate the printing. If the audit
bit is set then the audit trail is dumped for each resource.
uvm_resource #(T)
Parameterized resource. Provides essential access methods to read from and write to
the resource database.
Summary
uvm_resource #(T)
Parameterized resource.
CLAss HiErArcHY
uvm_void
uvm_object
uvm_resource_base
uvm_resource#(T)
UVM 1.2 Class Reference
188
CLAss DEcLArATiON
class uvm_resource #(
type T = int
) extends uvm_resource_base
TYPE INTErFAcE
get_type
get_type_handle
SET/GET INTErFAcE
set
set_override
get_by_name
get_by_type
REAd/WriTE INTErFAcE
read
write
PriOriTY
set priority
get_highest_precedence
Resources can be identified by type using a static
type handle.
Static function that returns the static type handle.
Returns the static type handle of this resource in
a polymorphic fashion.
uvm_resource#(T) provides an interface for setting
and getting a resources.
Simply put this resource into the global resource
pool
Put a resource into the global resource pool as an
override.
looks up a resource by name in the name map.
looks up a resource by type_handle in the type
map.
read and write provide a type-safe interface for
getting and setting the object in the resource
container.
Return the object stored in the resource
container.
Modify the object stored in this resource
container.
Functions for manipulating the search priority of
resources.
Change the search priority of the resource based
on the value of the priority enum argument, pri.
In a queue of resources, locate the first one with
the highest precedence whose type is T.
TYPE INTErFAcE
Resources can be identified by type using a static type handle. The parent class provides
the virtual function interface get_type_handle. Here we implement it by returning the
static type handle.
get_type
static function this_type get_type()
Static function that returns the static type handle. The return type is this_type, which is
the type of the parameterized class.
get_type_handle
function uvm_resource_base get_type_handle()
Returns the static type handle of this resource in a polymorphic fashion. The return type
of get_type_handle() is uvm_resource_base. This function is not static and therefore can
only be used by instances of a parameterized resource.
UVM 1.2 Class Reference
189
SET/GET INTErFAcE
uvm_resource#(T) provides an interface for setting and getting a resources. Specifically,
a resource can insert itself into the resource pool. It doesn’t make sense for a resource
to get itself, since you can’t call a function on a handle you don’t have. However, a
static get interface is provided as a convenience. This obviates the need for the user to
get a handle to the global resource pool as this is done for him here.
set
function void set()
Simply put this resource into the global resource pool
set_override
function void set_override(
Put a resource into the global resource pool as an override. This means it gets put at
the head of the list and is searched before other existing resources that occupy the same
position in the name map or the type map. The default is to override both the name
and type maps. However, using the override argument you can specify that either the
name map or type map is overridden.
get_by_name
static function this_type get_by_name(
string scope, string name, bit rpterr = 1
)
looks up a resource by name in the name map. The first resource with the specified
name, whose type is the current type, and is visible in the specified scope is returned, if
one exists. The rpterr flag indicates whether or not an error should be reported if the
search fails. If rpterr is set to one then a failure message is issued, including suggested
spelling alternatives, based on resource names that exist in the database, gathered by
the spell checker.
get_by_type
static function this_type get_by_type(
string scope
= "",
uvm_resource_base type_handle )
looks up a resource by type_handle in the type map. The first resource with the
specified type_handle that is visible in the specified scope is returned, if one exists. If
there is no resource matching the specifications, null is returned.
REAd/WriTE INTErFAcE
UVM 1.2 Class Reference
190
read and write provide a type-safe interface for getting and setting the object in the
resource container. The interface is type safe because the value argument for write and
the return value of read are T, the type supplied in the class parameter. If either of
these functions is used in an incorrect type context the compiler will complain.
read
function T read(
uvm_object accessor = null
)
Return the object stored in the resource container. If an accessor object is supplied
then also update the accessor record for this resource.
write
function void write(
T t,
uvm_object accessor = null
)
Modify the object stored in this resource container. If the resource is read-only then
issue an error message and return without modifying the object in the container. If the
resource is not read-only and an accessor object has been supplied then also update the
accessor record. Lastly, replace the object value in the container with the value supplied
as the argument, t, and release any processes blocked on
uvm_resource_base::wait_modified. If the value to be written is the same as the value
already present in the resource then the write is not done. That also means that the
accessor record is not updated and the modified bit is not set.
PriOriTY
Functions for manipulating the search priority of resources. These implementations of
the interface defined in the base class delegate to the resource pool.
set priority
Change the search priority of the resource based on the value of the priority enum
argument, pri.
get_highest_precedence
static function this_type get_highest_precedence(
ref uvm_resource_types::rsrc_q_t q
)
In a queue of resources, locate the first one with the highest precedence whose type is
T. This function is static so that it can be called from anywhere.
UVM 1.2 Class Reference
191
10.2 UVM Resource Database
Contents
UVM Resource
Database
Intro
uvm_resource_db
uvm_resource_db_options
The uvm_resource_db class provides a convenience
interface for the resources facility.
All of the functions in uvm_resource_db#(T) are
static, so they must be called using the :: operator.
Provides a namespace for managing options for the
resources DB facility.
Intro
The uvm_resource_db class provides a convenience interface for the resources facility. In many cases basic operations such as creating and setting a resource or getting a
resource could take multiple lines of code using the interfaces in uvm_resource_base or
uvm_resource#(T). The convenience layer in uvm_resource_db reduces many of those
operations to a single line of code.
If the run-time +UVM_RESOURCE_DB_TRACE command line option is specified, all
resource DB accesses (read and write) are displayed.
uvm_resource_db
All of the functions in uvm_resource_db#(T) are static, so they must be called using the
:: operator. For example:
uvm_resource_db#(int)::set("A", "*", 17, this);
The parameter value “int” identifies the resource type as uvm_resource#(int). Thus, the
type of the object in the resource container is int. This maintains the type-safety
characteristics of resource operations.
Summary
uvm_resource_db
All of the functions in uvm_resource_db#(T) are static, so they must be called
using the :: operator.
CLAss DEcLArATiON
class uvm_resource_db #(
type T = uvm_object
)
METHOds
get_by_type
UVM 1.2 Class Reference
Get a resource by type.
192
get_by_name
set_default
set
set_anonymous
read_by_name
read_by_type
write_by_name
write_by_type
dump
Imports a resource by name.
add a new item into the resources database.
Create a new resource, write a val to it, and set it into the
database using name and scope as the lookup
parameters.
Create a new resource, write a val to it, and set it into the
database.
locate a resource by name and scope and read its value.
Read a value by type.
write a val into the resources database.
write a val into the resources database.
Dump all the resources in the resource pool.
METHOds
get_by_type
static function rsrc_t get_by_type(
string scope
)
Get a resource by type. The type is specified in the db class parameter so the only
argument to this function is the scope.
get_by_name
static function rsrc_t get_by_name(
string scope, string name, bit rpterr = 1
)
Imports a resource by name. The first argument is the current scope of the resource to
be retrieved and the second argument is the name. The rpterr flag indicates whether or
not to generate a warning if no matching resource is found.
set_default
static function rsrc_t set_default(
string scope,
string name
)
add a new item into the resources database. The item will not be written to so it will
have its default value. The resource is created using name and scope as the lookup
parameters.
set
static function void set(
input string scope, name,
input string T val,
input uvm_object accessor = null
)
UVM 1.2 Class Reference
193
Create a new resource, write a val to it, and set it into the database using name and
scope as the lookup parameters. The accessor is used for auditing.
set_anonymous
static function void set_anonymous(
input string scope, T val,
input uvm_object accessor = null
)
Create a new resource, write a val to it, and set it into the database. The resource has
no name and therefore will not be entered into the name map. But is does have a scope
for lookup purposes. The accessor is used for auditing.
read_by_name
static function bit read_by_name(
input string scope, name,
input string inout T val,
input uvm_object accessor = null
)
locate a resource by name and scope and read its value. The value is returned through
the output argument val. The return value is a bit that indicates whether or not the
read was successful. The accessor is used for auditing.
read_by_type
static function bit read_by_type(
input string scope, val,
inout T input uvm_object accessor = null
)
Read a value by type. The value is returned through the output argument val. The
scope is used for the lookup. The return value is a bit that indicates whether or not the
read is successful. The accessor is used for auditing.
write_by_name
static function bit write_by_name(
input string scope, name,
input string input T val,
input uvm_object accessor = null
)
write a val into the resources database. First, look up the resource by name and scope. If it is not located then add a new resource to the database and then write its value.
Because the scope is matched to a resource which may be a regular expression, and
consequently may target other scopes beyond the scope argument. Care must be taken
with this function. If a get_by_name match is found for name and scope then val will be
written to that matching resource and thus may impact other scopes which also match
the resource.
UVM 1.2 Class Reference
194
write_by_type
static function bit write_by_type(
input string scope, input T val,
input uvm_object accessor = null
)
write a val into the resources database. First, look up the resource by type. If it is not
located then add a new resource to the database and then write its value.
Because the scope is matched to a resource which may be a regular expression, and
consequently may target other scopes beyond the scope argument. Care must be taken
with this function. If a get_by_name match is found for name and scope then val will be
written to that matching resource and thus may impact other scopes which also match
the resource.
dump
static function void dump()
Dump all the resources in the resource pool. This is useful for debugging purposes. This
function does not use the parameter T, so it will dump the same thing -- the entire
database -- no matter the value of the parameter.
uvm_resource_db_options
Provides a namespace for managing options for the resources DB facility. The only thing
allowed in this class is static local data members and static functions for manipulating
and retrieving the value of the data members. The static local data members represent
options and settings that control the behavior of the resources DB facility.
Summary
uvm_resource_db_options
Provides a namespace for managing options for the resources DB facility.
METHOds
turn_on_tracing
turn_off_tracing
is_tracing
Turn tracing on for the resource database.
Turn tracing off for the resource database.
Returns 1 if the tracing facility is on and 0 if it is off.
METHOds
turn_on_tracing
static function void turn_on_tracing()
UVM 1.2 Class Reference
195
Turn tracing on for the resource database. This causes all reads and writes to the
database to display information about the accesses. Tracing is off by default.
This method is implicitly called by the +UVM_RESOURCE_DB_TRACE.
turn_off_tracing
static function void turn_off_tracing()
Turn tracing off for the resource database.
is_tracing
static function bit is_tracing()
Returns 1 if the tracing facility is on and 0 if it is off.
UVM 1.2 Class Reference
196
10.3 UVM Configuration Database
Contents
UVM Configuration
Database
Intro
uvm_config_db
Types
uvm_config_int
uvm_config_string
uvm_config_object
uvm_config_wrapper
uvm_config_db_options
The uvm_config_db class provides a convenience
interface on top of the uvm_resource_db to simplify the
basic interface that is used for configuring
uvm_component instances.
All of the functions in uvm_config_db#(T) are static, so
they must be called using the :: operator.
Convenience type for
uvm_config_db#(uvm_bitstream_t)
Convenience type for uvm_config_db#(string)
Convenience type for uvm_config_db#(uvm_object)
Convenience type for
uvm_config_db#(uvm_object_wrapper)
Provides a namespace for managing options for the
configuration DB facility.
Intro
The uvm_config_db class provides a convenience interface on top of the
uvm_resource_db to simplify the basic interface that is used for configuring
uvm_component instances.
If the run-time +UVM_CONFIG_DB_TRACE command line option is specified, all
configuration DB accesses (read and write) are displayed.
uvm_config_db
All of the functions in uvm_config_db#(T) are static, so they must be called using the ::
operator. For example:
uvm_config_db#(int)::set(this, "*", "A");
The parameter value “int” identifies the configuration type as an int property.
The set and get methods provide the same API and semantics as the set/get_config_*
functions in uvm_component.
Summary
uvm_config_db
All of the functions in uvm_config_db#(T) are static, so they must be called using
UVM 1.2 Class Reference
197
the :: operator.
CLAss HiERARchY
uvm_resource_db#(T)
uvm_config_db
CLAss DEcLARAtiON
class uvm_config_db#(
type T = int
) extends uvm_resource_db#(T)
MEthOds
get
set
exists
wait_modified
Get the value for field_name in inst_name, using
component cntxt as the starting search point.
Create a new or update an existing configuration setting for
field_name in inst_name from cntxt.
Check if a value for field_name is available in inst_name,
using component cntxt as the starting search point.
Wait for a configuration setting to be set for field_name in
cntxt and inst_name.
MEthOds
get
static function bit get(
uvm_component cntxt,
string inst_name,
string field_name,
inout T value
)
Get the value for field_name in inst_name, using component cntxt as the starting search
point. inst_name is an explicit instance name relative to cntxt and may be an empty
string if the cntxt is the instance that the configuration object applies to. field_name is
the specific field in the scope that is being searched for.
The basic get_config_* methods from uvm_component are mapped to this function as:
get_config_int(...) => uvm_config_db#(uvm_bitstream_t)::get(cntxt,...)
get_config_string(...) => uvm_config_db#(string)::get(cntxt,...)
get_config_object(...) => uvm_config_db#(uvm_object)::get(cntxt,...)
set
static function void set(
uvm_component cntxt,
string inst_name,
string field_name,
T value
)
Create a new or update an existing configuration setting for field_name in inst_name
from cntxt. The setting is made at cntxt, with the full scope of the set being
{cntxt,”.”,~inst_name~}. If cntxt is null then inst_name provides the complete scope
UVM 1.2 Class Reference
198
information of the setting. field_name is the target field. Both inst_name and
field_name may be glob style or regular expression style expressions.
If a setting is made at build time, the cntxt hierarchy is used to determine the setting’s
precedence in the database. Settings from hierarchically higher levels have higher
precedence. Settings from the same level of hierarchy have a last setting wins
semantic. A precedence setting of uvm_resource_base::default_precedence is used for
uvm_top, and each hierarchical level below the top is decremented by 1.
After build time, all settings use the default precedence and thus have a last wins
semantic. So, if at run time, a low level component makes a runtime setting of some
field, that setting will have precedence over a setting from the test level that was made
earlier in the simulation.
The basic set_config_* methods from uvm_component are mapped to this function as:
set_config_int(...) => uvm_config_db#(uvm_bitstream_t)::set(cntxt,...)
set_config_string(...) => uvm_config_db#(string)::set(cntxt,...)
set_config_object(...) => uvm_config_db#(uvm_object)::set(cntxt,...)
exists
static function bit exists(
uvm_component cntxt,
inst_name, string string field_name, spell_chk = bit )
Check if a value for field_name is available in inst_name, using component cntxt as the
starting search point. inst_name is an explicit instance name relative to cntxt and may
be an empty string if the cntxt is the instance that the configuration object applies to. field_name is the specific field in the scope that is being searched for. The spell_chk arg
can be set to 1 to turn spell checking on if it is expected that the field should exist in
the database. The function returns 1 if a config parameter exists and 0 if it doesn’t
exist.
wait_modified
static task wait_modified(
uvm_component cntxt,
string inst_name,
string field_name
)
Wait for a configuration setting to be set for field_name in cntxt and inst_name. The
task blocks until a new configuration setting is applied that effects the specified field.
Types
Summary
Types
uvm_config_int
UVM 1.2 Class Reference
Convenience type for
199
uvm_config_string
uvm_config_object
uvm_config_wrapper
uvm_config_db#(uvm_bitstream_t)
Convenience type for uvm_config_db#(string)
Convenience type for uvm_config_db#(uvm_object)
Convenience type for
uvm_config_db#(uvm_object_wrapper)
uvm_config_int
Convenience type for uvm_config_db#(uvm_bitstream_t)
typedef uvm_config_db#(uvm_bitstream_t) uvm_config_int;
uvm_config_string
Convenience type for uvm_config_db#(string)
typedef uvm_config_db#(string) uvm_config_string;
uvm_config_object
Convenience type for uvm_config_db#(uvm_object)
typedef uvm_config_db#(uvm_object) uvm_config_object;
uvm_config_wrapper
Convenience type for uvm_config_db#(uvm_object_wrapper)
typedef uvm_config_db#(uvm_object_wrapper) uvm_config_wrapper;
uvm_config_db_options
Provides a namespace for managing options for the configuration DB facility. The only
thing allowed in this class is static local data members and static functions for
manipulating and retrieving the value of the data members. The static local data
members represent options and settings that control the behavior of the configuration DB
facility.
Summary
UVM 1.2 Class Reference
200
uvm_config_db_options
Provides a namespace for managing options for the configuration DB facility.
MEthOds
turn_on_tracing
turn_off_tracing
is_tracing
Turn tracing on for the configuration database.
Turn tracing off for the configuration database.
Returns 1 if the tracing facility is on and 0 if it is off.
MEthOds
turn_on_tracing
static function void turn_on_tracing()
Turn tracing on for the configuration database. This causes all reads and writes to the
database to display information about the accesses. Tracing is off by default.
This method is implicitly called by the +UVM_CONFIG_DB_TRACE.
turn_off_tracing
static function void turn_off_tracing()
Turn tracing off for the configuration database.
is_tracing
static function bit is_tracing()
Returns 1 if the tracing facility is on and 0 if it is off.
UVM 1.2 Class Reference
201
11. Synchronization Classes
The UVM provides event and barrier synchronization classes for managing concurrent
processes.
uvm_event#(T) - UVM’s event class augments the SystemVerilog event datatype
with such services as setting callbacks and data delivery.
uvm_barrier - A barrier is used to prevent a pre-configured number of processes
from continuing until all have reached a certain point in simulation.
uvm_event_pool and uvm_barrier_pool - The event and barrier pool classes are
specializations of uvm_object_string_pool #(T) used to store collections of
uvm_event#(uvm_object) and uvm_barriers, respectively, indexed by string name. Each
pool class contains a static, “global” pool instance for sharing across all processes.
uvm_event_callback - The event callback is used to create callback objects that
may be attached to uvm_event#(T).
Summary
Synchronization Classes
UVM 1.2 Class Reference
202
11.1 uvm_event_base
The uvm_event_base class is an abstract wrapper class around the SystemVerilog event
construct. It provides some additional services such as setting callbacks and maintaining
the number of waiters.
Contents
uvm_event_base
uvm_event#(T)
The uvm_event_base class is an abstract wrapper class around
the SystemVerilog event construct.
The uvm_event class is an extension of the abstract
uvm_event_base class.
METHODS
new
function new (
string name = ""
)
Creates a new event object.
wait_on
virtual task wait_on (
bit delta = 0
)
Waits for the event to be activated for the first time.
If the event has already been triggered, this task returns immediately. If delta is set,
the caller will be forced to wait a single delta #0 before returning. This prevents the
caller from returning before previously waiting processes have had a chance to resume.
Once an event has been triggered, it will be remain “on” until the event is reset.
wait_off
virtual task wait_off (
bit delta = 0
)
If the event has already triggered and is “on”, this task waits for the event to be turned
“off” via a call to reset.
If the event has not already been triggered, this task returns immediately. If delta is
set, the caller will be forced to wait a single delta #0 before returning. This prevents the
caller from returning before previously waiting processes have had a chance to resume.
UVM 1.2 Class Reference
203
wait_trigger
virtual task wait_trigger ()
Waits for the event to be triggered.
If one process calls wait_trigger in the same delta as another process calls
uvm_event#(T)::trigger, a race condition occurs. If the call to wait occurs before the
trigger, this method will return in this delta. If the wait occurs after the trigger, this
method will not return until the next trigger, which may never occur and thus cause
deadlock.
wait_ptrigger
virtual task wait_ptrigger ()
Waits for a persistent trigger of the event. Unlike wait_trigger, this views the trigger as
persistent within a given time-slice and thus avoids certain race conditions. If this
method is called after the trigger but within the same time-slice, the caller returns
immediately.
get_trigger_time
virtual function time get_trigger_time ()
Gets the time that this event was last triggered. If the event has not been triggered, or
the event has been reset, then the trigger time will be 0.
is_on
virtual function bit is_on ()
Indicates whether the event has been triggered since it was last reset.
A return of 1 indicates that the event has triggered.
is_off
virtual function bit is_off ()
Indicates whether the event has been triggered or been reset.
A return of 1 indicates that the event has not been triggered.
reset
virtual function void reset (
bit wakeup = 0
)
Resets the event to its off state. If wakeup is set, then all processes currently waiting
for the event are activated before the reset.
UVM 1.2 Class Reference
204
No callbacks are called during a reset.
cancel
virtual function void cancel ()
Decrements the number of waiters on the event.
This is used if a process that is waiting on an event is disabled or activated by some
other means.
get_num_waiters
virtual function int get_num_waiters ()
Returns the number of processes waiting on the event.
uvm_event#(T)
The uvm_event class is an extension of the abstract uvm_event_base class.
The optional parameter T allows the user to define a data type which can be passed
during an event trigger.
Summary
uvm_event#(T)
The uvm_event class is an extension of the abstract uvm_event_base class.
CLASS HIERARcHY
uvm_void
uvm_object
uvm_event_base
uvm_event#(T)
CLASS DEcLARATION
class uvm_event#(
type T = uvm_object
) extends uvm_event_base
METHODS
new
wait_trigger_data
wait_ptrigger_data
trigger
get_trigger_data
add_callback
delete_callback
UVM 1.2 Class Reference
Creates a new event object.
This method calls uvm_event_base::wait_trigger
followed by get_trigger_data.
This method calls uvm_event_base::wait_ptrigger
followed by get_trigger_data.
Triggers the event, resuming all waiting processes.
Gets the data, if any, provided by the last call to
trigger.
Registers a callback object, cb, with this event.
Unregisters the given callback, cb, from this event.
205
METHODS
new
function new (
string name = ""
)
Creates a new event object.
wait_trigger_data
virtual task wait_trigger_data (
output T data
)
This method calls uvm_event_base::wait_trigger followed by get_trigger_data.
wait_ptrigger_data
virtual task wait_ptrigger_data (
output T data
)
This method calls uvm_event_base::wait_ptrigger followed by get_trigger_data.
trigger
virtual function void trigger (
T data = null
)
Triggers the event, resuming all waiting processes.
An optional data argument can be supplied with the enable to provide trigger-specific
information.
get_trigger_data
virtual function T get_trigger_data ()
Gets the data, if any, provided by the last call to trigger.
add_callback
virtual function void add_callback (
uvm_event_callback#(T) cb,
append = 1
bit )
UVM 1.2 Class Reference
206
Registers a callback object, cb, with this event. The callback object may include
pre_trigger and post_trigger functionality. If append is set to 1, the default, cb is added
to the back of the callback list. Otherwise, cb is placed at the front of the callback list.
delete_callback
virtual function void delete_callback (
uvm_event_callback#(T) cb
)
Unregisters the given callback, cb, from this event.
UVM 1.2 Class Reference
207
11.2 uvm_event_callback
The uvm_event_callback class is an abstract class that is used to create callback objects
which may be attached to uvm_event#(T)s. To use, you derive a new class and override
any or both pre_trigger and post_trigger.
Callbacks are an alternative to using processes that wait on events. When a callback is
attached to an event, that callback object’s callback function is called each time the
event is triggered.
Summary
uvm_event_callback
The uvm_event_callback class is an abstract class that is used to create callback
objects which may be attached to uvm_event#(T)s.
CLAss HIERARchY
uvm_void
uvm_object
uvm_event_callback
CLAss DEcLARATION
virtual class uvm_event_callback#(
type T = uvm_object
) extends uvm_object
METhOds
new
pre_trigger
post_trigger
Creates a new callback object.
This callback is called just before triggering the associated
event.
This callback is called after triggering the associated event.
METhOds
new
function new (
string name = ""
)
Creates a new callback object.
pre_trigger
virtual function bit pre_trigger (
uvm_event#(T) e,
T data
)
This callback is called just before triggering the associated event. In a derived class,
override this method to implement any pre-trigger functionality.
UVM 1.2 Class Reference
208
If your callback returns 1, then the event will not trigger and the post-trigger callback is
not called. This provides a way for a callback to prevent the event from triggering.
In the function, e is the uvm_event#(T) that is being triggered, and data is the optional
data associated with the event trigger.
post_trigger
virtual function void post_trigger (
uvm_event#(T) e,
T data
)
This callback is called after triggering the associated event. In a derived class, override
this method to implement any post-trigger functionality.
In the function, e is the uvm_event#(T) that is being triggered, and data is the optional
data associated with the event trigger.
UVM 1.2 Class Reference
209
11.3 uvm_barrier
The uvm_barrier class provides a multiprocess synchronization mechanism. It enables a
set of processes to block until the desired number of processes get to the
synchronization point, at which time all of the processes are released.
Summary
uvm_barrier
The uvm_barrier class provides a multiprocess synchronization mechanism.
CLAss HIERARchY
uvm_void
uvm_object
uvm_barrier
CLAss DEcLARATION
class uvm_barrier extends uvm_object
METhOds
new
wait_for
reset
set_auto_reset
set_threshold
get_threshold
get_num_waiters
cancel
Creates a new barrier object.
Waits for enough processes to reach the barrier before
continuing.
Resets the barrier.
Determines if the barrier should reset itself after the
threshold is reached.
Sets the process threshold.
Gets the current threshold setting for the barrier.
Returns the number of processes currently waiting at the
barrier.
Decrements the waiter count by one.
METhOds
new
function new (
string name
= "",
int threshold = 0
)
Creates a new barrier object.
wait_for
virtual task wait_for()
Waits for enough processes to reach the barrier before continuing.
The number of processes to wait for is set by the set_threshold method.
UVM 1.2 Class Reference
210
reset
virtual function void reset (
bit wakeup = 1
)
Resets the barrier. This sets the waiter count back to zero.
The threshold is unchanged. After reset, the barrier will force processes to wait for the
threshold again.
If the wakeup bit is set, any currently waiting processes will be activated.
set_auto_reset
virtual function void set_auto_reset (
bit value = 1
)
Determines if the barrier should reset itself after the threshold is reached.
The default is on, so when a barrier hits its threshold it will reset, and new processes will
block until the threshold is reached again.
If auto reset is off, then once the threshold is achieved, new processes pass through
without being blocked until the barrier is reset.
set_threshold
virtual function void set_threshold (
int threshold
)
Sets the process threshold.
This determines how many processes must be waiting on the barrier before the
processes may proceed.
Once the threshold is reached, all waiting processes are activated.
If threshold is set to a value less than the number of currently waiting processes, then
the barrier is reset and waiting processes are activated.
get_threshold
virtual function int get_threshold ()
Gets the current threshold setting for the barrier.
get_num_waiters
virtual function int get_num_waiters ()
Returns the number of processes currently waiting at the barrier.
UVM 1.2 Class Reference
211
cancel
virtual function void cancel ()
Decrements the waiter count by one. This is used when a process that is waiting on the
barrier is killed or activated by some other means.
UVM 1.2 Class Reference
212
11.4 Objection Mechanism
The following classes define the objection mechanism and end-of-test functionality, which
is based on uvm_objection.
Contents
Objection Mechanism
The following classes define the objection mechanism
and end-of-test functionality, which is based on
uvm_objection.
uvm_objection
Objections provide a facility for coordinating status
information between two or more participating
components, objects, and even module-based IP.
The uvm_objection is the callback type that defines the
callback implementations for an objection callback.
uvm_objection_callback
uvm_objection
Objections provide a facility for coordinating status information between two or more
participating components, objects, and even module-based IP.
Tracing of objection activity can be turned on to follow the activity of the objection
mechanism. It may be turned on for a specific objection instance with
uvm_objection::trace_mode, or it can be set for all objections from the command line
using the option +UVM_OBJECTION_TRACE.
Summary
uvm_objection
Objections provide a facility for coordinating status information between two or
more participating components, objects, and even module-based IP.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_objection
CLAss DEcLARATIoN
class uvm_objection extends uvm_report_object
new
trace_mode
OBJEcTIoN CoNTRoL
set_propagate_mode
get_propagate_mode
raise_objection
drop_objection
UVM 1.2 Class Reference
Creates a new objection instance.
Set or get the trace mode for the objection object.
Sets the propagation mode for this objection.
Returns the propagation mode for this objection.
Raises the number of objections for the source
object by count, which defaults to 1.
Drops the number of objections for the source object
by count, which defaults to 1.
213
clear
set_drain_time
CALLBAcK HooKs
raised
dropped
all_dropped
OBJEcTIoN STATUs
get_objectors
wait_for
get_objection_count
get_objection_total
get_drain_time
display_objections
Immediately clears the objection state.
Sets the drain time on the given object to drain.
Objection callback that is called when a
raise_objection has reached obj.
Objection callback that is called when a
drop_objection has reached obj.
Objection callback that is called when a
drop_objection has reached obj, and the total count
for obj goes to zero.
Returns the current list of objecting objects (objects
that raised an objection but have not dropped it).
Waits for the raised, dropped, or all_dropped event
to occur in the given obj.
Returns the current number of objections raised by
the given object.
Returns the current number of objections raised by
the given object and all descendants.
Returns the current drain time set for the given
object (default: 0 ns).
Displays objection information about the given
object.
new
function new(
string name = ""
)
Creates a new objection instance. Accesses the command line argument
+UVM_OBJECTION_TRACE to turn tracing on for all objection objects.
trace_mode
function bit trace_mode (
int mode = -1
)
Set or get the trace mode for the objection object. If no argument is specified (or an
argument other than 0 or 1) the current trace mode is unaffected. A trace_mode of 0
turns tracing off. A trace mode of 1 turns tracing on. The return value is the mode prior
to being reset.
OBJEcTIoN CoNTRoL
set_propagate_mode
function void set_propagate_mode (
bit prop_mode
)
Sets the propagation mode for this objection.
By default, objections support hierarchical propagation for components. For example, if
UVM 1.2 Class Reference
214
we have the following basic component tree:
uvm_top.parent.child
Any objections raised by ‘child’ would get propagated down to parent, and then to
uvm_test_top. Resulting in the following counts and totals:
| count | total |
uvm_top.parent.child |
1 |
1 |
uvm_top.parent
|
0 |
1 |
uvm_top
|
0 |
1 |
While propagations such as these can be useful, if they are unused by the testbench then
they are simply an unnecessary performance hit. If the testbench is not going to use
this functionality, then the performance can be improved by setting the propagation
mode to 0.
When propagation mode is set to 0, all intermediate callbacks between the source and
top will be skipped. This would result in the following counts and totals for the above
objection:
| count | total |
uvm_top.parent.child |
1 |
1 |
uvm_top.parent
|
0 |
0 |
uvm_top
|
0 |
1 |
Since the propagation mode changes the behavior of the objection, it can only be safely
changed if there are no objections raised or draining. Any attempts to change the mode
while objections are raised or draining will result in an error.
get_propagate_mode
function bit get_propagate_mode()
Returns the propagation mode for this objection.
raise_objection
virtual function void raise_objection (
uvm_object obj
= null,
string description = "",
int count
= 1
)
Raises the number of objections for the source object by count, which defaults to 1. The
object is usually the this handle of the caller. If object is not specified or null, the
implicit top-level component, uvm_root, is chosen.
Raising an objection causes the following.
The source and total objection counts for object are increased by count. description is a string that marks a specific objection and is used in tracing/debug.
The objection’s raised virtual method is called, which calls the
UVM 1.2 Class Reference
215
uvm_component::raised method for all of the components up the hierarchy.
drop_objection
virtual function void drop_objection (
uvm_object obj
= null,
string description = "",
int count
= 1
)
Drops the number of objections for the source object by count, which defaults to 1. The
object is usually the this handle of the caller. If object is not specified or null, the
implicit top-level component, uvm_root, is chosen.
Dropping an objection causes the following.
The source and total objection counts for object are decreased by count. It is an
error to drop the objection count for object below zero.
The objection’s dropped virtual method is called, which calls the
uvm_component::dropped method for all of the components up the hierarchy.
If the total objection count has not reached zero for object, then the drop is
propagated up the object hierarchy as with raise_objection. Then, each object in
the hierarchy will have updated their source counts--objections that they
originated--and total counts--the total number of objections by them and all their
descendants.
If the total objection count reaches zero, propagation up the hierarchy is deferred until a
configurable drain-time has passed and the uvm_component::all_dropped callback for
the current hierarchy level has returned. The following process occurs for each instance
up the hierarchy from the source caller:
A process is forked in a non-blocking fashion, allowing the drop call to return. The
forked process then does the following:
If a drain time was set for the given object, the process waits for that amount of
time.
The objection’s all_dropped virtual method is called, which calls the
uvm_component::all_dropped method (if object is a component).
The process then waits for the all_dropped callback to complete.
After the drain time has elapsed and all_dropped callback has completed,
propagation of the dropped objection to the parent proceeds as described in
raise_objection, except as described below.
If a new objection for this object or any of its descendants is raised during the drain
time or during execution of the all_dropped callback at any point, the hierarchical chain
described above is terminated and the dropped callback does not go up the hierarchy. The raised objection will propagate up the hierarchy, but the number of raised
propagated up is reduced by the number of drops that were pending waiting for the
all_dropped/drain time completion. Thus, if exactly one objection caused the count to go
to zero, and during the drain exactly one new objection comes in, no raises or drops are
propagated up the hierarchy,
As an optimization, if the object has no set drain-time and no registered callbacks, the
forked process can be skipped and propagation proceeds immediately to the parent as
described.
clear
UVM 1.2 Class Reference
216
virtual function void clear(
uvm_object obj = null
)
Immediately clears the objection state. All counts are cleared and the any processes
waiting on a call to wait_for(UVM_ALL_DROPPED, uvm_top) are released.
The caller, if a uvm_object-based object, should pass its ‘this’ handle to the obj
argument to document who cleared the objection. Any drain_times set by the user are
not affected.
set_drain_time
Sets the drain time on the given object to drain.
The drain time is the amount of time to wait once all objections have been dropped
before calling the all_dropped callback and propagating the objection to the parent.
If a new objection for this object or any of its descendants is raised during the drain
time or during execution of the all_dropped callbacks, the drain_time/all_dropped
execution is terminated.
CALLBAcK HooKs
raised
virtual function void raised (
uvm_object obj,
uvm_object source_obj,
string description,
int count
)
Objection callback that is called when a raise_objection has reached obj. The default
implementation calls uvm_component::raised.
dropped
virtual function void dropped (
uvm_object obj,
uvm_object source_obj,
string description,
int count
)
Objection callback that is called when a drop_objection has reached obj. The default
implementation calls uvm_component::dropped.
all_dropped
virtual task all_dropped (
uvm_object obj,
uvm_object source_obj,
string description,
int count
)
UVM 1.2 Class Reference
217
Objection callback that is called when a drop_objection has reached obj, and the total
count for obj goes to zero. This callback is executed after the drain time associated with
obj. The default implementation calls uvm_component::all_dropped.
OBJEcTIoN STATUs
get_objectors
function void get_objectors(
ref uvm_object list[$]
)
Returns the current list of objecting objects (objects that raised an objection but have
not dropped it).
wait_for
task wait_for(
uvm_objection_event objt_event, obj
= null
uvm_object )
Waits for the raised, dropped, or all_dropped event to occur in the given obj. The task
returns after all corresponding callbacks for that event have been executed.
get_objection_count
function int get_objection_count (
uvm_object obj = null
)
Returns the current number of objections raised by the given object.
get_objection_total
function int get_objection_total (
uvm_object obj = null
)
Returns the current number of objections raised by the given object and all descendants.
get_drain_time
function time get_drain_time (
uvm_object obj = null
)
Returns the current drain time set for the given object (default: 0 ns).
display_objections
UVM 1.2 Class Reference
218
function void display_objections(
uvm_object obj
= null,
bit show_header = 1
)
Displays objection information about the given object. If object is not specified or null,
the implicit top-level component, uvm_root, is chosen. The show_header argument
allows control of whether a header is output.
uvm_objection_callback
The uvm_objection is the callback type that defines the callback implementations for an
objection callback. A user uses the callback type uvm_objection_cbs_t to add callbacks
to specific objections.
For example
class my_objection_cb extends uvm_objection_callback;
function new(string name);
super.new(name);
endfunction
virtual function void raised (uvm_objection objection, uvm_object obj,
uvm_object source_obj, string description, int count);
`uvm_info("RAISED","%0t: Objection %s: Raised for %s", $time,
objection.get_name(),
obj.get_full_name());
endfunction
endclass
...
initial begin
my_objection_cb cb = new("cb");
uvm_objection_cbs_t::add(null, cb); //typewide callback
end
Summary
uvm_objection_callback
The uvm_objection is the callback type that defines the callback implementations
for an objection callback.
CLAss HIERARchY
uvm_void
uvm_object
uvm_callback
uvm_objection_callback
CLAss DEcLARATIoN
class uvm_objection_callback extends uvm_callback
METhods
raised
dropped
all_dropped
UVM 1.2 Class Reference
Objection raised callback function.
Objection dropped callback function.
Objection all_dropped callback function.
219
METhods
raised
virtual function void raised (
uvm_objection objection,
uvm_object obj,
uvm_object source_obj,
string description,
int count
)
Objection raised callback function. Called by uvm_objection::raised.
dropped
virtual function void dropped (
uvm_objection objection,
uvm_object obj,
uvm_object source_obj,
string description,
int count
)
Objection dropped callback function. Called by uvm_objection::dropped.
all_dropped
virtual task all_dropped (
uvm_objection objection,
uvm_object obj,
uvm_object source_obj,
string description,
int count
)
Objection all_dropped callback function. Called by uvm_objection::all_dropped.
UVM 1.2 Class Reference
220
11.5 uvm_heartbeat
Heartbeats provide a way for environments to easily ensure that their descendants are
alive. A uvm_heartbeat is associated with a specific objection object. A component that
is being tracked by the heartbeat object must raise (or drop) the synchronizing objection
during the heartbeat window.
The uvm_heartbeat object has a list of participating objects. The heartbeat can be
configured so that all components (UVM_ALL_ACTIVE), exactly one (UVM_ONE_ACTIVE),
or any component (UVM_ANY_ACTIVE) must trigger the objection in order to satisfy the
heartbeat condition.
Summary
uvm_heartbeat
Heartbeats provide a way for environments to easily ensure that their
descendants are alive.
METHODs
new
set_mode
set_heartbeat
add
remove
start
stop
Creates a new heartbeat instance associated with cntxt.
Sets or retrieves the heartbeat mode.
Sets up the heartbeat event and assigns a list of objects to
watch.
Add a single component to the set of components to be
monitored.
Remove a single component to the set of components being
monitored.
Starts the heartbeat monitor.
Stops the heartbeat monitor.
METHODs
new
function new(
string name,
uvm_component cntxt,
uvm_objection objection = null
)
Creates a new heartbeat instance associated with cntxt. The context is the hierarchical
location that the heartbeat objections will flow through and be monitored at. The
objection associated with the heartbeat is optional, if it is left null but it must be set
before the heartbeat monitor will activate.
uvm_objection myobjection = new("myobjection"); //some shared objection
class myenv extends uvm_env;
uvm_heartbeat hb = new("hb", this, myobjection);
...
endclass
UVM 1.2 Class Reference
221
set_mode
function uvm_heartbeat_modes set_mode (
uvm_heartbeat_modes mode = UVM_NO_HB_MODE
)
Sets or retrieves the heartbeat mode. The current value for the heartbeat mode is
returned. If an argument is specified to change the mode then the mode is changed to
the new value.
set_heartbeat
function void set_heartbeat (
uvm_event#(uvm_object) e,
ref uvm_component comps[$]
)
Sets up the heartbeat event and assigns a list of objects to watch. The monitoring is
started as soon as this method is called. Once the monitoring has been started with a
specific event, providing a new monitor event results in an error. To change trigger
events, you must first stop the monitor and then start with a new event trigger.
If the trigger event e is null and there was no previously set trigger event, then the
monitoring is not started. Monitoring can be started by explicitly calling start.
add
function void add (
uvm_component comp
)
Add a single component to the set of components to be monitored. This does not cause
monitoring to be started. If monitoring is currently active then this component will be
immediately added to the list of components and will be expected to participate in the
currently active event window.
remove
function void remove (
uvm_component comp
)
Remove a single component to the set of components being monitored. Monitoring is not
stopped, even if the last component has been removed (an explicit stop is required).
start
function void start (
uvm_event#(uvm_object) e = null
)
Starts the heartbeat monitor. If e is null then whatever event was previously set is
used. If no event was previously set then a warning is issued. It is an error if the
monitor is currently running and e is specifying a different trigger event from the current
event.
UVM 1.2 Class Reference
222
stop
function void stop ()
Stops the heartbeat monitor. Current state information is reset so that if start is called
again the process will wait for the first event trigger to start the monitoring.
UVM 1.2 Class Reference
223
11.6 Callbacks Classes
This section defines the classes used for callback registration, management, and userdefined callbacks.
Contents
Callbacks
Classes
This section defines the classes used for callback registration,
management, and user-defined callbacks.
uvm_callbacks
#(T,CB)
The uvm_callbacks class provides a base class for
implementing callbacks, which are typically used to modify or
augment component behavior without changing the
component class.
uvm_callback_iter The uvm_callback_iter class is an iterator class for iterating
over callback queues of a specific callback type.
uvm_callback
The uvm_callback class is the base class for user-defined
callback classes.
uvm_callbacks #(T,CB)
The uvm_callbacks class provides a base class for implementing callbacks, which are
typically used to modify or augment component behavior without changing the
component class. To work effectively, the developer of the component class defines a set
of “hook” methods that enable users to customize certain behaviors of the component in
a manner that is controlled by the component developer. The integrity of the
component’s overall behavior is intact, while still allowing certain customizable actions by
the user.
To enable compile-time type-safety, the class is parameterized on both the user-defined
callback interface implementation as well as the object type associated with the callback. The object type-callback type pair are associated together using the `uvm_register_cb
macro to define a valid pairing; valid pairings are checked when a user attempts to add a
callback to an object.
To provide the most flexibility for end-user customization and reuse, it is recommended
that the component developer also define a corresponding set of virtual method hooks in
the component itself. This affords users the ability to customize via inheritance/factory
overrides as well as callback object registration. The implementation of each virtual
method would provide the default traversal algorithm for the particular callback being
called. Being virtual, users can define subtypes that override the default algorithm,
perform tasks before and/or after calling super.method to execute any registered
callbacks, or to not call the base implementation, effectively disabling that particular
hook. A demonstration of this methodology is provided in an example included in the kit.
Summary
uvm_callbacks #(T,CB)
The uvm_callbacks class provides a base class for implementing callbacks, which
are typically used to modify or augment component behavior without changing
the component class.
CLAss HIERARchY
UVM 1.2 Class Reference
224
uvm_typed_callbacks#(T)
uvm_callbacks#(T,CB)
CLAss DEcLARAtION
class uvm_callbacks #(
type T = uvm_object,
type CB = uvm_callback
) extends uvm_typed_callbacks#(T)
T
This type parameter specifies the base object type with
which the CB callback objects will be registered.
This type parameter specifies the base callback type that
will be managed by this callback class.
CB
Add/dELEtE
INtERFAcE
add
add_by_name
delete
delete_by_name
ItERAtOR INtERFAcE
get_first
get_last
get_next
get_prev
DEbUG
display
Registers the given callback object, cb, with the given obj
handle.
Registers the given callback object, cb, with one or more
uvm_components.
Deletes the given callback object, cb, from the queue
associated with the given obj handle.
Removes the given callback object, cb, associated with
one or more uvm_component callback queues.
This set of functions provide an iterator interface for
callback queues.
Returns the first enabled callback of type CB which
resides in the queue for obj.
Returns the last enabled callback of type CB which
resides in the queue for obj.
Returns the next enabled callback of type CB which
resides in the queue for obj, using itr as the starting
point.
Returns the previous enabled callback of type CB which
resides in the queue for obj, using itr as the starting
point.
This function displays callback information for obj.
T
This type parameter specifies the base object type with which the CB callback objects will
be registered. This object must be a derivative of uvm_object.
CB
This type parameter specifies the base callback type that will be managed by this
callback class. The callback type is typically a interface class, which defines one or more
virtual method prototypes that users can override in subtypes. This type must be a
derivative of uvm_callback.
Add/ dELEtE
INtERFAcE
add
UVM 1.2 Class Reference
225
static function void add(
T obj,
uvm_callback cb,
uvm_apprepend ordering = UVM_APPEND
)
Registers the given callback object, cb, with the given obj handle. The obj handle can be
null, which allows registration of callbacks without an object context. If ordering is
UVM_APPEND (default), the callback will be executed after previously added callbacks,
else the callback will be executed ahead of previously added callbacks. The cb is the
callback handle; it must be non-null, and if the callback has already been added to the
object instance then a warning is issued. Note that the CB parameter is optional. For
example, the following are equivalent:
uvm_callbacks#(my_comp)::add(comp_a, cb);
uvm_callbacks#(my_comp, my_callback)::add(comp_a,cb);
add_by_name
static function void add_by_name(
string name,
uvm_callback cb,
uvm_component root,
uvm_apprepend ordering = UVM_APPEND
)
Registers the given callback object, cb, with one or more uvm_components. The
components must already exist and must be type T or a derivative. As with add the CB
parameter is optional. root specifies the location in the component hierarchy to start the
search for name. See uvm_root::find_all for more details on searching by name.
delete
static function void delete(
T obj,
uvm_callback cb
)
Deletes the given callback object, cb, from the queue associated with the given obj
handle. The obj handle can be null, which allows de-registration of callbacks without an
object context. The cb is the callback handle; it must be non-null, and if the callback
has already been removed from the object instance then a warning is issued. Note that
the CB parameter is optional. For example, the following are equivalent:
uvm_callbacks#(my_comp)::delete(comp_a, cb);
uvm_callbacks#(my_comp, my_callback)::delete(comp_a,cb);
delete_by_name
static function void delete_by_name(
string name,
uvm_callback cb,
uvm_component root
)
UVM 1.2 Class Reference
226
Removes the given callback object, cb, associated with one or more uvm_component
callback queues. As with delete the CB parameter is optional. root specifies the location
in the component hierarchy to start the search for name. See uvm_root::find_all for
more details on searching by name.
ItERAtOR INtERFAcE
This set of functions provide an iterator interface for callback queues. A facade class,
uvm_callback_iter is also available, and is the generally preferred way to iterate over
callback queues.
get_first
static function CB get_first (
ref int itr,
input T obj
)
Returns the first enabled callback of type CB which resides in the queue for obj. If obj is
null then the typewide queue for T is searched. itr is the iterator; it will be updated with
a value that can be supplied to get_next to get the next callback object.
If the queue is empty then null is returned.
The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator
interface.
get_last
static function CB get_last (
ref int itr,
input T obj
)
Returns the last enabled callback of type CB which resides in the queue for obj. If obj is
null then the typewide queue for T is searched. itr is the iterator; it will be updated with
a value that can be supplied to get_prev to get the previous callback object.
If the queue is empty then null is returned.
The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator
interface.
get_next
static function CB get_next (
ref int itr,
input T obj
)
Returns the next enabled callback of type CB which resides in the queue for obj, using itr
as the starting point. If obj is null then the typewide queue for T is searched. itr is the
iterator; it will be updated with a value that can be supplied to get_next to get the next
callback object.
If no more callbacks exist in the queue, then null is returned. get_next will continue to
UVM 1.2 Class Reference
227
return null in this case until get_first or get_last has been used to reset the iterator.
The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator
interface.
get_prev
static function CB get_prev (
ref int itr,
input T obj
)
Returns the previous enabled callback of type CB which resides in the queue for obj,
using itr as the starting point. If obj is null then the typewide queue for T is searched. itr is the iterator; it will be updated with a value that can be supplied to get_prev to get
the previous callback object.
If no more callbacks exist in the queue, then null is returned. get_prev will continue to
return null in this case until get_first or get_last has been used to reset the iterator.
The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator
interface.
DEbUG
display
static function void display(
T obj = null
)
This function displays callback information for obj. If obj is null, then it displays callback
information for all objects of type T, including typewide callbacks.
uvm_callback_iter
The uvm_callback_iter class is an iterator class for iterating over callback queues of a
specific callback type. The typical usage of the class is:
uvm_callback_iter#(mycomp,mycb) iter = new(this);
for(mycb cb = iter.first(); cb != null; cb = iter.next())
cb.dosomething();
The callback iteration macros, `uvm_do_callbacks and `uvm_do_callbacks_exit_on
provide a simple method for iterating callbacks and executing the callback methods.
Summary
uvm_callback_iter
UVM 1.2 Class Reference
228
The uvm_callback_iter class is an iterator class for iterating over callback queues
of a specific callback type.
CLAss DEcLARAtION
class uvm_callback_iter#(
type T = uvm_object,
type CB = uvm_callback
)
MEthOds
new
first
last
next
prev
get_cb
Creates a new callback iterator object.
Returns the first valid (enabled) callback of the callback type (or a
derivative) that is in the queue of the context object.
Returns the last valid (enabled) callback of the callback type (or a
derivative) that is in the queue of the context object.
Returns the next valid (enabled) callback of the callback type (or a
derivative) that is in the queue of the context object.
Returns the previous valid (enabled) callback of the callback type
(or a derivative) that is in the queue of the context object.
Returns the last callback accessed via a first() or next() call.
MEthOds
new
function new(
T obj
)
Creates a new callback iterator object. It is required that the object context be provided.
first
function CB first()
Returns the first valid (enabled) callback of the callback type (or a derivative) that is in
the queue of the context object. If the queue is empty then null is returned.
last
function CB last()
Returns the last valid (enabled) callback of the callback type (or a derivative) that is in
the queue of the context object. If the queue is empty then null is returned.
next
function CB next()
Returns the next valid (enabled) callback of the callback type (or a derivative) that is in
the queue of the context object. If there are no more valid callbacks in the queue, then
null is returned.
UVM 1.2 Class Reference
229
prev
function CB prev()
Returns the previous valid (enabled) callback of the callback type (or a derivative) that is
in the queue of the context object. If there are no more valid callbacks in the queue,
then null is returned.
get_cb
function CB get_cb()
Returns the last callback accessed via a first() or next() call.
uvm_callback
The uvm_callback class is the base class for user-defined callback classes. Typically, the
component developer defines an application-specific callback class that extends from this
class. In it, he defines one or more virtual methods, called a callback interface, that
represent the hooks available for user override.
Methods intended for optional override should not be declared pure. Usually, all the
callback methods are defined with empty implementations so users have the option of
overriding any or all of them.
The prototypes for each hook method are completely application specific with no
restrictions.
Summary
uvm_callback
The uvm_callback class is the base class for user-defined callback classes.
CLAss HIERARchY
uvm_void
uvm_object
uvm_callback
CLAss DEcLARAtION
class uvm_callback extends uvm_object
MEthOds
new
callback_mode
is_enabled
get_type_name
UVM 1.2 Class Reference
Creates a new uvm_callback object, giving it an optional
name.
Enable/disable callbacks (modeled like rand_mode and
constraint_mode).
Returns 1 if the callback is enabled, 0 otherwise.
Returns the type name of this callback object.
230
MEthOds
new
function new(
string name = "uvm_callback"
)
Creates a new uvm_callback object, giving it an optional name.
callback_mode
function bit callback_mode(
int on = -1
)
Enable/disable callbacks (modeled like rand_mode and constraint_mode).
is_enabled
function bit is_enabled()
Returns 1 if the callback is enabled, 0 otherwise.
get_type_name
virtual function string get_type_name()
Returns the type name of this callback object.
UVM 1.2 Class Reference
231
12. Container Classes
The container classes are type parameterized data structures. The uvm_queue #(T) class
implements a queue datastructure similar to the SystemVerilog queue construct. And
the uvm_pool #(KEY,T) class implements a pool datastructure similar to the
SystemVerilog associative array. The class based data structures allow the objects to be
shared by reference; for example, a copy of a uvm_pool #(KEY,T) object will copy just
the class handle instead of the entire associative array.
Summary
Container Classes
The container classes are type parameterized data structures.
UVM 1.2 Class Reference
232
12.1 Pool Classes
This section defines the uvm_pool #(KEY, T) class and derivative.
Contents
Pool Classes
This section defines the uvm_pool #(KEY, T) class and
derivative.
uvm_pool #(KEY,T)
uvm_object_string_pool
#(T)
Implements a class-based dynamic associative array.
This provides a specialization of the generic uvm_pool
#(KEY,T) class for an associative array of uvm_objectbased objects indexed by string.
uvm_pool #(KEY,T)
Implements a class-based dynamic associative array. Allows sparse arrays to be
allocated on demand, and passed and stored by reference.
Summary
uvm_pool #(KEY,T)
Implements a class-based dynamic associative array.
CLAss HIeRARchy
uvm_void
uvm_object
uvm_pool#(KEY,T)
CLAss DecLARAtION
class uvm_pool #(
type KEY = int,
T = uvm_void
) extends uvm_object
MethOds
new
get_global_pool
get_global
get
add
num
delete
exists
first
last
next
prev
UVM 1.2 Class Reference
Creates a new pool with the given name.
Returns the singleton global pool for the item type, T.
Returns the specified item instance from the global item
pool.
Returns the item with the given key.
Adds the given (key, item) pair to the pool.
Returns the number of uniquely keyed items stored in the
pool.
Removes the item with the given key from the pool.
Returns 1 if an item with the given key exists in the pool,
0 otherwise.
Returns the key of the first item stored in the pool.
Returns the key of the last item stored in the pool.
Returns the key of the next item in the pool.
Returns the key of the previous item in the pool.
233
MethOds
new
function new (
string name = ""
)
Creates a new pool with the given name.
get_global_pool
static function this_type get_global_pool ()
Returns the singleton global pool for the item type, T.
This allows items to be shared amongst components throughout the verification
environment.
get_global
static function T get_global (
KEY key
)
Returns the specified item instance from the global item pool.
get
virtual function T get (
KEY key
)
Returns the item with the given key.
If no item exists by that key, a new item is created with that key and returned.
add
virtual function void add (
KEY key,
T item
)
Adds the given (key, item) pair to the pool. If an item already exists at the given key it
is overwritten with the new item.
num
virtual function int num ()
UVM 1.2 Class Reference
234
Returns the number of uniquely keyed items stored in the pool.
delete
virtual function void delete (
KEY key
)
Removes the item with the given key from the pool.
exists
virtual function int exists (
KEY key
)
Returns 1 if an item with the given key exists in the pool, 0 otherwise.
first
virtual function int first (
ref KEY key
)
Returns the key of the first item stored in the pool.
If the pool is empty, then key is unchanged and 0 is returned.
If the pool is not empty, then key is key of the first item and 1 is returned.
last
virtual function int last (
ref KEY key
)
Returns the key of the last item stored in the pool.
If the pool is empty, then 0 is returned and key is unchanged.
If the pool is not empty, then key is set to the last key in the pool and 1 is returned.
next
virtual function int next (
ref KEY key
)
Returns the key of the next item in the pool.
If the input key is the last key in the pool, then key is left unchanged and 0 is returned.
If a next key is found, then key is updated with that key and 1 is returned.
UVM 1.2 Class Reference
235
prev
virtual function int prev (
ref KEY key
)
Returns the key of the previous item in the pool.
If the input key is the first key in the pool, then key is left unchanged and 0 is returned.
If a previous key is found, then key is updated with that key and 1 is returned.
uvm_object_string_pool #(T)
This provides a specialization of the generic uvm_pool #(KEY,T) class for an associative
array of uvm_object-based objects indexed by string. Specializations of this class include
the uvm_event_pool (a uvm_object_string_pool storing uvm_event#(uvm_object)) and
uvm_barrier_pool (a uvm_obejct_string_pool storing uvm_barrier).
Summary
uvm_object_string_pool #(T)
This provides a specialization of the generic uvm_pool #(KEY,T) class for an
associative array of uvm_object-based objects indexed by string.
CLAss HIeRARchy
uvm_pool#(string,T)
uvm_object_string_pool#(T)
CLAss DecLARAtION
class uvm_object_string_pool #(
type T = uvm_object
) extends uvm_pool #(string,T)
MethOds
new
get_type_name
get_global_pool
get_global
get
delete
Creates a new pool with the given name.
Returns the type name of this object.
Returns the singleton global pool for the item type, T.
Returns the specified item instance from the global item
pool.
Returns the object item at the given string key.
Removes the item with the given string key from the pool.
MethOds
new
function new (
string name = ""
)
UVM 1.2 Class Reference
236
Creates a new pool with the given name.
get_type_name
virtual function string get_type_name()
Returns the type name of this object.
get_global_pool
static function this_type get_global_pool ()
Returns the singleton global pool for the item type, T.
This allows items to be shared amongst components throughout the verification
environment.
get_global
static function T get_global (
string key
)
Returns the specified item instance from the global item pool.
get
virtual function T get (
string key
)
Returns the object item at the given string key.
If no item exists by the given key, a new item is created for that key and returned.
delete
virtual function void delete (
string key
)
Removes the item with the given string key from the pool.
UVM 1.2 Class Reference
237
12.2 uvm_queue #(T)
Implements a class-based dynamic queue. Allows queues to be allocated on demand,
and passed and stored by reference.
Summary
uvm_queue #(T)
Implements a class-based dynamic queue.
CLAss HIERARchY
uvm_void
uvm_object
uvm_queue#(T)
CLAss DEcLARAtION
class uvm_queue #(
type T = int
) extends uvm_object
MEthOds
new
get_global_queue
get_global
get
size
insert
delete
pop_front
pop_back
push_front
push_back
Creates a new queue with the given name.
Returns the singleton global queue for the item type, T.
Returns the specified item instance from the global item
queue.
Returns the item at the given index.
Returns the number of items stored in the queue.
Inserts the item at the given index in the queue.
Removes the item at the given index from the queue; if
index is not provided, the entire contents of the queue
are deleted.
Returns the first element in the queue (index=0), or null
if the queue is empty.
Returns the last element in the queue (index=size()-1),
or null if the queue is empty.
Inserts the given item at the front of the queue.
Inserts the given item at the back of the queue.
MEthOds
new
function new (
string name = ""
)
Creates a new queue with the given name.
get_global_queue
static function this_type get_global_queue ()
UVM 1.2 Class Reference
238
Returns the singleton global queue for the item type, T.
This allows items to be shared amongst components throughout the verification
environment.
get_global
static function T get_global (
int index
)
Returns the specified item instance from the global item queue.
get
virtual function T get (
int index
)
Returns the item at the given index.
If no item exists by that key, a new item is created with that key and returned.
size
virtual function int size ()
Returns the number of items stored in the queue.
insert
virtual function void insert (
int index,
T item
)
Inserts the item at the given index in the queue.
delete
virtual function void delete (
int index = -1
)
Removes the item at the given index from the queue; if index is not provided, the entire
contents of the queue are deleted.
pop_front
virtual function T pop_front()
Returns the first element in the queue (index=0), or null if the queue is empty.
UVM 1.2 Class Reference
239
pop_back
virtual function T pop_back()
Returns the last element in the queue (index=size()-1), or null if the queue is empty.
push_front
virtual function void push_front(
T item
)
Inserts the given item at the front of the queue.
push_back
virtual function void push_back(
T item
)
Inserts the given item at the back of the queue.
UVM 1.2 Class Reference
240
13. TLM Interfaces
The UVM TLM library defines several abstract, transaction-level interfaces and the ports
and exports that facilitate their use. Each TLM interface consists of one or more methods
used to transport data, typically whole transactions (objects) at a time. Component
designs that use TLM ports and exports to communicate are inherently more reusable,
interoperable, and modular.
The UVM TLM library specifies the required behavior (semantic) of each interface
method. Classes (components) that implement a TLM interface must meet the specified
semantic.
Summary
TLM Interfaces
The UVM TLM library defines several abstract, transaction-level interfaces and the
ports and exports that facilitate their use.
TLM1
TLM2
Sequencer
Port
Analysis
The TLM1 ports provide blocking and non-blocking pass-by-value
transaction-level interfaces.
The TLM2 sockets provide blocking and non-blocking transactionlevel interfaces with well-defined completion semantics.
A push or pull port, with well-defined completion semantics.
The analysis interface is used to perform non-blocking broadcasts
of transactions to connected components.
TLM1
The TLM1 ports provide blocking and non-blocking pass-by-value transaction-level
interfaces. The semantics of these interfaces are limited to message passing.
TLM2
The TLM2 sockets provide blocking and non-blocking transaction-level interfaces with
well-defined completion semantics.
Sequencer Port
A push or pull port, with well-defined completion semantics. It is used to connect
sequencers with drivers and layering sequences.
Analysis
The analysis interface is used to perform non-blocking broadcasts of transactions to
connected components. It is typically used by such components as monitors to publish
transactions observed on a bus to its subscribers, which are typically scoreboards and
response/coverage collectors.
UVM 1.2 Class Reference
241
14. TLM1 Interfaces, Ports, Exports and Transport
Interfaces
Each TLM1 interface is either blocking, non-blocking, or a combination of these two.
blocking
A blocking interface conveys transactions in blocking fashion; its
methods do not return until the transaction has been
successfully sent or retrieved. Because delivery may consume
time to complete, the methods in such an interface are
declared as tasks.
non-blocking
A non-blocking interface attempts to convey a transaction
without consuming simulation time. Its methods are declared
as functions. Because delivery may fail (e.g. the target
component is busy and cannot accept the request), the
methods may return with failed status.
combination
A combination interface contains both the blocking and nonblocking variants. In SystemC, combination interfaces are
defined through multiple inheritance. Because SystemVerilog
does not support multiple inheritance, the UVM emulates
hierarchical interfaces via a common base class and interface
mask.
Like their SystemC counterparts, the UVM’s TLM port and export implementations allow
connections between ports whose interfaces are not an exact match. For example, a
uvm_blocking_get_port can be connected to any port, export or imp port that provides at
the least an implementation of the blocking_get interface, which includes the uvm_get_*
ports and exports, uvm_blocking_get_peek_* ports and exports, and uvm_get_peek_*
ports and exports.
The sections below provide and overview of the unidirectional and bidirectional TLM
interfaces, ports, and exports.
Summary
TLM1 Interfaces, Ports, Exports and Transport Interfaces
Each TLM1 interface is either blocking, non-blocking, or a combination of these
two.
UNiDiReCtiONAl
INteRFACes &
PORts
Put
Get and
Peek
Ports,
Exports,
and Imps
BiDiReCtiONAl
INteRFACes &
PORts
Transport
Master and
Slave
UVM 1.2 Class Reference
The unidirectional TLM interfaces consist of blocking, nonblocking, and combined blocking and non-blocking variants of
the put, get and peek interfaces, plus a non-blocking analysis
interface.
The put interfaces are used to send, or put, transactions to
other components.
The get interfaces are used to retrieve transactions from
other components.
The UVM provides unidirectional ports, exports, and
implementation ports for connecting your components via the
TLM interfaces.
The bidirectional interfaces consist of blocking, non-blocking,
and combined blocking and non-blocking variants of the
transport, master, and slave interfaces.
The transport interface sends a request transaction and
returns a response transaction in a single task call, thereby
enforcing an in-order execution semantic.
The primitive, unidirectional put, get, and peek interfaces are
combined to form bidirectional master and slave interfaces.
242
Ports,
Exports,
and Imps
UsAGe
The UVM provides bidirectional ports, exports, and
implementation ports for connecting your components via the
TLM interfaces.
This example illustrates basic TLM connectivity using the
blocking put interface.
UNiDiReCtiONAl INteRFACes & PORts
The unidirectional TLM interfaces consist of blocking, non-blocking, and combined
blocking and non-blocking variants of the put, get and peek interfaces, plus a nonblocking analysis interface.
Put
The put interfaces are used to send, or put, transactions to other components. Successful completion of a put guarantees its delivery, not execution.
Get and Peek
The get interfaces are used to retrieve transactions from other components. The peek
interfaces are used for the same purpose, except the retrieved transaction is not
consumed; successive calls to peek will return the same object. Combined get_peek
interfaces are also defined.
UVM 1.2 Class Reference
243
Ports, Exports, and Imps
The UVM provides unidirectional ports, exports, and implementation ports for connecting
your components via the TLM interfaces.
Ports
instantiated in components that require, or use, the associate
interface to initiate transaction requests.
Exports
instantiated by components that forward an implementation of the
methods defined in the associated interface. The implementation is
typically provided by an imp port in a child component.
Imps
instantiated by components that provide or implement an
implementation of the methods defined in the associated interface.
UVM 1.2 Class Reference
244
A summary of port, export, and imp declarations are
class uvm_*_export #(type T=int)
extends uvm_port_base #(tlm_if_base #(T,T));
class uvm_*_port #(type T=int)
extends uvm_port_base #(tlm_if_base #(T,T));
class uvm_*_imp #(type T=int)
extends uvm_port_base #(tlm_if_base #(T,T));
where the asterisk can be any of
blocking_put
nonblocking_put
put
blocking_get
nonblocking_get
get
blocking_peek
nonblocking_peek
peek
blocking_get_peek
nonblocking_get_peek
get_peek
analysis
BiDiReCtiONAl INteRFACes & PORts
The bidirectional interfaces consist of blocking, non-blocking, and combined blocking and
non-blocking variants of the transport, master, and slave interfaces.
Bidirectional interfaces involve both a transaction request and response.
Transport
The transport interface sends a request transaction and returns a response transaction in
a single task call, thereby enforcing an in-order execution semantic. The request and
response transactions can be different types.
Master and Slave
The primitive, unidirectional put, get, and peek interfaces are combined to form
UVM 1.2 Class Reference
245
bidirectional master and slave interfaces. The master puts requests and gets or peeks
responses. The slave gets or peeks requests and puts responses. Because the put and
the get come from different function interface methods, the requests and responses are
not coupled as they are with the transport interface.
Ports, Exports, and Imps
The UVM provides bidirectional ports, exports, and implementation ports for connecting
your components via the TLM interfaces.
Ports
instantiated in components that require, or use, the associate
interface to initiate transaction requests.
Exports
instantiated by components that forward an implementation of the
methods defined in the associated interface. The implementation is
typically provided by an imp port in a child component.
Imps
instantiated by components that provide or implement an
implementation of the methods defined in the associated interface.
UVM 1.2 Class Reference
246
A summary of port, export, and imp declarations are
class uvm_*_port #(type REQ=int, RSP=int)
extends uvm_port_base #(tlm_if_base #(REQ, RSP));
class uvm_*_export #(type REQ=int, RSP=int)
extends uvm_port_base #(tlm_if_base #(REQ, RSP));
class uvm_*_imp #(type REQ=int, RSP=int)
extends uvm_port_base #(tlm_if_base #(REQ, RSP));
where the asterisk can be any of
transport
blocking_transport
nonblocking_transport
blocking_master
nonblocking_master
master
blocking_slave
nonblocking_slave
slave
UsAGe
This example illustrates basic TLM connectivity using the blocking put interface.
UVM 1.2 Class Reference
247
port-to-port
leaf1’s out port is connected to its parent’s (comp1)
out port
port-to-export
comp1’s out port is connected to comp2’s in export
export-to-export
comp2’s in export is connected to its child’s
(subcomp2) in export
export-to-imp
subcomp2’s in export is connected leaf2’s in imp
port.
imp-to-implementation
leaf2’s in imp port is connected to its implementation,
leaf2
Hierarchical port connections are resolved and optimized just before
uvm_component::end_of_elaboration_phase. After optimization, calling any port’s
interface method (e.g. leaf1.out.put(trans)) incurs a single hop to get to the
implementation (e.g. leaf2’s put task), no matter how far up and down the hierarchy the
implementation resides.
`include "uvm_pkg.sv"
import uvm_pkg::*;
class trans extends uvm_transaction;
rand int addr;
rand int data;
rand bit write;
endclass
class leaf1 extends uvm_component;
`uvm_component_utils(leaf1)
uvm_blocking_put_port #(trans) out;
function new(string name, uvm_component parent=null);
super.new(name,parent);
out = new("out",this);
endfunction
virtual task run_phase(uvm_phase phase);
trans t;
phase.raise_objection(this, "prolonging run_phase");
t = new;
t.randomize();
out.put(t);
phase.drop_objection(this, "prolonging run_phase");
endtask
endclass
class comp1 extends uvm_component;
`uvm_component_utils(comp1)
uvm_blocking_put_port #(trans) out;
leaf1 leaf;
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
virtual function void build_phase(uvm_phase phase);
out = new("out",this);
leaf = new("leaf1",this);
endfunction
// connect port to port
virtual function void connect_phase(uvm_phase phase);
leaf.out.connect(out);
endfunction
endclass
class leaf2 extends uvm_component;
`uvm_component_utils(leaf2)
uvm_blocking_put_imp #(trans,leaf2) in;
function new(string name, uvm_component parent=null);
super.new(name,parent);
UVM 1.2 Class Reference
248
// connect imp to implementation (this)
in = new("in",this);
endfunction
virtual task put(trans t);
$display("Got trans: addr=%0d, data=%0d, write=%0d",
t.addr, t.data, t.write);
endtask
endclass
class subcomp2 extends uvm_component;
`uvm_component_utils(subcomp2)
uvm_blocking_put_export #(trans) in;
leaf2 leaf;
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
virtual function void build_phase(uvm_phase phase);
in = new("in",this);
leaf = new("leaf2",this);
endfunction
// connect export to imp
virtual function void connect_phase(uvm_phase phase);
in.connect(leaf.in);
endfunction
endclass
class comp2 extends uvm_component;
`uvm_component_utils(comp2)
uvm_blocking_put_export #(trans) in;
subcomp2 subcomp;
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
virtual function void build_phase(uvm_phase phase);
in = new("in",this);
subcomp = new("subcomp2",this);
endfunction
// connect export to export
virtual function void connect_phase(uvm_phase phase);
in.connect(subcomp.in);
endfunction
endclass
class env extends uvm_component;
`uvm_component_utils(comp1)
comp1 comp1_i;
comp2 comp2_i;
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
virtual function void build_phase(uvm_phase phase);
comp1_i = new("comp1",this);
comp2_i = new("comp2",this);
endfunction
// connect port to export
virtual function void connect_phase(uvm_phase phase);
comp1_i.out.connect(comp2_i.in);
endfunction
endclass
module top;
env e = new("env");
initial run_test();
initial #10 uvm_top.stop_request();
endmodule
UVM 1.2 Class Reference
249
14.1 uvm_tlm_if_base #(T1,T2)
This class declares all of the methods of the TLM API.
Various subsets of these methods are combined to form primitive TLM interfaces, which
are then paired in various ways to form more abstract “combination” TLM interfaces. Components that require a particular interface use ports to convey that requirement. Components that provide a particular interface use exports to convey its availability.
Communication between components is established by connecting ports to compatible
exports, much like connecting module signal-level output ports to compatible input
ports. The difference is that UVM ports and exports bind interfaces (groups of methods),
not signals and wires. The methods of the interfaces so bound pass data as whole
transactions (e.g. objects). The set of primitive and combination TLM interfaces afford
many choices for designing components that communicate at the transaction level.
Summary
uvm_tlm_if_base #(T1,T2)
This class declares all of the methods of the TLM API.
CLAss DEcLARAtION
virtual class uvm_tlm_if_base #(
type T1 = int,
type T2 = int
)
BLOcKING
put
BLOcKING
get
BLOcKING
peek
PUt
Sends a user-defined transaction of type T.
GEt
Provides a new transaction of type T.
PEEK
Obtain a new transaction without consuming it.
NON-bLOcKING
PUt
try_put
can_put
Sends a transaction of type T, if possible.
Returns 1 if the component is ready to accept the
transaction; 0 otherwise.
NON-bLOcKING
GEt
try_get
can_get
Provides a new transaction of type T.
Returns 1 if a new transaction can be provided immediately
upon request, 0 otherwise.
NON-bLOcKING
PEEK
try_peek
can_peek
Provides a new transaction without consuming it.
Returns 1 if a new transaction is available; 0 otherwise.
BLOcKING
tRANsPORt
transport
Executes the given request and returns the response in the
given output argument.
NON-bLOcKING
tRANsPORt
nb_transport
Executes the given request and returns the response in the
given output argument.
ANALYsIs
UVM 1.2 Class Reference
250
write
BLOcKING
Broadcasts a user-defined transaction of type T to any
number of listeners.
PUt
put
virtual task put(
input T1 t
)
Sends a user-defined transaction of type T.
Components implementing the put method will block the calling thread if it cannot
immediately accept delivery of the transaction.
BLOcKING
GEt
get
virtual task get(
output T2 t
)
Provides a new transaction of type T.
The calling thread is blocked if the requested transaction cannot be provided
immediately. The new transaction is returned in the provided output argument.
The implementation of get must regard the transaction as consumed. Subsequent calls
to get must return a different transaction instance.
BLOcKING
PEEK
peek
virtual task peek(
output T2 t
)
Obtain a new transaction without consuming it.
If a transaction is available, then it is written to the provided output argument. If a
transaction is not available, then the calling thread is blocked until one is available.
The returned transaction is not consumed. A subsequent peek or get will return the
same transaction.
UVM 1.2 Class Reference
251
NON- bLOcKING
PUt
try_put
virtual function bit try_put(
input T1 t
)
Sends a transaction of type T, if possible.
If the component is ready to accept the transaction argument, then it does so and
returns 1, otherwise it returns 0.
can_put
virtual function bit can_put()
Returns 1 if the component is ready to accept the transaction; 0 otherwise.
NON- bLOcKING
GEt
try_get
virtual function bit try_get(
output T2 t
)
Provides a new transaction of type T.
If a transaction is immediately available, then it is written to the output argument and 1
is returned. Otherwise, the output argument is not modified and 0 is returned.
can_get
virtual function bit can_get()
Returns 1 if a new transaction can be provided immediately upon request, 0 otherwise.
NON- bLOcKING
PEEK
try_peek
virtual function bit try_peek(
output T2 t
)
Provides a new transaction without consuming it.
If available, a transaction is written to the output argument and 1 is returned. A
UVM 1.2 Class Reference
252
subsequent peek or get will return the same transaction. If a transaction is not
available, then the argument is unmodified and 0 is returned.
can_peek
virtual function bit can_peek()
Returns 1 if a new transaction is available; 0 otherwise.
BLOcKING
tRANsPORt
transport
virtual task transport(
input T1 req ,
output T2 rsp
)
Executes the given request and returns the response in the given output argument. The
calling thread may block until the operation is complete.
NON- bLOcKING
tRANsPORt
nb_transport
virtual function bit nb_transport(
input T1 req,
output T2 rsp
)
Executes the given request and returns the response in the given output argument. Completion of this operation must occur without blocking.
If for any reason the operation could not be executed immediately, then a 0 must be
returned; otherwise 1.
ANALYsIs
write
virtual function void write(
input T1 t
)
Broadcasts a user-defined transaction of type T to any number of listeners. The
operation must complete without blocking.
UVM 1.2 Class Reference
253
14.2 TLM Export Classes
The following classes define the TLM export classes.
Contents
TLM Export
Classes
The following classes define the TLM export classes.
uvm_*_export
#(T)
The unidirectional uvm_*_export is a port that forwards or
promotes an interface implementation from a child component to
its parent.
The bidirectional uvm_*_export is a port that forwards or
promotes an interface implementation from a child component to
its parent.
uvm_*_export
#(REQ,RSP)
uvm_*_export #(T)
The unidirectional uvm_*_export is a port that forwards or promotes an interface
implementation from a child component to its parent. An export can be connected to
any compatible child export or imp port. It must ultimately be connected to at least one
implementation of its associated interface.
The interface type represented by the asterisk is any of the following
blocking_put
nonblocking_put
put
blocking_get
nonblocking_get
get
blocking_peek
nonblocking_peek
peek
blocking_get_peek
nonblocking_get_peek
get_peek
Type parameters
T
The type of transaction to be communicated by the export
Exports are connected to interface implementations directly via uvm_*_imp #(T,IMP)
ports or indirectly via other uvm_*_export #(T) exports.
Summary
uvm_*_export #(T)
The unidirectional uvm_*_export is a port that forwards or promotes an interface
implementation from a child component to its parent.
MetHODs
UVM 1.2 Class Reference
254
new
The name and parent are the standard uvm_component
constructor arguments.
MetHODs
new
The name and parent are the standard uvm_component constructor arguments. The
min_size and max_size specify the minimum and maximum number of interfaces that
must have been supplied to this port by the end of elaboration.
function new (string name,
uvm_component parent,
int min_size=1,
int max_size=1)
uvm_*_export #(REQ,RSP)
The bidirectional uvm_*_export is a port that forwards or promotes an interface
implementation from a child component to its parent. An export can be connected to
any compatible child export or imp port. It must ultimately be connected to at least one
implementation of its associated interface.
The interface type represented by the asterisk is any of the following
blocking_transport
nonblocking_transport
transport
blocking_master
nonblocking_master
master
blocking_slave
nonblocking_slave
slave
Type parameters
REQ
The type of request transaction to be communicated by the export
RSP
The type of response transaction to be communicated by the export
Exports are connected to interface implementations directly via uvm_*_imp #(REQ, RSP,
IMP, REQ_IMP, RSP_IMP) ports or indirectly via other uvm_*_export #(REQ,RSP)
exports.
Summary
uvm_*_export #(REQ,RSP)
The bidirectional uvm_*_export is a port that forwards or promotes an interface
UVM 1.2 Class Reference
255
implementation from a child component to its parent.
MetHODs
new
The name and parent are the standard uvm_component
constructor arguments.
MetHODs
new
The name and parent are the standard uvm_component constructor arguments. The
min_size and max_size specify the minimum and maximum number of interfaces that
must have been supplied to this port by the end of elaboration.
function new (string name,
uvm_component parent,
int min_size=1,
int max_size=1)
UVM 1.2 Class Reference
256
14.3 TLM Port Classes
The following classes define the TLM port classes.
Contents
TLM Port
Classes
The following classes define the TLM port classes.
uvm_*_port
#(T)
uvm_*_port
#(REQ,RSP)
These unidirectional ports are instantiated by components that
require, or use, the associated interface to convey transactions.
These bidirectional ports are instantiated by components that
require, or use, the associated interface to convey transactions.
uvm_*_port #(T)
These unidirectional ports are instantiated by components that require, or use, the
associated interface to convey transactions. A port can be connected to any compatible
port, export, or imp port. Unless its min_size is 0, a port must be connected to at least
one implementation of its associated interface.
The asterisk in uvm_*_port is any of the following
blocking_put
nonblocking_put
put
blocking_get
nonblocking_get
get
blocking_peek
nonblocking_peek
peek
blocking_get_peek
nonblocking_get_peek
get_peek
Type parameters
T
The type of transaction to be communicated by the export. The type T is
not restricted to class handles and may be a value type such as
int,enum,struct or similar.
Ports are connected to interface implementations directly via uvm_*_imp #(T,IMP) ports
or indirectly via hierarchical connections to uvm_*_port #(T) and uvm_*_export #(T)
ports.
Summary
uvm_*_port #(T)
These unidirectional ports are instantiated by components that require, or use,
the associated interface to convey transactions.
UVM 1.2 Class Reference
257
MEtHODs
new
The name and parent are the standard uvm_component
constructor arguments.
MEtHODs
new
The name and parent are the standard uvm_component constructor arguments. The
min_size and max_size specify the minimum and maximum number of interfaces that
must have been connected to this port by the end of elaboration.
function new (string name,
uvm_component parent,
int min_size=1,
int max_size=1)
uvm_*_port #(REQ,RSP)
These bidirectional ports are instantiated by components that require, or use, the
associated interface to convey transactions. A port can be connected to any compatible
port, export, or imp port. Unless its min_size is 0, a port must be connected to at least
one implementation of its associated interface.
The asterisk in uvm_*_port is any of the following
blocking_transport
nonblocking_transport
transport
blocking_master
nonblocking_master
master
blocking_slave
nonblocking_slave
slave
Ports are connected to interface implementations directly via uvm_*_imp
#(REQ,RSP,IMP,REQ_IMP,RSP_IMP) ports or indirectly via hierarchical connections to
uvm_*_port #(REQ,RSP) and uvm_*_export #(REQ,RSP) ports.
Type parameters
REQ
The type of request transaction to be communicated by the export
RSP
The type of response transaction to be communicated by the export
Summary
uvm_*_port #(REQ,RSP)
UVM 1.2 Class Reference
258
These bidirectional ports are instantiated by components that require, or use, the
associated interface to convey transactions.
MEtHODs
new
The name and parent are the standard uvm_component
constructor arguments.
MEtHODs
new
The name and parent are the standard uvm_component constructor arguments. The
min_size and max_size specify the minimum and maximum number of interfaces that
must have been supplied to this port by the end of elaboration.
function new (string name, uvm_component parent, int min_size=1, int max_size=1)
UVM 1.2 Class Reference
259
14.4 uvm_*_imp ports
The following defines the TLM implementation (imp) classes.
Contents
uvm_*_imp
ports
The following defines the TLM implementation (imp) classes.
uvm_*_imp
#(T,IMP)
Unidirectional implementation (imp) port classes--An imp
port provides access to an implementation of the associated
interface to all connected ports and exports.
Bidirectional implementation (imp) port classes--An imp port
provides access to an implementation of the associated
interface to all connected ports and exports.
uvm_*_imp
#(REQ, RSP, IMP,
REQ_IMP,
RSP_IMP)
uvm_*_imp #(T,IMP)
Unidirectional implementation (imp) port classes--An imp port provides access to an
implementation of the associated interface to all connected ports and exports. Each imp
port instance must be connected to the component instance that implements the
associated interface, typically the imp port’s parent. All other connections-- e.g. to other
ports and exports-- are prohibited.
The asterisk in uvm_*_imp may be any of the following
blocking_put
nonblocking_put
put
blocking_get
nonblocking_get
get
blocking_peek
nonblocking_peek
peek
blocking_get_peek
nonblocking_get_peek
get_peek
Type parameters
T
The type of transaction to be communicated by the imp
IMP
The type of the component implementing the interface. That is, the
class to which this imp will delegate.
The interface methods are implemented in a component of type IMP, a handle to which is
passed in a constructor argument. The imp port delegates all interface calls to this
component.
Summary
uvm_*_imp #(T,IMP)
UVM 1.2 Class Reference
260
Unidirectional implementation (imp) port classes--An imp port provides access to
an implementation of the associated interface to all connected ports and exports.
MEtHODs
new
Creates a new unidirectional imp port with the given name and
parent.
MEtHODs
new
Creates a new unidirectional imp port with the given name and parent. The parent must
implement the interface associated with this port. Its type must be the type specified in
the imp’s type-parameter, IMP.
function new (string name, IMP parent);
uvm_*_imp #(REQ, RSP, IMP, REQ_IMP,
RSP_IMP)
Bidirectional implementation (imp) port classes--An imp port provides access to an
implementation of the associated interface to all connected ports and exports. Each imp
port instance must be connected to the component instance that implements the
associated interface, typically the imp port’s parent. All other connections-- e.g. to other
ports and exports-- are prohibited.
The interface represented by the asterisk is any of the following
blocking_transport
nonblocking_transport
transport
blocking_master
nonblocking_master
master
blocking_slave
nonblocking_slave
slave
Type parameters
REQ
Request transaction type
RSP
Response transaction type
IMP
Component type that implements the interface methods, typically
the parent of this imp port.
REQ_IMP
Component type that implements the request side of the interface. Defaults to IMP. For master and slave imps only.
UVM 1.2 Class Reference
261
RSP_IMP
Component type that implements the response side of the
interface. Defaults to IMP. For master and slave imps only.
The interface methods are implemented in a component of type IMP, a handle to which is
passed in a constructor argument. The imp port delegates all interface calls to this
component.
The master and slave imps have two modes of operation.
A single component of type IMP implements the entire interface for both requests
and responses.
Two sibling components of type REQ_IMP and RSP_IMP implement the request and
response interfaces, respectively. In this case, the IMP parent instantiates this imp
port and the REQ_IMP and RSP_IMP components.
The second mode is needed when a component instantiates more than one imp port, as
in the uvm_tlm_req_rsp_channel #(REQ,RSP) channel.
Summary
uvm_*_imp #(REQ, RSP, IMP, REQ_IMP, RSP_IMP)
Bidirectional implementation (imp) port classes--An imp port provides access to
an implementation of the associated interface to all connected ports and exports.
MEtHODs
new
Creates a new bidirectional imp port with the given name and
parent.
MEtHODs
new
Creates a new bidirectional imp port with the given name and parent. The parent, whose
type is specified by IMP type parameter, must implement the interface associated with
this port.
Transport imp constructor
function new(string name, IMP imp)
Master and slave imp constructor
The optional req_imp and rsp_imp arguments, available to master and slave imp ports,
allow the requests and responses to be handled by different subcomponents. If they are
specified, they must point to the underlying component that implements the request and
response methods, respectively.
function new(string name, IMP imp,
REQ_IMP req_imp=imp, RSP_IMP rsp_imp=imp)
UVM 1.2 Class Reference
262
14.5 TLM FIFO Classes
This section defines TLM-based FIFO classes.
Contents
TLM FIFO Classes
This section defines TLM-based FIFO classes.
uvm_tlm_fifo#(T)
This class provides storage of transactions between
two independently running processes.
An analysis_fifo is a uvm_tlm_fifo#(T) with an
unbounded size and a write interface.
uvm_tlm_analysis_fifo#(T)
uvm_tlm_fifo#(T)
This class provides storage of transactions between two independently running
processes. Transactions are put into the FIFO via the put_export. transactions are
fetched from the FIFO in the order they arrived via the get_peek_export. The put_export
and get_peek_export are inherited from the uvm_tlm_fifo_base #(T) super class, and the
interface methods provided by these exports are defined by the uvm_tlm_if_base
#(T1,T2) class.
Summary
uvm_tlm_fifo#(T)
This class provides storage of transactions between two independently running
processes.
MEtHoDs
new
size
used
is_empty
is_full
flush
The name and parent are the normal uvm_component
constructor arguments.
Returns the capacity of the FIFO-- that is, the number of entries
the FIFO is capable of holding.
Returns the number of entries put into the FIFO.
Returns 1 when there are no entries in the FIFO, 0 otherwise.
Returns 1 when the number of entries in the FIFO is equal to its
size, 0 otherwise.
Removes all entries from the FIFO, after which used returns 0
and is_empty returns 1.
MEtHoDs
new
function new(
string name, uvm_component parent = null,
int size = 1
)
UVM 1.2 Class Reference
263
The name and parent are the normal uvm_component constructor arguments. The
parent should be null if the uvm_tlm_fifo#(T) is going to be used in a statically
elaborated construct (e.g., a module). The size indicates the maximum size of the FIFO;
a value of zero indicates no upper bound.
size
virtual function int size()
Returns the capacity of the FIFO-- that is, the number of entries the FIFO is capable of
holding. A return value of 0 indicates the FIFO capacity has no limit.
used
virtual function int used()
Returns the number of entries put into the FIFO.
is_empty
virtual function bit is_empty()
Returns 1 when there are no entries in the FIFO, 0 otherwise.
is_full
virtual function bit is_full()
Returns 1 when the number of entries in the FIFO is equal to its size, 0 otherwise.
flush
virtual function void flush()
Removes all entries from the FIFO, after which used returns 0 and is_empty returns 1.
uvm_tlm_analysis_fifo#(T)
An analysis_fifo is a uvm_tlm_fifo#(T) with an unbounded size and a write interface. It
can be used any place a uvm_analysis_imp is used. Typical usage is as a buffer between
a uvm_analysis_port in an initiator component and TLM1 target component.
Summary
uvm_tlm_analysis_fifo#(T)
An analysis_fifo is a uvm_tlm_fifo#(T) with an unbounded size and a write
UVM 1.2 Class Reference
264
interface.
PoRts
analysis_export
#(T)
The analysis_export provides the write method to all
connected analysis ports and parent exports:
MEtHoDs
new
This is the standard uvm_component constructor.
PoRts
analysis_export #(T)
The analysis_export provides the write method to all connected analysis ports and parent
exports:
function void write (T t)
Access via ports bound to this export is the normal mechanism for writing to an analysis
FIFO. See write method of uvm_tlm_if_base #(T1,T2) for more information.
MEtHoDs
new
function new(
string name ,
uvm_component parent = null
)
This is the standard uvm_component constructor. name is the local name of this
component. The parent should be left unspecified when this component is instantiated in
statically elaborated constructs and must be specified when this component is a child of
another UVM component.
UVM 1.2 Class Reference
265
14.6 uvm_tlm_fifo_base #(T)
This class is the base for uvm_tlm_fifo#(T). It defines the TLM exports through which all
transaction-based FIFO operations occur. It also defines default implementations for
each interface method provided by these exports.
The interface methods provided by the put_export and the get_peek_export are defined
and described by uvm_tlm_if_base #(T1,T2). See the TLM Overview section for a
general discussion of TLM interface definition and usage.
Parameter type
T
The type of transactions to be stored by this FIFO.
Summary
uvm_tlm_fifo_base #(T)
This class is the base for uvm_tlm_fifo#(T).
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_tlm_fifo_base#(T)
CLAss DEcLARAtION
virtual class uvm_tlm_fifo_base #(
type T = int
) extends uvm_component
PORts
put_export
get_peek_export
put_ap
get_ap
MEthOds
new
The put_export provides both the blocking and nonblocking put interface methods to any attached port:
The get_peek_export provides all the blocking and nonblocking get and peek interface methods:
Transactions passed via put or try_put (via any port
connected to the put_export) are sent out this port via
its write method.
Transactions passed via get, try_get, peek, or try_peek
(via any port connected to the get_peek_export) are sent
out this port via its write method.
The name and parent are the normal uvm_component
constructor arguments.
PORts
put_export
UVM 1.2 Class Reference
266
The put_export provides both the blocking and non-blocking put interface methods to
any attached port:
task put (input T t)
function bit can_put ()
function bit try_put (input T t)
Any put port variant can connect and send transactions to the FIFO via this export,
provided the transaction types match. See uvm_tlm_if_base #(T1,T2) for more
information on each of the above interface methods.
get_peek_export
The get_peek_export provides all the blocking and non-blocking get and peek interface
methods:
task get (output T t)
function bit can_get ()
function bit try_get (output T t)
task peek (output T t)
function bit can_peek ()
function bit try_peek (output T t)
Any get or peek port variant can connect to and retrieve transactions from the FIFO via
this export, provided the transaction types match. See uvm_tlm_if_base #(T1,T2) for
more information on each of the above interface methods.
put_ap
Transactions passed via put or try_put (via any port connected to the put_export) are
sent out this port via its write method.
function void write (T t)
All connected analysis exports and imps will receive put transactions. See
uvm_tlm_if_base #(T1,T2) for more information on the write interface method.
get_ap
Transactions passed via get, try_get, peek, or try_peek (via any port connected to the
get_peek_export) are sent out this port via its write method.
function void write (T t)
All connected analysis exports and imps will receive get transactions. See
uvm_tlm_if_base #(T1,T2) for more information on the write method.
UVM 1.2 Class Reference
267
MEthOds
new
function new(
string name, uvm_component parent = null
)
The name and parent are the normal uvm_component constructor arguments. The
parent should be null if the uvm_tlm_fifo is going to be used in a statically elaborated
construct (e.g., a module). The size indicates the maximum size of the FIFO. A value of
zero indicates no upper bound.
UVM 1.2 Class Reference
268
14.7 TLM Channel Classes
This section defines built-in TLM channel classes.
Contents
TLM Channel Classes
This section defines built-in TLM channel classes.
uvm_tlm_req_rsp_channel
#(REQ,RSP)
uvm_tlm_transport_channel
#(REQ,RSP)
The uvm_tlm_req_rsp_channel contains a request
FIFO of type REQ and a response FIFO of type RSP.
A uvm_tlm_transport_channel is a
uvm_tlm_req_rsp_channel #(REQ,RSP) that
implements the transport interface.
uvm_tlm_req_rsp_channel #(REQ,RSP)
The uvm_tlm_req_rsp_channel contains a request FIFO of type REQ and a response FIFO
of type RSP. These FIFOs can be of any size. This channel is particularly useful for
dealing with pipelined protocols where the request and response are not tightly coupled.
Type parameters
REQ
Type of the request transactions conveyed by this channel.
RSP
Type of the response transactions conveyed by this channel.
Summary
uvm_tlm_req_rsp_channel #(REQ,RSP)
The uvm_tlm_req_rsp_channel contains a request FIFO of type REQ and a
response FIFO of type RSP.
ClAss HIerArchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_tlm_req_rsp_channel#(REQ,RSP)
ClAss DeclArAtION
class uvm_tlm_req_rsp_channel #(
type REQ = int,
type RSP = REQ
) extends uvm_component
POrts
put_request_export
get_peek_response_export
UVM 1.2 Class Reference
The put_export provides both the blocking and
non-blocking put interface methods to the
request FIFO:
The get_peek_response_export provides all the
blocking and non-blocking get and peek
269
get_peek_request_export
put_response_export
request_ap
response_ap
master_export
slave_export
MethOds
new
interface methods to the response FIFO:
The get_peek_export provides all the blocking
and non-blocking get and peek interface
methods to the response FIFO:
The put_export provides both the blocking and
non-blocking put interface methods to the
response FIFO:
Transactions passed via put or try_put (via any
port connected to the put_request_export) are
sent out this port via its write method.
Transactions passed via put or try_put (via any
port connected to the put_response_export)
are sent out this port via its write method.
Exports a single interface that allows a master
to put requests and get or peek responses.
Exports a single interface that allows a slave to
get or peek requests and to put responses.
The name and parent are the standard
uvm_component constructor arguments.
POrts
put_request_export
The put_export provides both the blocking and non-blocking put interface methods to the
request FIFO:
task put (input T t);
function bit can_put ();
function bit try_put (input T t);
Any put port variant can connect and send transactions to the request FIFO via this
export, provided the transaction types match.
get_peek_response_export
The get_peek_response_export provides all the blocking and non-blocking get and peek
interface methods to the response FIFO:
task get (output T t);
function bit can_get ();
function bit try_get (output T t);
task peek (output T t);
function bit can_peek ();
function bit try_peek (output T t);
Any get or peek port variant can connect to and retrieve transactions from the response
FIFO via this export, provided the transaction types match.
get_peek_request_export
UVM 1.2 Class Reference
270
The get_peek_export provides all the blocking and non-blocking get and peek interface
methods to the response FIFO:
task get (output T t);
function bit can_get ();
function bit try_get (output T t);
task peek (output T t);
function bit can_peek ();
function bit try_peek (output T t);
Any get or peek port variant can connect to and retrieve transactions from the response
FIFO via this export, provided the transaction types match.
put_response_export
The put_export provides both the blocking and non-blocking put interface methods to the
response FIFO:
task put (input T t);
function bit can_put ();
function bit try_put (input T t);
Any put port variant can connect and send transactions to the response FIFO via this
export, provided the transaction types match.
request_ap
Transactions passed via put or try_put (via any port connected to the
put_request_export) are sent out this port via its write method.
function void write (T t);
All connected analysis exports and imps will receive these transactions.
response_ap
Transactions passed via put or try_put (via any port connected to the
put_response_export) are sent out this port via its write method.
function void write (T t);
All connected analysis exports and imps will receive these transactions.
master_export
Exports a single interface that allows a master to put requests and get or peek
UVM 1.2 Class Reference
271
responses. It is a combination of the put_request_export and
get_peek_response_export.
slave_export
Exports a single interface that allows a slave to get or peek requests and to put
responses. It is a combination of the get_peek_request_export and
put_response_export.
MethOds
new
function new (
string name,
uvm_component parent
= null,
int request_fifo_size = 1,
int response_fifo_size = 1
)
The name and parent are the standard uvm_component constructor arguments. The
parent must be null if this component is defined within a static component such as a
module, program block, or interface. The last two arguments specify the request and
response FIFO sizes, which have default values of 1.
uvm_tlm_transport_channel #(REQ,RSP)
A uvm_tlm_transport_channel is a uvm_tlm_req_rsp_channel #(REQ,RSP) that
implements the transport interface. It is useful when modeling a non-pipelined bus at
the transaction level. Because the requests and responses have a tightly coupled oneto-one relationship, the request and response FIFO sizes are both set to one.
Summary
uvm_tlm_transport_channel #(REQ,RSP)
A uvm_tlm_transport_channel is a uvm_tlm_req_rsp_channel #(REQ,RSP) that
implements the transport interface.
ClAss HIerArchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_tlm_req_rsp_channel#(REQ,RSP)
uvm_tlm_transport_channel#(REQ,RSP)
ClAss DeclArAtION
UVM 1.2 Class Reference
272
class uvm_tlm_transport_channel #(
type REQ = int,
type RSP = REQ
) extends uvm_tlm_req_rsp_channel #(REQ, RSP)
POrts
transport_export
MethOds
new
The put_export provides both the blocking and nonblocking transport interface methods to the response
FIFO:
The name and parent are the standard uvm_component
constructor arguments.
POrts
transport_export
The put_export provides both the blocking and non-blocking transport interface methods
to the response FIFO:
task transport(REQ request, output RSP response);
function bit nb_transport(REQ request, output RSP response);
Any transport port variant can connect to and send requests and retrieve responses via
this export, provided the transaction types match. Upon return, the response argument
carries the response to the request.
MethOds
new
function new (
string name, uvm_component parent = null
)
The name and parent are the standard uvm_component constructor arguments. The
parent must be null if this component is defined within a statically elaborated construct
such as a module, program block, or interface.
UVM 1.2 Class Reference
273
14.8 Sequence Item Pull Ports
This section defines the port, export, and imp port classes for communicating sequence
items between uvm_sequencer #(REQ,RSP) and uvm_driver #(REQ,RSP).
Contents
Sequence Item Pull
Ports
This section defines the port, export, and imp port
classes for communicating sequence items between
uvm_sequencer #(REQ,RSP) and uvm_driver
#(REQ,RSP).
uvm_seq_item_pull_port
#(REQ,RSP)
uvm_seq_item_pull_export
#(REQ,RSP)
uvm_seq_item_pull_imp
#(REQ,RSP,IMP)
UVM provides a port, export, and imp connector for
use in sequencer-driver communication.
This export type is used in sequencer-driver
communication.
This imp type is used in sequencer-driver
communication.
uvm_seq_item_pull_port #(REQ,RSP)
UVM provides a port, export, and imp connector for use in sequencer-driver
communication. All have standard port connector constructors, except that
uvm_seq_item_pull_port’s default min_size argument is 0; it can be left unconnected.
Summary
uvm_seq_item_pull_port #(REQ,RSP)
UVM provides a port, export, and imp connector for use in sequencer-driver
communication.
CLAss HierArchY
uvm_port_base#(uvm_sqr_if_base#(REQ,RSP))
uvm_seq_item_pull_port#(REQ,RSP)
CLAss DecLArATiON
class uvm_seq_item_pull_port #(
type REQ = int,
type RSP = REQ
) extends uvm_port_base #(uvm_sqr_if_base #(REQ, RSP))
uvm_seq_item_pull_export #(REQ,RSP)
This export type is used in sequencer-driver communication. It has the standard
constructor for exports.
Summary
UVM 1.2 Class Reference
274
uvm_seq_item_pull_export #(REQ,RSP)
This export type is used in sequencer-driver communication.
CLAss HierArchY
uvm_port_base#(uvm_sqr_if_base#(REQ,RSP))
uvm_seq_item_pull_export#(REQ,RSP)
CLAss DecLArATiON
class uvm_seq_item_pull_export #(
type REQ = int,
type RSP = REQ
) extends uvm_port_base #(uvm_sqr_if_base #(REQ, RSP))
uvm_seq_item_pull_imp #(REQ,RSP,IMP)
This imp type is used in sequencer-driver communication. It has the standard
constructor for imp-type ports.
Summary
uvm_seq_item_pull_imp #(REQ,RSP,IMP)
This imp type is used in sequencer-driver communication.
CLAss HierArchY
uvm_port_base#(uvm_sqr_if_base#(REQ,RSP))
uvm_seq_item_pull_imp#(REQ,RSP,IMP)
CLAss DecLArATiON
class uvm_seq_item_pull_imp #(
type REQ = int,
type RSP = REQ,
type IMP = int
) extends uvm_port_base #(uvm_sqr_if_base #(REQ, RSP))
MeThOds
new
MeThOds
new
UVM 1.2 Class Reference
275
14.9 uvm_sqr_if_base #(REQ,RSP)
This class defines an interface for sequence drivers to communicate with sequencers. The driver requires the interface via a port, and the sequencer implements it and
provides it via an export.
Summary
uvm_sqr_if_base #(REQ,RSP)
This class defines an interface for sequence drivers to communicate with
sequencers.
CLAss DecLArATION
virtual class uvm_sqr_if_base #(
type T1 = uvm_object,
T2 = T1
)
MeTHOds
get_next_item
try_next_item
item_done
wait_for_sequences
has_do_available
get
peek
put
put_response
disable_auto_item_recording
is_auto_item_recording_enabled
Retrieves the next available item from a
sequence.
Retrieves the next available item from a
sequence if one is available.
Indicates that the request is completed to
the sequencer.
Waits for a sequence to have a new item
available.
Indicates whether a sequence item is
available for immediate processing.
Retrieves the next available item from a
sequence.
Returns the current request item if one is
in the sequencer FIFO.
Sends a response back to the sequence
that issued the request.
Sends a response back to the sequence
that issued the request.
By default, item recording is performed
automatically when get_next_item() and
item_done() are called.
Return TRUE if automatic item recording
is enabled for this port instance.
MeTHOds
get_next_item
virtual task get_next_item(
output T1 t
)
Retrieves the next available item from a sequence. The call will block until an item is
available. The following steps occur on this call:
1
Arbitrate among requesting, unlocked, relevant sequences - choose the
highest priority sequence based on the current sequencer arbitration
UVM 1.2 Class Reference
276
mode. If no sequence is available, wait for a requesting unlocked relevant
sequence, then re-arbitrate.
2
The chosen sequence will return from wait_for_grant
3
The chosen sequence uvm_sequence_base::pre_do is called
4
The chosen sequence item is randomized
5
The chosen sequence uvm_sequence_base::post_do is called
6
Return with a reference to the item
Once get_next_item is called, item_done must be called to indicate the completion of the
request to the sequencer. This will remove the request item from the sequencer FIFO.
try_next_item
virtual task try_next_item(
output T1 t
)
Retrieves the next available item from a sequence if one is available. Otherwise, the
function returns immediately with request set to null. The following steps occur on this
call:
1
Arbitrate among requesting, unlocked, relevant sequences - choose the
highest priority sequence based on the current sequencer arbitration
mode. If no sequence is available, return null.
2
The chosen sequence will return from wait_for_grant
3
The chosen sequence uvm_sequence_base::pre_do is called
4
The chosen sequence item is randomized
5
The chosen sequence uvm_sequence_base::post_do is called
6
Return with a reference to the item
Once try_next_item is called, item_done must be called to indicate the completion of the
request to the sequencer. This will remove the request item from the sequencer FIFO.
item_done
virtual function void item_done(
input T2 t = null
)
Indicates that the request is completed to the sequencer. Any
uvm_sequence_base::wait_for_item_done calls made by a sequence for this item will
return.
The current item is removed from the sequencer FIFO.
If a response item is provided, then it will be sent back to the requesting sequence. The
response item must have its sequence ID and transaction ID set correctly, using the
uvm_sequence_item::set_id_info method:
rsp.set_id_info(req);
Before item_done is called, any calls to peek will retrieve the current item that was
UVM 1.2 Class Reference
277
obtained by get_next_item. After item_done is called, peek will cause the sequencer to
arbitrate for a new item.
wait_for_sequences
virtual task wait_for_sequences()
Waits for a sequence to have a new item available. The default implementation in the
sequencer calls uvm_wait_for_nba_region. User-derived sequencers may override its
wait_for_sequences implementation to perform some other application-specific
implementation.
has_do_available
virtual function bit has_do_available()
Indicates whether a sequence item is available for immediate processing. Implementations should return 1 if an item is available, 0 otherwise.
get
virtual task get(
output T1 t
)
Retrieves the next available item from a sequence. The call blocks until an item is
available. The following steps occur on this call:
1
Arbitrate among requesting, unlocked, relevant sequences - choose the
highest priority sequence based on the current sequencer arbitration
mode. If no sequence is available, wait for a requesting unlocked relevant
sequence, then re-arbitrate.
2
The chosen sequence will return from uvm_sequence_base::wait_for_grant
3
The chosen sequence uvm_sequence_base::pre_do is called
4
The chosen sequence item is randomized
5
The chosen sequence uvm_sequence_base::post_do is called
6
Indicate item_done to the sequencer
7
Return with a reference to the item
When get is called, item_done may not be called. A new item can be obtained by calling
get again, or a response may be sent using either put, or uvm_driver::rsp_port.write().
peek
virtual task peek(
output T1 t
)
Returns the current request item if one is in the sequencer FIFO. If no item is in the
FIFO, then the call will block until the sequencer has a new request. The following steps
will occur if the sequencer FIFO is empty:
1
Arbitrate among requesting, unlocked, relevant sequences - choose the
UVM 1.2 Class Reference
278
highest priority sequence based on the current sequencer arbitration
mode. If no sequence is available, wait for a requesting unlocked relevant
sequence, then re-arbitrate.
2
The chosen sequence will return from uvm_sequence_base::wait_for_grant
3
The chosen sequence uvm_sequence_base::pre_do is called
4
The chosen sequence item is randomized
5
The chosen sequence uvm_sequence_base::post_do is called
Once a request item has been retrieved and is in the sequencer FIFO, subsequent calls to
peek will return the same item. The item will stay in the FIFO until either get or
item_done is called.
put
virtual task put(
input T2 t
)
Sends a response back to the sequence that issued the request. Before the response is
put, it must have its sequence ID and transaction ID set to match the request. This can
be done using the uvm_sequence_item::set_id_info call:
rsp.set_id_info(req);
While this is a task, it will not consume time (including delta cycles). The response will
be put into the sequence response queue or it will be sent to the sequence response
handler.
put_response
virtual function void put_response(
input T2 t
)
Sends a response back to the sequence that issued the request. Before the response is
put, it must have its sequence ID and transaction ID set to match the request. This can
be done using the uvm_sequence_item::set_id_info call:
rsp.set_id_info(req);
disable_auto_item_recording
virtual function void disable_auto_item_recording()
By default, item recording is performed automatically when get_next_item() and
item_done() are called. However, this works only for simple, in-order, blocking
transaction execution. For pipelined and out-of-order transaction execution, the driver
must turn off this automatic recording and call uvm_transaction::accept_tr,
uvm_transaction::begin_tr and uvm_transaction::end_tr explicitly at appropriate points in
time.
This methods be called at the beginning of the driver’s run_phase() method. Once
disabled, automatic recording cannot be re-enabled.
For backward-compatibility, automatic item recording can be globally turned off at
UVM 1.2 Class Reference
279
compile time by defining UVM_DISABLE_AUTO_ITEM_RECORDING
is_auto_item_recording_enabled
virtual function bit is_auto_item_recording_enabled()
Return TRUE if automatic item recording is enabled for this port instance.
UVM 1.2 Class Reference
280
15. TLM2 Interfaces, Ports, Exports and Transport
Interfaces Subset
Sockets group together all the necessary core interfaces for transportation and binding,
allowing more generic usage models than just TLM core interfaces.
A socket is like a port or export; in fact it is derived from the same base class as ports
and export, namely uvm_port_base #(IF). However, unlike a port or export a socket
provides both a forward and backward path. Thus you can enable asynchronous
(pipelined) bi-directional communication by connecting sockets together. To enable this,
a socket contains both a port and an export. Components that initiate transactions are
called initiators, and components that receive transactions sent by an initiator are called
targets. Initiators have initiator sockets and targets have target sockets. Initiator
sockets can connect to target sockets. You cannot connect initiator sockets to other
initiator sockets and you cannot connect target sockets to target sockets.
The UVM TLM2 subset provides the following two transport interfaces
Blocking (b_transport)
completes the entire transaction within a single
method call
Non-blocking (nb_transport)
describes the progress of a transaction using
multiple nb_transport() method calls going backand-forth between initiator and target
In general, any component might modify a transaction object during its lifetime (subject
to the rules of the protocol). Significant timing points during the lifetime of a transaction
(for example: start of response- phase) are indicated by calling nb_transport() in either
forward or backward direction, the specific timing point being given by the phase
argument. Protocol-specific rules for reading or writing the attributes of a transaction
can be expressed relative to the phase. The phase can be used for flow control, and for
that reason might have a different value at each hop taken by a transaction; the phase is
not an attribute of the transaction object.
A call to nb_transport() always represents a phase transition. However, the return from
nb_transport() might or might not do so, the choice being indicated by the value
returned from the function (UVM_TLM_ACCEPTED versus UVM_TLM_UPDATED). Generally, you indicate the completion of a transaction over a particular hop using the
value of the phase argument. As a shortcut, a target might indicate the completion of
the transaction by returning a special value of UVM_TLM_COMPLETED. However, this is
an option, not a necessity.
The transaction object itself does not contain any timing information by design. Or even
events and status information concerning the API. You can pass the delays as
arguments to b_transport()/ nb_transport() and push the actual realization of any delay
in the simulator kernel downstream and defer (for simulation speed).
Use Models
Since sockets are derived from uvm_port_base #(IF) they are created and connected in
the same way as port, and exports. Create them in the build phase and connect them in
the connect phase by calling connect(). Initiator and target termination sockets are on
the ends of any connection. There can be an arbitrary number of pass-through sockets
in the path between initiator and target. Some socket types must be bound to imps
implementations of the transport tasks and functions. Blocking terminator sockets must
be bound to an implementation of b_transport(), for example. Nonblocking initiator
sockets must be bound to an implementation of nb_transport_bw() and nonblocking
target sockets must be bound to an implementation of nb_transport_fw(). Typically, the
UVM 1.2 Class Reference
281
task or function is implemented in the component in which the socket is instantiated and
the component type and instance are provided to complete the binding.
Consider for example a consumer component with a blocking target socket.
Example
class consumer extends uvm_component;
tlm2_b_target_socket #(consumer, trans) target_socket;
function new(string name, uvm_component parent);
super.new(name, parent);
endfunction
function void build();
target_socket = new("target_socket", this, this);
endfunction
task b_transport(trans t, uvm_tlm_time delay);
#5;
uvm_report_info("consumer", t.convert2string());
endtask
endclass
The interface task b_transport() is implemented in the consumer component. The
consumer component type is used in the declaration of the target socket. This informs
the socket object the type of the object that contains the interface task, in this case
b_transport(). When the socket is instantiated “this” is passed in twice, once as the
parent just like any other component instantiation and again to identify the object that
holds the implementation of b_transport(). Finally, in order to complete the binding, an
implementation of b_transport() must be present in the consumer component. Any
component that has either a blocking termination socket, a nonblocking initiator socket,
or a nonblocking termination socket must provide implementations of the relevant
components. This includes initiator and target components as well as interconnect
components that have these kinds of sockets. Components with pass-through sockets do
not need to provide implementations of any sort. Of course, they must ultimately be
connected to sockets that do that the necessary implementations.
In summary
Call to b_transport()
start-of-life of transaction
Return from b_transport()
end-of-life of transaction
Phase argument to nb_transport()
timing point within lifetime of
transaction
Return value of nb_transport()
whether return path is being used
(also shortcut to final phase)
Response status within transaction object
protocol-specific status,
success/failure of transaction
On top of this, TLM-2.0 defines a generic payload and base protocol to enhance
interoperability for models with a memory-mapped bus interface.
It is possible to use the interfaces described above with user-defined transaction types
and protocols for the sake of interoperability. However, TLM-2.0 strongly recommends
either using the base protocol off-the-shelf or creating models of specific protocols on top
of the base protocol.
The UVM 1.2 standard only defines and supports this TLM2 style interface for
SystemVerilog to SystemVerilog communication. Mixed language TLM communication is
saved for future extension.
Summary
UVM 1.2 Class Reference
282
TLM2 Interfaces, Ports, Exports and Transport Interfaces Subset
Sockets group together all the necessary core interfaces for transportation and
binding, allowing more generic usage models than just TLM core interfaces.
UVM 1.2 Class Reference
283
15.1 Interface Masks
Each of the following macros is a mask that identifies which interfaces a particular port
requires or export provides. The interfaces are identified by bit position and can be
OR’ed together for combination ports/exports. The mask is used to do run-time interface
type checking of port/export connections.
Summary
Interface Masks
Each of the following macros is a mask that identifies which interfaces a particular
port requires or export provides.
MACROs
`UVM_TLM_NB_FW_MASK
`UVM_TLM_NB_BW_MASK
`UVM_TLM_B_MASK
Define Non blocking Forward mask onehot
assignment = ‘b001
Define Non blocking backward mask onehot
assignment = ‘b010
Define blocking mask onehot assignment =
‘b100
MACROs
`UVM_TLM_NB_FW_MASK
Define Non blocking Forward mask onehot assignment = ‘b001
`UVM_TLM_NB_BW_MASK
Define Non blocking backward mask onehot assignment = ‘b010
`UVM_TLM_B_MASK
Define blocking mask onehot assignment = ‘b100
UVM 1.2 Class Reference
284
15.2 TLM2 Types
Summary
TLM2 Types
ENUmeRAtIONs
uvm_tlm_phase_e
Nonblocking transport synchronization state
values between an initiator and a target.
Pre-defined phase state values for the
nonblocking transport Base Protocol between
an initiator and a target.
uvm_tlm_sync_e
MACROs
`UVM_TLM_TASK_ERROR
`UVM_TLM_FUNCTION_ERROR
Defines Not-Yet-Implemented TLM tasks
Defines Not-Yet-Implemented TLM functions
ENUmeRAtIONs
uvm_tlm_phase_e
Nonblocking transport synchronization state values between an initiator and a target.
UNINITIALIZED_PHASE
Defaults for constructor
BEGIN_REQ
Beginning of request phase
END_REQ
End of request phase
BEGIN_RESP
Beginning of response phase
END_RESP
End of response phase
uvm_tlm_sync_e
Pre-defined phase state values for the nonblocking transport Base Protocol between an
initiator and a target.
UVM_TLM_ACCEPTED
Transaction has been accepted
UVM_TLM_UPDATED
Transaction has been modified
UVM_TLM_COMPLETED
Execution of transaction is complete
MACROs
`UVM_TLM_TASK_ERROR
Defines Not-Yet-Implemented TLM tasks
UVM 1.2 Class Reference
285
`UVM_TLM_FUNCTION_ERROR
Defines Not-Yet-Implemented TLM functions
uvm_tlm_if
Base class type to define the transport functions.
nb_transport_fw
nb_transport_bw
b_transport
Summary
uvm_tlm_if
Base class type to define the transport functions.
ClAss DeClARAtION
class uvm_tlm_if #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
)
tlm tRANsPORt
metHOds
nb_transport_fw
nb_transport_bw
b_transport
Each of the interface methods take a handle to the
transaction to be transported and a reference argument
for the delay.
Forward path call.
Implementation of the backward path.
Execute a blocking transaction.
tlm tRANsPORt metHOds
Each of the interface methods take a handle to the transaction to be transported and a
reference argument for the delay. In addition, the nonblocking interfaces take a
reference argument for the phase.
nb_transport_fw
virtual function uvm_tlm_sync_e nb_transport_fw(
T t,
ref P p,
input uvm_tlm_time delay
)
Forward path call. The first call to this method for a transaction marks the initial timing
point. Every call to this method may mark a timing point in the execution of the
transaction. The timing annotation argument allows the timing points to be offset from
the simulation times at which the forward path is used. The final timing point of a
transaction may be marked by a call to nb_transport_bw or a return from this or
subsequent call to nb_transport_fw.
See TLM2 Interfaces, Ports, Exports and Transport Interfaces Subset for more details on
UVM 1.2 Class Reference
286
the semantics and rules of the nonblocking transport interface.
nb_transport_bw
virtual function uvm_tlm_sync_e nb_transport_bw(
T t,
ref P p,
input uvm_tlm_time delay
)
Implementation of the backward path. This function MUST be implemented in the
INITIATOR component class.
Every call to this method may mark a timing point, including the final timing point, in the
execution of the transaction. The timing annotation argument allows the timing point to
be offset from the simulation times at which the backward path is used. The final timing
point of a transaction may be marked by a call to nb_transport_fw or a return from this
or subsequent call to nb_transport_bw.
See TLM2 Interfaces, Ports, Exports and Transport Interfaces Subset for more details on
the semantics and rules of the nonblocking transport interface.
Example
class master extends uvm_component;
uvm_tlm_nb_initiator_socket #(trans, uvm_tlm_phase_e, this_t) initiator_socket;
...
function void build_phase(uvm_phase phase);
initiator_socket = new(“initiator_socket”, this, this);
endfunction
function uvm_tlm_sync_e nb_transport_bw(ref trans t,
ref uvm_tlm_phase_e p,
input uvm_tlm_time delay);
transaction = t;
state = p;
return UVM_TLM_ACCEPTED;
endfunction
...
endclass
b_transport
virtual task b_transport(
T t,
uvm_tlm_time delay
)
Execute a blocking transaction. Once this method returns, the transaction is assumed to
have been executed. Whether that execution is successful or not must be indicated by
UVM 1.2 Class Reference
287
the transaction itself.
The callee may modify or update the transaction object, subject to any constraints
imposed by the transaction class. The initiator may re-use a transaction object from one
call to the next and across calls to b_transport().
The call to b_transport shall mark the first timing point of the transaction. The return
from b_transport shall mark the final timing point of the transaction. The timing
annotation argument allows the timing points to be offset from the simulation times at
which the task call and return are executed.
UVM 1.2 Class Reference
288
15.3 TLM Generic Payload & Extensions
The Generic Payload transaction represents a generic bus read/write access. It is used as
the default transaction in TLM2 blocking and nonblocking transport interfaces.
Contents
TLM Generic Payload &
Extensions
The Generic Payload transaction represents a
generic bus read/write access.
GlOBAlS
uvm_tlm_command_e
uvm_tlm_response_status_e
Defines, Constants, enums.
Command attribute type definition
Response status attribute type definition
GeNeRIc PAYlOAD
uvm_tlm_generic_payload
This class provides a transaction definition
commonly used in memory-mapped bus-based
systems.
This typedef provides a short, more convenient
name for the uvm_tlm_generic_payload type.
The class uvm_tlm_extension_base is the nonparameterized base class for all generic payload
extensions.
TLM extension class.
uvm_tlm_gp
uvm_tlm_extension_base
uvm_tlm_extension
GlOBAlS
Defines, Constants, enums.
uvm_tlm_command_e
Command attribute type definition
UVM_TLM_READ_COMMAND
Bus read operation
UVM_TLM_WRITE_COMMAND
Bus write operation
UVM_TLM_IGNORE_COMMAND
No bus operation.
uvm_tlm_response_status_e
Response status attribute type definition
UVM_TLM_OK_RESPONSE
Bus operation completed
successfully
UVM_TLM_INCOMPLETE_RESPONSE
Transaction was not delivered
to target
UVM_TLM_GENERIC_ERROR_RESPONSE
Bus operation had an error
UVM_TLM_ADDRESS_ERROR_RESPONSE
Invalid address specified
UVM_TLM_COMMAND_ERROR_RESPONSE
Invalid command specified
UVM_TLM_BURST_ERROR_RESPONSE
Invalid burst specified
UVM_TLM_BYTE_ENABLE_ERROR_RESPONSE
Invalid byte enabling specified
UVM 1.2 Class Reference
289
GeNeRIc PAYlOAD
uvm_tlm_generic_payload
This class provides a transaction definition commonly used in memory-mapped bus-based
systems. It’s intended to be a general purpose transaction class that lends itself to many
applications. The class is derived from uvm_sequence_item which enables it to be
generated in sequences and transported to drivers through sequencers.
Summary
uvm_tlm_generic_payload
This class provides a transaction definition commonly used in memory-mapped
bus-based systems.
ClASS HIeRARchY
uvm_void
uvm_object
uvm_transaction
uvm_sequence_item
uvm_tlm_generic_payload
ClASS DeclARAtION
class uvm_tlm_generic_payload extends uvm_sequence_item
m_address
m_command
m_data
m_length
m_response_status
m_dmi
m_byte_enable
m_byte_enable_length
m_streaming_width
new
AcceSSORS
get_command
set_command
is_read
set_read
is_write
set_write
UVM 1.2 Class Reference
Address for the bus operation.
Bus operation type.
Data read or to be written.
The number of bytes to be copied to or from the
m_data array, inclusive of any bytes disabled by
the m_byte_enable attribute.
Status of the bus operation.
DMI mode is not yet supported in the UVM TLM2
subset.
Indicates valid m_data array elements.
The number of elements in the m_byte_enable
array.
Number of bytes transferred on each beat.
Create a new instance of the generic payload.
The accessor functions let you set and get each of
the members of the generic payload.
Get the value of the m_command variable
Set the value of the m_command variable
Returns true if the current value of the
m_command variable is
UVM_TLM_READ_COMMAND.
Set the current value of the m_command variable
to UVM_TLM_READ_COMMAND.
Returns true if the current value of the
m_command variable is
UVM_TLM_WRITE_COMMAND.
Set the current value of the m_command variable
290
set_address
get_address
get_data
set_data
get_data_length
set_data_length
get_streaming_width
set_streaming_width
get_byte_enable
set_byte_enable
get_byte_enable_length
set_byte_enable_length
set_dmi_allowed
is_dmi_allowed
get_response_status
set_response_status
is_response_ok
is_response_error
get_response_string
EXteNSIONS MechANISm
set_extension
get_num_extensions
get_extension
clear_extension
clear_extensions
pre_randomize()
post_randomize()
to UVM_TLM_WRITE_COMMAND.
Set the value of the m_address variable
Get the value of the m_address variable
Return the value of the m_data array
Set the value of the m_data array
Return the current size of the m_data array
Set the value of the m_length
Get the value of the m_streaming_width array
Set the value of the m_streaming_width array
Return the value of the m_byte_enable array
Set the value of the m_byte_enable array
Return the current size of the m_byte_enable
array
Set the size m_byte_enable_length of the
m_byte_enable array
DMI hint.
DMI hint.
Return the current value of the
m_response_status variable
Set the current value of the m_response_status
variable
Return TRUE if the current value of the
m_response_status variable is
UVM_TLM_OK_RESPONSE
Return TRUE if the current value of the
m_response_status variable is not
UVM_TLM_OK_RESPONSE
Return the current value of the
m_response_status variable as a string
Add an instance-specific extension.
Return the current number of instance specific
extensions.
Return the instance specific extension bound
under the specified key.
Remove the instance-specific extension bound
under the specified key.
Remove all instance-specific extensions
Prepare this class instance for randomization
Clean-up this class instance after randomization
m_address
rand bit [63:0] m_address
Address for the bus operation. Should be set or read using the set_address and
get_address methods. The variable should be used only when constraining.
For a read command or a write command, the target shall interpret the current value of
the address attribute as the start address in the system memory map of the contiguous
block of data being read or written. The address associated with any given byte in the
data array is dependent upon the address attribute, the array index, the streaming width
attribute, the endianness and the width of the physical bus.
If the target is unable to execute the transaction with the given address attribute
(because the address is out-of-range, for example) it shall generate a standard error
response. The recommended response status is UVM_TLM_ADDRESS_ERROR_RESPONSE.
m_command
UVM 1.2 Class Reference
291
rand uvm_tlm_command_e m_command
Bus operation type. Should be set using the set_command, set_read or set_write
methods and read using the get_command, is_read or is_write methods. The variable
should be used only when constraining.
If the target is unable to execute a read or write command, it shall generate a standard
error response. The recommended response status is
UVM_TLM_COMMAND_ERROR_RESPONSE.
On receipt of a generic payload transaction with the command attribute equal to
UVM_TLM_IGNORE_COMMAND, the target shall not execute a write command or a read
command not modify any data. The target may, however, use the value of any attribute
in the generic payload, including any extensions.
The command attribute shall be set by the initiator, and shall not be overwritten by any
interconnect
m_data
rand byte unsigned m_data[]
Data read or to be written. Should be set and read using the set_data or get_data
methods The variable should be used only when constraining.
For a read command or a write command, the target shall copy data to or from the data
array, respectively, honoring the semantics of the remaining attributes of the generic
payload.
For a write command or UVM_TLM_IGNORE_COMMAND, the contents of the data array
shall be set by the initiator, and shall not be overwritten by any interconnect component
or target. For a read command, the contents of the data array shall be overwritten by
the target (honoring the semantics of the byte enable) but by no other component.
Unlike the OSCI TLM-2.0 LRM, there is no requirement on the endiannes of multi-byte
data in the generic payload to match the host endianness. Unlike C++, it is not possible
in SystemVerilog to cast an arbitrary data type as an array of bytes. Therefore,
matching the host endianness is not necessary. In contrast, arbitrary data types may be
converted to and from a byte array using the streaming operator and uvm_object objects
may be further converted using the uvm_object::pack_bytes() and
uvm_object::unpack_bytes() methods. All that is required is that a consistent
mechanism is used to fill the payload data array and later extract data from it.
Should a generic payload be transferred to/from a SystemC model, it will be necessary
for any multi-byte data in that generic payload to use/be interpreted using the host
endianness. However, this process is currently outside the scope of this standard.
m_length
rand int unsigned m_length
The number of bytes to be copied to or from the m_data array, inclusive of any bytes
disabled by the m_byte_enable attribute.
The data length attribute shall be set by the initiator, and shall not be overwritten by any
interconnect component or target.
The data length attribute shall not be set to 0. In order to transfer zero bytes, the
UVM 1.2 Class Reference
292
m_command attribute should be set to UVM_TLM_IGNORE_COMMAND.
m_response_status
rand uvm_tlm_response_status_e m_response_status
Status of the bus operation. Should be set using the set_response_status method and
read using the get_response_status, get_response_string, is_response_ok or
is_response_error methods. The variable should be used only when constraining.
The response status attribute shall be set to UVM_TLM_INCOMPLETE_RESPONSE by the
initiator, and may be overwritten by the target. The response status attribute should not
be overwritten by any interconnect component, because the default value
UVM_TLM_INCOMPLETE_RESPONSE indicates that the transaction was not delivered to
the target.
The target may set the response status attribute to UVM_TLM_OK_RESPONSE to indicate
that it was able to execute the command successfully, or to one of the five error
responses to indicate an error. The target should choose the appropriate error response
depending on the cause of the error. If a target detects an error but is unable to select
a specific error response, it may set the response status to
UVM_TLM_GENERIC_ERROR_RESPONSE.
The target shall be responsible for setting the response status attribute at the
appropriate point in the lifetime of the transaction. In the case of the blocking transport
interface, this means before returning control from b_transport. In the case of the nonblocking transport interface and the base protocol, this means before sending the
BEGIN_RESP phase or returning a value of UVM_TLM_COMPLETED.
It is recommended that the initiator should always check the response status attribute on
receiving a transition to the BEGIN_RESP phase or after the completion of the
transaction. An initiator may choose to ignore the response status if it is known in
advance that the value will be UVM_TLM_OK_RESPONSE, perhaps because it is known in
advance that the initiator is only connected to targets that always return
UVM_TLM_OK_RESPONSE, but in general this will not be the case. In other words, the
initiator ignores the response status at its own risk.
m_dmi
bit m_dmi
DMI mode is not yet supported in the UVM TLM2 subset. This variable is provided for
completeness and interoperability with SystemC.
m_byte_enable
rand byte unsigned m_byte_enable[]
Indicates valid m_data array elements. Should be set and read using the
set_byte_enable or get_byte_enable methods The variable should be used only when
constraining.
The elements in the byte enable array shall be interpreted as follows. A value of 8’h00
shall indicate that that corresponding byte is disabled, and a value of 8’hFF shall indicate
that the corresponding byte is enabled.
UVM 1.2 Class Reference
293
Byte enables may be used to create burst transfers where the address increment
between each beat is greater than the number of significant bytes transferred on each
beat, or to place words in selected byte lanes of a bus. At a more abstract level, byte
enables may be used to create “lacy bursts” where the data array of the generic payload
has an arbitrary pattern of holes punched in it.
The byte enable mask may be defined by a small pattern applied repeatedly or by a large
pattern covering the whole data array. The byte enable array may be empty, in which
case byte enables shall not be used for the current transaction.
The byte enable array shall be set by the initiator and shall not be overwritten by any
interconnect component or target.
If the byte enable pointer is not empty, the target shall either implement the semantics
of the byte enable as defined below or shall generate a standard error response. The
recommended response status is UVM_TLM_BYTE_ENABLE_ERROR_RESPONSE.
In the case of a write command, any interconnect component or target should ignore the
values of any disabled bytes in the m_data array. In the case of a read command, any
interconnect component or target should not modify the values of disabled bytes in the
m_data array.
m_byte_enable_length
rand int unsigned m_byte_enable_length
The number of elements in the m_byte_enable array.
It shall be set by the initiator, and shall not be overwritten by any interconnect
component or target.
m_streaming_width
rand int unsigned m_streaming_width
Number of bytes transferred on each beat. Should be set and read using the
set_streaming_width or get_streaming_width methods The variable should be used only
when constraining.
Streaming affects the way a component should interpret the data array. A stream
consists of a sequence of data transfers occurring on successive notional beats, each beat
having the same start address as given by the generic payload address attribute. The
streaming width attribute shall determine the width of the stream, that is, the number of
bytes transferred on each beat. In other words, streaming affects the local address
associated with each byte in the data array. In all other respects, the organization of the
data array is unaffected by streaming.
The bytes within the data array have a corresponding sequence of local addresses within
the component accessing the generic payload transaction. The lowest address is given by
the value of the address attribute. The highest address is given by the formula
address_attribute + streaming_width - 1. The address to or from which each byte is
being copied in the target shall be set to the value of the address attribute at the start
of each beat.
With respect to the interpretation of the data array, a single transaction with a streaming
width shall be functionally equivalent to a sequence of transactions each having the same
address as the original transaction, each having a data length attribute equal to the
streaming width of the original, and each with a data array that is a different subset of
UVM 1.2 Class Reference
294
the original data array on each beat. This subset effectively steps down the original data
array maintaining the sequence of bytes.
A streaming width of 0 indicates that a streaming transfer is not required. it is equivalent
to a streaming width value greater than or equal to the size of the m_data array.
Streaming may be used in conjunction with byte enables, in which case the streaming
width would typically be equal to the byte enable length. It would also make sense to
have the streaming width a multiple of the byte enable length. Having the byte enable
length a multiple of the streaming width would imply that different bytes were enabled
on each beat.
If the target is unable to execute the transaction with the given streaming width, it shall
generate a standard error response. The recommended response status is
TLM_BURST_ERROR_RESPONSE.
new
function new(
string name = ""
)
Create a new instance of the generic payload. Initialize all the members to their default
values.
AcceSSORS
The accessor functions let you set and get each of the members of the generic payload. All of the accessor methods are virtual. This implies a slightly different use model for
the generic payload than in SystemC. The way the generic payload is defined in
SystemC does not encourage you to create new transaction types derived from
uvm_tlm_generic_payload. Instead, you would use the extensions mechanism. Thus in
SystemC none of the accessors are virtual.
get_command
virtual function uvm_tlm_command_e get_command()
Get the value of the m_command variable
set_command
virtual function void set_command(
uvm_tlm_command_e command
)
Set the value of the m_command variable
is_read
virtual function bit is_read()
Returns true if the current value of the m_command variable is
UVM 1.2 Class Reference
295
UVM_TLM_READ_COMMAND.
set_read
virtual function void set_read()
Set the current value of the m_command variable to UVM_TLM_READ_COMMAND.
is_write
virtual function bit is_write()
Returns true if the current value of the m_command variable is
UVM_TLM_WRITE_COMMAND.
set_write
virtual function void set_write()
Set the current value of the m_command variable to UVM_TLM_WRITE_COMMAND.
set_address
virtual function void set_address(
bit [63:0] addr
)
Set the value of the m_address variable
get_address
virtual function bit [63:0] get_address()
Get the value of the m_address variable
get_data
virtual function void get_data (
output byte unsigned p []
)
Return the value of the m_data array
set_data
virtual function void set_data(
ref byte unsigned p []
)
Set the value of the m_data array
UVM 1.2 Class Reference
296
get_data_length
virtual function int unsigned get_data_length()
Return the current size of the m_data array
set_data_length
virtual function void set_data_length(
int unsigned length
)
Set the value of the m_length
get_streaming_width
virtual function int unsigned get_streaming_width()
Get the value of the m_streaming_width array
set_streaming_width
virtual function void set_streaming_width(
int unsigned width
)
Set the value of the m_streaming_width array
get_byte_enable
virtual function void get_byte_enable(
output byte unsigned p[]
)
Return the value of the m_byte_enable array
set_byte_enable
virtual function void set_byte_enable(
ref byte unsigned p[]
)
Set the value of the m_byte_enable array
get_byte_enable_length
virtual function int unsigned get_byte_enable_length()
Return the current size of the m_byte_enable array
UVM 1.2 Class Reference
297
set_byte_enable_length
virtual function void set_byte_enable_length(
int unsigned length
)
Set the size m_byte_enable_length of the m_byte_enable array i.e. m_byte_enable.size()
set_dmi_allowed
virtual function void set_dmi_allowed(
bit dmi
)
DMI hint. Set the internal flag m_dmi to allow dmi access
is_dmi_allowed
virtual function bit is_dmi_allowed()
DMI hint. Query the internal flag m_dmi if allowed dmi access
get_response_status
virtual function uvm_tlm_response_status_e get_response_status()
Return the current value of the m_response_status variable
set_response_status
virtual function void set_response_status(
uvm_tlm_response_status_e status
)
Set the current value of the m_response_status variable
is_response_ok
virtual function bit is_response_ok()
Return TRUE if the current value of the m_response_status variable is
UVM_TLM_OK_RESPONSE
is_response_error
virtual function bit is_response_error()
Return TRUE if the current value of the m_response_status variable is not
UVM_TLM_OK_RESPONSE
UVM 1.2 Class Reference
298
get_response_string
virtual function string get_response_string()
Return the current value of the m_response_status variable as a string
EXteNSIONS MechANISm
set_extension
function uvm_tlm_extension_base set_extension(
uvm_tlm_extension_base ext
)
Add an instance-specific extension. Only one instance of any given extension type is
allowed. If there is an existing extension instance of the type of ext, ext replaces it and
its handle is returned. Otherwise, null is returned.
get_num_extensions
function int get_num_extensions()
Return the current number of instance specific extensions.
get_extension
function uvm_tlm_extension_base get_extension(
uvm_tlm_extension_base ext_handle
)
Return the instance specific extension bound under the specified key. If no extension is
bound under that key, null is returned.
clear_extension
function void clear_extension(
uvm_tlm_extension_base ext_handle
)
Remove the instance-specific extension bound under the specified key.
clear_extensions
function void clear_extensions()
Remove all instance-specific extensions
pre_randomize()
UVM 1.2 Class Reference
299
function void pre_randomize()
Prepare this class instance for randomization
post_randomize()
function void post_randomize()
Clean-up this class instance after randomization
uvm_tlm_gp
This typedef provides a short, more convenient name for the uvm_tlm_generic_payload
type.
Summary
uvm_tlm_gp
This typedef provides a short, more convenient name for the
uvm_tlm_generic_payload type.
ClASS DeclARAtION
typedef uvm_tlm_generic_payload uvm_tlm_gp
uvm_tlm_extension_base
The class uvm_tlm_extension_base is the non-parameterized base class for all generic
payload extensions. It includes the utility do_copy() and create(). The pure virtual
function get_type_handle() allows you to get a unique handle that represents the derived
type. This is implemented in derived classes.
This class is never used directly by users. The uvm_tlm_extension class is used instead.
Summary
uvm_tlm_extension_base
The class uvm_tlm_extension_base is the non-parameterized base class for all
generic payload extensions.
ClASS HIeRARchY
uvm_void
uvm_object
uvm_tlm_extension_base
ClASS DeclARAtION
UVM 1.2 Class Reference
300
virtual class uvm_tlm_extension_base extends uvm_object
MethODS
new
get_type_handle
get_type_handle_name
create
An interface to polymorphically retrieve a handle
that uniquely identifies the type of the sub-class
An interface to polymorphically retrieve the name
that uniquely identifies the type of the sub-class
MethODS
new
function new(
string name = ""
)
get_type_handle
pure virtual function uvm_tlm_extension_base get_type_handle()
An interface to polymorphically retrieve a handle that uniquely identifies the type of the
sub-class
get_type_handle_name
pure virtual function string get_type_handle_name()
An interface to polymorphically retrieve the name that uniquely identifies the type of the
sub-class
create
virtual function uvm_object create (
string name = ""
)
uvm_tlm_extension
TLM extension class. The class is parameterized with arbitrary type which represents the
type of the extension. An instance of the generic payload can contain one extension
object of each type; it cannot contain two instances of the same extension type.
The extension type can be identified using the ID() method.
To implement a generic payload extension, simply derive a new class from this class and
specify the name of the derived class as the extension parameter.
UVM 1.2 Class Reference
301
class my_ID extends uvm_tlm_extension#(my_ID);
int ID;
`uvm_object_utils_begin(my_ID)
`uvm_field_int(ID, UVM_ALL_ON)
`uvm_object_utils_end
function new(string name = "my_ID");
super.new(name);
endfunction
endclass
Summary
uvm_tlm_extension
TLM extension class.
ClASS HIeRARchY
uvm_void
uvm_object
uvm_tlm_extension_base
uvm_tlm_extension
ClASS DeclARAtION
class uvm_tlm_extension #(
type T = int
) extends uvm_tlm_extension_base
MethODS
new
ID()
creates a new extension object.
Return the unique ID of this TLM extension type.
MethODS
new
function new(
string name = ""
)
creates a new extension object.
ID()
static function this_type ID()
Return the unique ID of this TLM extension type. This method is used to identify the
type of the extension to retrieve from a uvm_tlm_generic_payload instance, using the
uvm_tlm_generic_payload::get_extension() method.
UVM 1.2 Class Reference
302
15.4 TLM Socket Base Classes
A collection of base classes, one for each socket type. The reason for having a base
class for each socket is that all the socket (base) types must be known before connect is
defined. Socket connection semantics are provided in the derived classes, which are user
visible.
Termination Sockets
A termination socket must be the terminus of every
TLM path. A transaction originates with an initiator
socket and ultimately ends up in a target socket. There may be zero or more pass-through sockets
between initiator and target.
Pass-through Sockets
Pass-through initiators are ports and contain exports
for instance IS-A port and HAS-A export. Passthrough targets are the opposite, they are exports and
contain ports.
Contents
TLM Socket Base Classes
A collection of base classes,
one for each socket type.
uvm_tlm_b_target_socket_base
IS-A forward imp; has no
backward path except via the
payload contents.
IS-A forward port; has no
backward path except via the
payload contents
IS-A forward imp; HAS-A
backward port
IS-A forward port; HAS-A
backward imp
IS-A forward port; HAS-A
backward export
IS-A forward export; HAS-A
backward port
IS-A forward port
IS-A forward export
uvm_tlm_b_initiator_socket_base
uvm_tlm_nb_target_socket_base
uvm_tlm_nb_initiator_socket_base
uvm_tlm_nb_passthrough_initiator_socket_base
uvm_tlm_nb_passthrough_target_socket_base
uvm_tlm_b_passthrough_initiator_socket_base
uvm_tlm_b_passthrough_target_socket_base
uvm_tlm_b_target_socket_base
IS-A forward imp; has no backward path except via the payload contents.
Summary
uvm_tlm_b_target_socket_base
IS-A forward imp; has no backward path except via the payload contents.
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T))
uvm_tlm_b_target_socket_base
UVM 1.2 Class Reference
303
ClAss DEclARAtION
class uvm_tlm_b_target_socket_base #(
type T = uvm_tlm_generic_payload
) extends uvm_port_base #(uvm_tlm_if #(T))
uvm_tlm_b_initiator_socket_base
IS-A forward port; has no backward path except via the payload contents
Summary
uvm_tlm_b_initiator_socket_base
IS-A forward port; has no backward path except via the payload contents
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T))
uvm_tlm_b_initiator_socket_base
ClAss DEclARAtION
class uvm_tlm_b_initiator_socket_base #(
type T = uvm_tlm_generic_payload
) extends uvm_port_base #(uvm_tlm_if #(T))
uvm_tlm_nb_target_socket_base
IS-A forward imp; HAS-A backward port
Summary
uvm_tlm_nb_target_socket_base
IS-A forward imp; HAS-A backward port
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_target_socket_base
ClAss DEclARAtION
class uvm_tlm_nb_target_socket_base #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_port_base #(uvm_tlm_if #(T,P))
UVM 1.2 Class Reference
304
uvm_tlm_nb_initiator_socket_base
IS-A forward port; HAS-A backward imp
Summary
uvm_tlm_nb_initiator_socket_base
IS-A forward port; HAS-A backward imp
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_initiator_socket_base
ClAss DEclARAtION
class uvm_tlm_nb_initiator_socket_base #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_port_base #(uvm_tlm_if #(T,P))
uvm_tlm_nb_passthrough_initiator_socket_base
IS-A forward port; HAS-A backward export
Summary
uvm_tlm_nb_passthrough_initiator_socket_base
IS-A forward port; HAS-A backward export
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_passthrough_initiator_socket_base
ClAss DEclARAtION
class uvm_tlm_nb_passthrough_initiator_socket_base #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_port_base #(uvm_tlm_if #(T,P))
uvm_tlm_nb_passthrough_target_socket_base
IS-A forward export; HAS-A backward port
Summary
UVM 1.2 Class Reference
305
uvm_tlm_nb_passthrough_target_socket_base
IS-A forward export; HAS-A backward port
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_passthrough_target_socket_base
ClAss DEclARAtION
class uvm_tlm_nb_passthrough_target_socket_base #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_port_base #(uvm_tlm_if #(T,P))
uvm_tlm_b_passthrough_initiator_socket_base
IS-A forward port
Summary
uvm_tlm_b_passthrough_initiator_socket_base
IS-A forward port
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T))
uvm_tlm_b_passthrough_initiator_socket_base
ClAss DEclARAtION
class uvm_tlm_b_passthrough_initiator_socket_base #(
type T = uvm_tlm_generic_payload
) extends uvm_port_base #(uvm_tlm_if #(T))
uvm_tlm_b_passthrough_target_socket_base
IS-A forward export
Summary
uvm_tlm_b_passthrough_target_socket_base
IS-A forward export
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T))
uvm_tlm_b_passthrough_target_socket_base
UVM 1.2 Class Reference
306
ClAss DEclARAtION
class uvm_tlm_b_passthrough_target_socket_base #(
type T = uvm_tlm_generic_payload
) extends uvm_port_base #(uvm_tlm_if #(T))
UVM 1.2 Class Reference
307
15.5 TLM Sockets
Each uvm_tlm_*_socket class is derived from a corresponding uvm_tlm_*_socket_base
class. The base class contains most of the implementation of the class, The derived
classes (in this file) contain the connection semantics.
Sockets come in several flavors: Each socket is either an initiator or a target, a passthrough or a terminator. Further, any particular socket implements either the blocking
interfaces or the nonblocking interfaces. Terminator sockets are used on initiators and
targets as well as interconnect components as shown in the figure above. Pass-through
sockets are used to enable connections to cross hierarchical boundaries.
There are eight socket types: the cross of blocking and nonblocking, pass-through and
termination, target and initiator
Sockets are specified based on what they are (IS-A) and what they contains (HAS-A). IS-A and HAS-A are types of object relationships. IS-A refers to the inheritance
relationship and HAS-A refers to the ownership relationship. For example if you say D is
a B that means that D is derived from base B. If you say object A HAS-A B that means
that B is a member of A.
Contents
TLM Sockets
Each uvm_tlm_*_socket class is
derived from a corresponding
uvm_tlm_*_socket_base class.
uvm_tlm_b_initiator_socket
IS-A forward port; has no backward
path except via the payload contents
IS-A forward imp; has no backward
path except via the payload contents.
IS-A forward port; HAS-A backward
imp
IS-A forward imp; HAS-A backward
port
IS-A forward port;
IS-A forward export;
IS-A forward port; HAS-A backward
export
IS-A forward export; HAS-A
backward port
uvm_tlm_b_target_socket
uvm_tlm_nb_initiator_socket
uvm_tlm_nb_target_socket
uvm_tlm_b_passthrough_initiator_socket
uvm_tlm_b_passthrough_target_socket
uvm_tlm_nb_passthrough_initiator_socket
uvm_tlm_nb_passthrough_target_socket
uvm_tlm_b_initiator_socket
IS-A forward port; has no backward path except via the payload contents
Summary
uvm_tlm_b_initiator_socket
IS-A forward port; has no backward path except via the payload contents
ClAss HIERARchY
uvm_tlm_b_initiator_socket_base#(T)
UVM 1.2 Class Reference
308
uvm_tlm_b_initiator_socket
ClAss DEclARAtION
class uvm_tlm_b_initiator_socket #(
type T = uvm_tlm_generic_payload
) extends uvm_tlm_b_initiator_socket_base #(T)
MEthOds
new
Connect
Construct a new instance of this socket
Connect this socket to the specified uvm_tlm_b_target_socket
MEthOds
new
function new(
string name,
uvm_component parent
)
Construct a new instance of this socket
Connect
Connect this socket to the specified uvm_tlm_b_target_socket
uvm_tlm_b_target_socket
IS-A forward imp; has no backward path except via the payload contents.
The component instantiating this socket must implement a b_transport() method with the
following signature
task b_transport(T t, uvm_tlm_time delay);
Summary
uvm_tlm_b_target_socket
IS-A forward imp; has no backward path except via the payload contents.
ClAss HIERARchY
uvm_tlm_b_target_socket_base#(T)
uvm_tlm_b_target_socket
ClAss DEclARAtION
class uvm_tlm_b_target_socket #(
UVM 1.2 Class Reference
309
type IMP = int,
type T = uvm_tlm_generic_payload
) extends uvm_tlm_b_target_socket_base #(T)
MEthOds
new
Connect
Construct a new instance of this socket imp is a reference to the
class implementing the b_transport() method.
Connect this socket to the specified uvm_tlm_b_initiator_socket
MEthOds
new
function new (
string name, uvm_component parent, IMP imp
= null
)
Construct a new instance of this socket imp is a reference to the class implementing the
b_transport() method. If not specified, it is assume to be the same as parent.
Connect
Connect this socket to the specified uvm_tlm_b_initiator_socket
uvm_tlm_nb_initiator_socket
IS-A forward port; HAS-A backward imp
The component instantiating this socket must implement a nb_transport_bw() method
with the following signature
function uvm_tlm_sync_e nb_transport_bw(T t, ref P p, input uvm_tlm_time
delay);
Summary
uvm_tlm_nb_initiator_socket
IS-A forward port; HAS-A backward imp
ClAss HIERARchY
uvm_tlm_nb_initiator_socket_base#(T,P)
uvm_tlm_nb_initiator_socket
ClAss DEclARAtION
class uvm_tlm_nb_initiator_socket #(
UVM 1.2 Class Reference
310
type IMP = int,
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_tlm_nb_initiator_socket_base #(T,P)
MEthOds
new
Connect
Construct a new instance of this socket imp is a reference to the
class implementing the nb_transport_bw() method.
Connect this socket to the specified uvm_tlm_nb_target_socket
MEthOds
new
function new(
string name, uvm_component parent, IMP imp
= null
)
Construct a new instance of this socket imp is a reference to the class implementing the
nb_transport_bw() method. If not specified, it is assume to be the same as parent.
Connect
Connect this socket to the specified uvm_tlm_nb_target_socket
uvm_tlm_nb_target_socket
IS-A forward imp; HAS-A backward port
The component instantiating this socket must implement a nb_transport_fw() method
with the following signature
function uvm_tlm_sync_e nb_transport_fw(T t, ref P p, input uvm_tlm_time
delay);
Summary
uvm_tlm_nb_target_socket
IS-A forward imp; HAS-A backward port
ClAss HIERARchY
uvm_tlm_nb_target_socket_base#(T,P)
uvm_tlm_nb_target_socket
ClAss DEclARAtION
UVM 1.2 Class Reference
311
class uvm_tlm_nb_target_socket #(
type IMP = int,
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_tlm_nb_target_socket_base #(T,P)
MEthOds
new
connect
Construct a new instance of this socket imp is a reference to the
class implementing the nb_transport_fw() method.
Connect this socket to the specified uvm_tlm_nb_initiator_socket
MEthOds
new
function new (
string name, uvm_component parent, IMP imp
= null
)
Construct a new instance of this socket imp is a reference to the class implementing the
nb_transport_fw() method. If not specified, it is assume to be the same as parent.
connect
function void connect(
this_type provider
)
Connect this socket to the specified uvm_tlm_nb_initiator_socket
uvm_tlm_b_passthrough_initiator_socket
IS-A forward port;
Summary
uvm_tlm_b_passthrough_initiator_socket
IS-A forward port;
ClAss HIERARchY
uvm_tlm_b_passthrough_initiator_socket_base#(T)
uvm_tlm_b_passthrough_initiator_socket
ClAss DEclARAtION
class uvm_tlm_b_passthrough_initiator_socket #(
type T = uvm_tlm_generic_payload
) extends uvm_tlm_b_passthrough_initiator_socket_base
#(T)
UVM 1.2 Class Reference
312
uvm_tlm_b_passthrough_target_socket
IS-A forward export;
Summary
uvm_tlm_b_passthrough_target_socket
IS-A forward export;
ClAss HIERARchY
uvm_tlm_b_passthrough_target_socket_base#(T)
uvm_tlm_b_passthrough_target_socket
ClAss DEclARAtION
class uvm_tlm_b_passthrough_target_socket #(
type T = uvm_tlm_generic_payload
) extends uvm_tlm_b_passthrough_target_socket_base #(T)
uvm_tlm_nb_passthrough_initiator_socket
IS-A forward port; HAS-A backward export
Summary
uvm_tlm_nb_passthrough_initiator_socket
IS-A forward port; HAS-A backward export
ClAss HIERARchY
uvm_tlm_nb_passthrough_initiator_socket_base#(T,P)
uvm_tlm_nb_passthrough_initiator_socket
ClAss DEclARAtION
class uvm_tlm_nb_passthrough_initiator_socket #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_tlm_nb_passthrough_initiator_socket_base
#(T,P)
uvm_tlm_nb_passthrough_target_socket
IS-A forward export; HAS-A backward port
UVM 1.2 Class Reference
313
Summary
uvm_tlm_nb_passthrough_target_socket
IS-A forward export; HAS-A backward port
ClAss HIERARchY
uvm_tlm_nb_passthrough_target_socket_base#(T,P)
uvm_tlm_nb_passthrough_target_socket
ClAss DEclARAtION
class uvm_tlm_nb_passthrough_target_socket #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_tlm_nb_passthrough_target_socket_base #(T,P)
MEthOds
connect
Connect this socket to the specified uvm_tlm_nb_initiator_socket
MEthOds
connect
function void connect(
this_type provider
)
Connect this socket to the specified uvm_tlm_nb_initiator_socket
UVM 1.2 Class Reference
314
15.6 TLM2 Export Classes
This section defines the export classes for connecting TLM2 interfaces.
Contents
TLM2 Export Classes
This section defines the export classes for
connecting TLM2 interfaces.
uvm_tlm_b_transport_export
uvm_tlm_nb_transport_fw_export
uvm_tlm_nb_transport_bw_export
Blocking transport export class.
Non-blocking forward transport export class
Non-blocking backward transport export class
uvm_tlm_b_transport_export
Blocking transport export class.
Summary
uvm_tlm_b_transport_export
Blocking transport export class.
ClAss HIeRARchY
uvm_port_base#(uvm_tlm_if#(T))
uvm_tlm_b_transport_export
ClAss DeclARAtION
class uvm_tlm_b_transport_export #(
type T = uvm_tlm_generic_payload
) extends uvm_port_base #(uvm_tlm_if #(T))
uvm_tlm_nb_transport_fw_export
Non-blocking forward transport export class
Summary
uvm_tlm_nb_transport_fw_export
Non-blocking forward transport export class
ClAss HIeRARchY
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_transport_fw_export
UVM 1.2 Class Reference
315
ClAss DeclARAtION
class uvm_tlm_nb_transport_fw_export #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_port_base #(uvm_tlm_if #(T,P))
uvm_tlm_nb_transport_bw_export
Non-blocking backward transport export class
Summary
uvm_tlm_nb_transport_bw_export
Non-blocking backward transport export class
ClAss HIeRARchY
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_transport_bw_export
ClAss DeclARAtION
class uvm_tlm_nb_transport_bw_export #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_port_base #(uvm_tlm_if #(T,P))
MethOds
new
MethOds
new
UVM 1.2 Class Reference
316
15.7 TLM2 imps (interface implementations)
This section defines the implementation classes for connecting TLM2 interfaces.
TLM imps bind a TLM interface with the object that contains the interface
implementation. In addition to the transaction type and the phase type, the imps are
parameterized with the type of the object that will provide the implementation. Most
often this will be the type of the component where the imp resides. The constructor of
the imp takes as an argument an object of type IMP and installs it as the
implementation object. Most often the imp constructor argument is “this”.
Contents
TLM2 imps (interface
implementations)
IMP BiNDiNG mAcROS
`UVM_TLM_NB_TRANSPORT_FW_IMP
`UVM_TLM_NB_TRANSPORT_BW_IMP
`UVM_TLM_B_TRANSPORT_IMP
IMP BiNDiNG clASSES
uvm_tlm_b_transport_imp
uvm_tlm_nb_transport_fw_imp
uvm_tlm_nb_transport_bw_imp
IMP
This section defines the implementation
classes for connecting TLM2 interfaces.
The macro wraps the forward path call
function nb_transport_fw()
Implementation of the backward path.
The macro wraps the function
b_transport() Execute a blocking
transaction.
Used like exports, except an additional
class parameter specifies the type of
the implementation object.
Used like exports, except an additional
class parameter specifies the type of
the implementation object.
Used like exports, except an additional
class parameter specifies the type of
the implementation object.
BiNDiNG mAcROS
`UVM_TLM_NB_TRANSPORT_FW_IMP
The macro wraps the forward path call function nb_transport_fw()
The first call to this method for a transaction marks the initial timing point. Every call to
this method may mark a timing point in the execution of the transaction. The timing
annotation argument allows the timing points to be offset from the simulation times at
which the forward path is used. The final timing point of a transaction may be marked
by a call to nb_transport_bw() within `UVM_TLM_NB_TRANSPORT_BW_IMP or a return
from this or subsequent call to nb_transport_fw().
See TLM2 Interfaces, Ports, Exports and Transport Interfaces Subset for more details on
the semantics and rules of the nonblocking transport interface.
`UVM_TLM_NB_TRANSPORT_BW_IMP
Implementation of the backward path. The macro wraps the function called
UVM 1.2 Class Reference
317
nb_transport_bw(). This function MUST be implemented in the INITIATOR component
class.
Every call to this method may mark a timing point, including the final timing point, in the
execution of the transaction. The timing annotation argument allows the timing point to
be offset from the simulation times at which the backward path is used. The final timing
point of a transaction may be marked by a call to nb_transport_fw() within
`UVM_TLM_NB_TRANSPORT_FW_IMP or a return from this or subsequent call to
nb_transport_bw().
See TLM2 Interfaces, Ports, Exports and Transport Interfaces Subset for more details on
the semantics and rules of the nonblocking transport interface.
Example
class master extends uvm_component;
uvm_tlm_nb_initiator_socket
#(trans, uvm_tlm_phase_e, this_t) initiator_socket;
function void build_phase(uvm_phase phase);
initiator_socket = new("initiator_socket", this, this);
endfunction
function uvm_tlm_sync_e nb_transport_bw(trans t,
ref uvm_tlm_phase_e p,
input uvm_tlm_time delay);
transaction = t;
state = p;
return UVM_TLM_ACCEPTED;
endfunction
...
endclass
`UVM_TLM_B_TRANSPORT_IMP
The macro wraps the function b_transport() Execute a blocking transaction. Once this
method returns, the transaction is assumed to have been executed. Whether that
execution is successful or not must be indicated by the transaction itself.
The callee may modify or update the transaction object, subject to any constraints
imposed by the transaction class. The initiator may re-use a transaction object from one
call to the next and across calls to b_transport().
The call to b_transport shall mark the first timing point of the transaction. The return
from b_transport() shall mark the final timing point of the transaction. The timing
annotation argument allows the timing points to be offset from the simulation times at
which the task call and return are executed.
IMP
BiNDiNG clASSES
uvm_tlm_b_transport_imp
Used like exports, except an additional class parameter specifies the type of the
implementation object. When the imp is instantiated the implementation object is
bound.
UVM 1.2 Class Reference
318
Summary
uvm_tlm_b_transport_imp
Used like exports, except an additional class parameter specifies the type of the
implementation object.
ClASS HiERARchY
uvm_port_base#(uvm_tlm_if#(T))
uvm_tlm_b_transport_imp
ClASS DEclARAtiON
class uvm_tlm_b_transport_imp #(
type T = uvm_tlm_generic_payload,
type IMP = int
) extends uvm_port_base #(uvm_tlm_if #(T))
uvm_tlm_nb_transport_fw_imp
Used like exports, except an additional class parameter specifies the type of the
implementation object. When the imp is instantiated the implementation object is
bound.
Summary
uvm_tlm_nb_transport_fw_imp
Used like exports, except an additional class parameter specifies the type of the
implementation object.
ClASS HiERARchY
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_transport_fw_imp
ClASS DEclARAtiON
class uvm_tlm_nb_transport_fw_imp #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e,
type IMP = int
) extends uvm_port_base #(uvm_tlm_if #(T,P))
uvm_tlm_nb_transport_bw_imp
Used like exports, except an additional class parameter specifies the type of the
implementation object. When the imp is instantiated the implementation object is
bound.
UVM 1.2 Class Reference
319
Summary
uvm_tlm_nb_transport_bw_imp
Used like exports, except an additional class parameter specifies the type of the
implementation object.
ClASS HiERARchY
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_transport_bw_imp
ClASS DEclARAtiON
class uvm_tlm_nb_transport_bw_imp #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e,
type IMP = int
) extends uvm_port_base #(uvm_tlm_if #(T,P))
UVM 1.2 Class Reference
320
15.8 TLM2 ports
The following defines TLM2 port classes.
Contents
TLM2 ports
The following defines TLM2 port classes.
uvm_tlm_b_transport_port
uvm_tlm_nb_transport_fw_port
Class providing the blocking transport port.
Class providing the non-blocking backward
transport port.
Class providing the non-blocking backward
transport port.
uvm_tlm_nb_transport_bw_port
uvm_tlm_b_transport_port
Class providing the blocking transport port. The port can be bound to one export. There
is no backward path for the blocking transport.
Summary
uvm_tlm_b_transport_port
Class providing the blocking transport port.
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T))
uvm_tlm_b_transport_port
ClAss DEclARAtION
class uvm_tlm_b_transport_port #(
type T = uvm_tlm_generic_payload
) extends uvm_port_base #(uvm_tlm_if #(T))
uvm_tlm_nb_transport_fw_port
Class providing the non-blocking backward transport port. Transactions received from
the producer, on the forward path, are sent back to the producer on the backward path
using this non-blocking transport port. The port can be bound to one export.
Summary
uvm_tlm_nb_transport_fw_port
Class providing the non-blocking backward transport port.
ClAss HIERARchY
UVM 1.2 Class Reference
321
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_transport_fw_port
ClAss DEclARAtION
class uvm_tlm_nb_transport_fw_port #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_port_base #(uvm_tlm_if #(T,P))
uvm_tlm_nb_transport_bw_port
Class providing the non-blocking backward transport port. Transactions received from
the producer, on the forward path, are sent back to the producer on the backward path
using this non-blocking transport port The port can be bound to one export.
Summary
uvm_tlm_nb_transport_bw_port
Class providing the non-blocking backward transport port.
ClAss HIERARchY
uvm_port_base#(uvm_tlm_if#(T,P))
uvm_tlm_nb_transport_bw_port
ClAss DEclARAtION
class uvm_tlm_nb_transport_bw_port #(
type T = uvm_tlm_generic_payload,
type P = uvm_tlm_phase_e
) extends uvm_port_base #(uvm_tlm_if #(T,P))
MEthOds
new
MEthOds
new
UVM 1.2 Class Reference
322
15.9 uvm_tlm_time
Canonical time type that can be used in different timescales
This time type is used to represent time values in a canonical form that can bridge
initiators and targets located in different timescales and time precisions.
For a detailed explanation of the purpose for this class, see Why is this necessary.
Summary
uvm_tlm_time
Canonical time type that can be used in different timescales
CLAss DEcLARATION
class uvm_tlm_time
set_time_resolution
new
get_name
reset
get_realtime
incr
decr
get_abstime
set_abstime
WHY
Is THIs
NEcEssARY
Set the default canonical time resolution.
Create a new canonical time value.
Return the name of this instance
Reset the value to 0
Return the current canonical time value, scaled for the
caller’s timescale
Increment the time value by the specified number of
scaled time unit
Decrement the time value by the specified number of
scaled time unit
Return the current canonical time value, in the number of
specified time unit, regardless of the current timescale of
the caller.
Set the current canonical time value, to the number of
specified time unit, regardless of the current timescale of
the caller.
Integers are not sufficient, on their own, to represent
time without any ambiguity: you need to know the scale
of that integer value.
set_time_resolution
static function void set_time_resolution(
real res
)
Set the default canonical time resolution.
Must be a power of 10. When co-simulating with SystemC, it is recommended that
default canonical time resolution be set to the SystemC time resolution.
By default, the default resolution is 1.0e-12 (ps)
new
function new(
string name = "uvm_tlm_time",
real res = 0
)
UVM 1.2 Class Reference
323
Create a new canonical time value.
The new value is initialized to 0. If a resolution is not specified, the default resolution,
as specified by set_time_resolution(), is used.
get_name
function string get_name()
Return the name of this instance
reset
function void reset()
Reset the value to 0
get_realtime
function real get_realtime(
time scaled, = 1.0e-9
real secs
)
Return the current canonical time value, scaled for the caller’s timescale
scaled must be a time literal value that corresponds to the number of seconds specified
in secs (1ns by default). It must be a time literal value that is greater or equal to the
current timescale.
#(delay.get_realtime(1ns));
#(delay.get_realtime(1fs, 1.0e-15));
incr
function void incr(
real t,
time scaled, real secs
= 1.0e-9
)
Increment the time value by the specified number of scaled time unit
t is a time value expressed in the scale and precision of the caller. scaled must be a
time literal value that corresponds to the number of seconds specified in secs (1ns by
default). It must be a time literal value that is greater or equal to the current timescale.
delay.incr(1.5ns, 1ns);
delay.incr(1.5ns, 1ps, 1.0e-12);
UVM 1.2 Class Reference
324
decr
function void decr(
real t,
time scaled,
real secs
)
Decrement the time value by the specified number of scaled time unit
t is a time value expressed in the scale and precision of the caller. scaled must be a
time literal value that corresponds to the number of seconds specified in secs (1ns by
default). It must be a time literal value that is greater or equal to the current timescale.
delay.decr(200ps, 1ns);
get_abstime
function real get_abstime(
real secs
)
Return the current canonical time value, in the number of specified time unit, regardless
of the current timescale of the caller.
secs is the number of seconds in the desired time unit e.g. 1e-9 for nanoseconds.
$write("%.3f ps\n", delay.get_abstime(1e-12));
set_abstime
function void set_abstime(
real t,
real secs
)
Set the current canonical time value, to the number of specified time unit, regardless of
the current timescale of the caller.
secs is the number of seconds in the time unit in the value t e.g. 1e-9 for nanoseconds.
delay.set_abstime(1.5, 1e-12));
WHY
Is THIs NEcEssARY
Integers are not sufficient, on their own, to represent time without any ambiguity: you
need to know the scale of that integer value. That scale is information conveyed outside
of that integer. In SystemVerilog, it is based on the timescale that was active when the
code was compiled. SystemVerilog properly scales time literals, but not integer values. UVM 1.2 Class Reference
325
That’s because it does not know the difference between an integer that carries an
integer value and an integer that carries a time value. The ‘time’ variables are simply
64-bit integers, they are not scaled back and forth to the underlying precision.
`timescale 1ns/1ps
module m();
time t;
initial
begin
#1.5;
$write("T=%f
t = 1.5;
#t;
$write("T=%f
#10ps;
$write("T=%f
t = 10ps;
#t;
$write("T=%f
end
endmodule
ns (1.5)\n", $realtime());
ns (3.0)\n", $realtime());
ns (3.010)\n", $realtime());
ns (3.020)\n", $realtime());
yields
T=1.500000
T=3.500000
T=3.510000
T=3.510000
ns
ns
ns
ns
(1.5)
(3.0)
(3.010)
(3.020)
Within SystemVerilog, we have to worry about
different time scale
different time precision
Because each endpoint in a socket could be coded in different packages and thus be
executing under different timescale directives, a simple integer cannot be used to
exchange time information across a socket.
For example
`timescale 1ns/1ps
package a_pkg;
class a;
function void f(inout time t);
t += 10ns;
endfunction
endclass
endpackage
`timescale 1ps/1ps
program p;
import a_pkg::*;
time t;
initial
begin
a A = new;
A.f(t);
#t;
$write("T=%0d ps (10,000)\n", $realtime());
end
endprogram
UVM 1.2 Class Reference
326
yields
T=10 ps (10,000)
Scaling is needed every time you make a procedural call to code that may interpret a
time value in a different timescale.
Using the uvm_tlm_time type
`timescale 1ns/1ps
package a_pkg;
import uvm_pkg::*;
class a;
function void f(uvm_tlm_time t);
t.incr(10ns, 1ns);
endfunction
endclass
endpackage
`timescale 1ps/1ps
program p;
import uvm_pkg::*;
import a_pkg::*;
uvm_tlm_time t = new;
initial
begin
a A = new;
A.f(t);
#(t.get_realtime(1ns));
$write("T=%0d ps (10,000)\n", $realtime());
end
endprogram
yields
T=10000 ps (10,000)
A similar procedure is required when crossing any simulator or language boundary, such
as interfacing between SystemVerilog and SystemC.
UVM 1.2 Class Reference
327
16. Analysis Ports
This section defines the port, export, and imp classes used for transaction analysis.
Contents
Analysis Ports
This section defines the port, export, and imp classes used
for transaction analysis.
uvm_analysis_port
Broadcasts a value to all subscribers implementing a
uvm_analysis_imp.
Receives all transactions broadcasted by a
uvm_analysis_port.
Exports a lower-level uvm_analysis_imp to its parent.
uvm_analysis_imp
uvm_analysis_export
uvm_analysis_port
Broadcasts a value to all subscribers implementing a uvm_analysis_imp.
class mon extends uvm_component;
uvm_analysis_port#(trans) ap;
function new(string name = "sb", uvm_component parent = null);
super.new(name, parent);
ap = new("ap", this);
endfunction
task run_phase(uvm_phase phase);
trans t;
...
ap.write(t);
...
endfunction
endclass
Summary
uvm_analysis_port
Broadcasts a value to all subscribers implementing a uvm_analysis_imp.
CLass HIERaRchY
uvm_port_base#(uvm_tlm_if_base#(T,T))
uvm_analysis_port
CLass DEcLaRaTION
class uvm_analysis_port # (
type T = int
) extends uvm_port_base # (uvm_tlm_if_base #(T,T))
METhOds
write
UVM 1.2 Class Reference
Send specified value to all connected interface
328
METhOds
write
function void write (
input T t
)
Send specified value to all connected interface
uvm_analysis_imp
Receives all transactions broadcasted by a uvm_analysis_port. It serves as the
termination point of an analysis port/export/imp connection. The component attached to
the imp class--called a subscriber-- implements the analysis interface.
Will invoke the write(T) method in the parent component. The implementation of the
write(T) method must not modify the value passed to it.
class sb extends uvm_component;
uvm_analysis_imp#(trans, sb) ap;
function new(string name = "sb", uvm_component parent = null);
super.new(name, parent);
ap = new("ap", this);
endfunction
function void write(trans t);
...
endfunction
endclass
Summary
uvm_analysis_imp
Receives all transactions broadcasted by a uvm_analysis_port.
CLass HIERaRchY
uvm_port_base#(uvm_tlm_if_base#(T,T))
uvm_analysis_imp
CLass DEcLaRaTION
class uvm_analysis_imp #(
type T = int,
type IMP = int
) extends uvm_port_base #(uvm_tlm_if_base #(T,T))
uvm_analysis_export
UVM 1.2 Class Reference
329
Exports a lower-level uvm_analysis_imp to its parent.
Summary
uvm_analysis_export
Exports a lower-level uvm_analysis_imp to its parent.
CLass HIERaRchY
uvm_port_base#(uvm_tlm_if_base#(T,T))
uvm_analysis_export
CLass DEcLaRaTION
class uvm_analysis_export #(
type T = int
) extends uvm_port_base #(uvm_tlm_if_base #(T,T))
METhOds
new
Instantiate the export.
METhOds
new
function new (
string name, uvm_component parent = null
)
Instantiate the export.
UVM 1.2 Class Reference
330
17. PREDEFINED COMpONENT CLASSES
Components form the foundation of the UVM. They encapsulate behavior of drivers,
scoreboards, and other objects in a testbench. The UVM library provides a set of
predefined component types, all derived directly or indirectly from uvm_component.
Predefined Components
Summary
Predefined Component Classes
Components form the foundation of the UVM.
UVM 1.2 Class Reference
331
17.1 uvm_component
The uvm_component class is the root base class for UVM components. In addition to the
features inherited from uvm_object and uvm_report_object, uvm_component provides
the following interfaces:
Hierarchy
provides methods for searching and traversing the
component hierarchy.
Phasing
defines a phased test flow that all components follow,
with a group of standard phase methods and an API
for custom phases and multiple independent phasing
domains to mirror DUT behavior e.g. power
Reporting
provides a convenience interface to the
uvm_report_handler. All messages, warnings, and
errors are processed through this interface.
Transaction recording
provides methods for recording the transactions
produced or consumed by the component to a
transaction database (vendor specific).
Factory
provides a convenience interface to the uvm_factory. The factory is used to create new components and
other objects based on type-wide and instance-specific
configuration.
The uvm_component is automatically seeded during construction using UVM seeding, if
enabled. All other objects must be manually reseeded, if appropriate. See
uvm_object::reseed for more information.
Summary
uvm_component
The uvm_component class is the root base class for UVM components.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
CLAss DEcLARATION
virtual class uvm_component extends uvm_report_object
new
Creates a new component with the given leaf
instance name and handle to its parent.
HIERARchY INTERFAcE
These methods provide user access to
information about the component hierarchy,
i.e., topology.
Returns a handle to this component’s
parent, or null if it has no parent.
Returns the full hierarchical name of this
object.
This function populates the end of the
children array with the list of this
component’s children.
get_parent
get_full_name
get_children
get_child
UVM 1.2 Class Reference
332
get_next_child
get_first_child
get_num_children
has_child
lookup
get_depth
PhAsING INTERFAcE
build_phase
connect_phase
end_of_elaboration_phase
start_of_simulation_phase
run_phase
pre_reset_phase
reset_phase
post_reset_phase
pre_configure_phase
configure_phase
post_configure_phase
pre_main_phase
main_phase
post_main_phase
pre_shutdown_phase
shutdown_phase
post_shutdown_phase
extract_phase
check_phase
report_phase
final_phase
phase_started
phase_ready_to_end
phase_ended
UVM 1.2 Class Reference
These methods are used to iterate through
this component’s children, if any.
Returns the number of this component’s
children.
Returns 1 if this component has a child
with the given name, 0 otherwise.
Looks for a component with the given
hierarchical name relative to this
component.
Returns the component’s depth from the
root level.
These methods implement an interface which
allows all components to step through a
standard schedule of phases, or a
customized schedule, and also an API to
allow independent phase domains which can
jump like state machines to reflect behavior
e.g.
The uvm_build_phase phase
implementation method.
The uvm_connect_phase phase
implementation method.
The uvm_end_of_elaboration_phase phase
implementation method.
The uvm_start_of_simulation_phase phase
implementation method.
The uvm_run_phase phase implementation
method.
The uvm_pre_reset_phase phase
implementation method.
The uvm_reset_phase phase
implementation method.
The uvm_post_reset_phase phase
implementation method.
The uvm_pre_configure_phase phase
implementation method.
The uvm_configure_phase phase
implementation method.
The uvm_post_configure_phase phase
implementation method.
The uvm_pre_main_phase phase
implementation method.
The uvm_main_phase phase
implementation method.
The uvm_post_main_phase phase
implementation method.
The uvm_pre_shutdown_phase phase
implementation method.
The uvm_shutdown_phase phase
implementation method.
The uvm_post_shutdown_phase phase
implementation method.
The uvm_extract_phase phase
implementation method.
The uvm_check_phase phase
implementation method.
The uvm_report_phase phase
implementation method.
The uvm_final_phase phase
implementation method.
Invoked at the start of each phase.
Invoked when all objections to ending the
given phase and all sibling phases have
been dropped, thus indicating that phase is
ready to begin a clean exit.
Invoked at the end of each phase.
333
set_domain
get_domain
define_domain
set_phase_imp
suspend
resume
resolve_bindings
CONFIGURATION INTERFAcE
check_config_usage
apply_config_settings
print_config_settings
print_config
print_config_with_audit
print_config_matches
OBJEcTION INTERFAcE
raised
dropped
all_dropped
FAcTORY INTERFAcE
create_component
create_object
UVM 1.2 Class Reference
Apply a phase domain to this component
and, if hier is set, recursively to all its
children.
Return handle to the phase domain set on
this component
Builds custom phase schedules into the
provided domain handle.
Override the default implementation for a
phase on this component (tree) with a
custom one, which must be created as a
singleton object extending the default one
and implementing required behavior in
exec and traverse methods
Suspend this component.
Resume this component.
Processes all port, export, and imp
connections.
Components can be designed to be userconfigurable in terms of its topology (the
type and number of children it has), mode of
operation, and run-time parameters (knobs).
Check all configuration settings in a
components configuration table to
determine if the setting has been used,
overridden or not used.
Searches for all config settings matching
this component’s instance path.
Called without arguments,
print_config_settings prints all configuration
information for this component, as set by
previous calls to
uvm_config_db#(T)::set().
Print_config_settings prints all configuration
information for this component, as set by
previous calls to
uvm_config_db#(T)::set() and exports
to the resources pool.
Operates the same as print_config except
that the audit bit is forced to 1.
Setting this static variable causes
uvm_config_db#(T)::get() to print info
about matching configuration settings as
they are being applied.
These methods provide object level hooks
into the uvm_objection mechanism.
The raised callback is called when this or a
descendant of this component instance
raises the specified objection.
The dropped callback is called when this or
a descendant of this component instance
drops the specified objection.
The all_droppped callback is called when all
objections have been dropped by this
component and all its descendants.
The factory interface provides convenient
access to a portion of UVM’s uvm_factory
interface.
A convenience function for
uvm_factory::create_component_by_name,
this method calls upon the factory to create
a new child component whose type
corresponds to the preregistered type
name, requested_type_name, and instance
name, name.
A convenience function for
uvm_factory::create_object_by_name, this
334
set_type_override_by_type
set_inst_override_by_type
set_type_override
set_inst_override
print_override_info
HIERARchIcAL REpORTING INTERFAcE
set_report_id_verbosity_hier
set_report_severity_id_verbosity_hier
set_report_severity_action_hier
set_report_id_action_hier
set_report_severity_id_action_hier
set_report_default_file_hier
set_report_severity_file_hier
set_report_id_file_hier
set_report_severity_id_file_hier
set_report_verbosity_level_hier
pre_abort
REcORdING INTERFAcE
accept_tr
do_accept_tr
begin_tr
UVM 1.2 Class Reference
method calls upon the factory to create a
new object whose type corresponds to the
preregistered type name,
requested_type_name, and instance name,
name.
A convenience function for
uvm_factory::set_type_override_by_type,
this method registers a factory override for
components and objects created at this
level of hierarchy or below.
A convenience function for
uvm_factory::set_inst_override_by_type,
this method registers a factory override for
components and objects created at this
level of hierarchy or below.
A convenience function for
uvm_factory::set_type_override_by_name,
this method configures the factory to create
an object of type override_type_name
whenever the factory is asked to produce a
type represented by original_type_name.
A convenience function for
uvm_factory::set_inst_override_by_name,
this method registers a factory override for
components created at this level of
hierarchy or below.
This factory debug method performs the
same lookup process as create_object and
create_component, but instead of creating
an object, it prints information about what
type of object would be created given the
provided arguments.
This interface provides versions of the
set_report_* methods in the
uvm_report_object base class that are
applied recursively to this component and all
its children.
These methods recursively associate the
specified verbosity with reports of the given
severity, id, or severity-id pair.
These methods recursively associate the
specified action with reports of the given
severity, id, or severity-id pair.
These methods recursively associate the
specified FILE descriptor with reports of the
given severity, id, or severity-id pair.
This method recursively sets the maximum
verbosity level for reports for this
component and all those below it.
This callback is executed when the
message system is executing a UVM_EXIT
action.
These methods comprise the componentbased transaction recording interface.
This function marks the acceptance of a
transaction, tr, by this component.
The accept_tr method calls this function to
accommodate any user-defined postaccept action.
This function marks the start of a
transaction, tr, by this component.
335
begin_child_tr
do_begin_tr
end_tr
do_end_tr
record_error_tr
record_event_tr
get_tr_stream
free_tr_stream
print_enabled
tr_database
This function marks the start of a child
transaction, tr, by this component.
The begin_tr and begin_child_tr methods
call this function to accommodate any
user-defined post-begin action.
This function marks the end of a
transaction, tr, by this component.
The end_tr method calls this function to
accommodate any user-defined post-end
action.
This function marks an error transaction by
a component.
This function marks an event transaction by
a component.
Returns a tr stream with this component’s
full name as a scope.
Frees the internal references associated
with stream.
This bit determines if this component
should automatically be printed as a child
of its parent object.
Specifies the uvm_tr_database object to
use for begin_tr and other methods in the
Recording Interface.
new
function new (
string name,
uvm_component parent
)
Creates a new component with the given leaf instance name and handle to its parent. If
the component is a top-level component (i.e. it is created in a static module or
interface), parent should be null.
The component will be inserted as a child of the parent object, if any. If parent already
has a child by the given name, an error is produced.
If parent is null, then the component will become a child of the implicit top-level
component, uvm_top.
All classes derived from uvm_component must call super.new(name,parent).
HIERARchY INTERFAcE
These methods provide user access to information about the component hierarchy, i.e.,
topology.
get_parent
virtual function uvm_component get_parent ()
Returns a handle to this component’s parent, or null if it has no parent.
get_full_name
UVM 1.2 Class Reference
336
virtual function string get_full_name ()
Returns the full hierarchical name of this object. The default implementation
concatenates the hierarchical name of the parent, if any, with the leaf name of this
object, as given by uvm_object::get_name.
get_children
function void get_children(
ref uvm_component children[$]
)
This function populates the end of the children array with the list of this component’s
children.
uvm_component array[$];
my_comp.get_children(array);
foreach(array[i])
do_something(array[i]);
get_child
function uvm_component get_child (
string name
)
get_next_child
function int get_next_child (
ref string name
)
get_first_child
function int get_first_child (
ref string name
)
These methods are used to iterate through this component’s children, if any. For
example, given a component with an object handle, comp, the following code calls
uvm_object::print for each child:
string name;
uvm_component child;
if (comp.get_first_child(name))
do begin
child = comp.get_child(name);
child.print();
end while (comp.get_next_child(name));
get_num_children
UVM 1.2 Class Reference
337
function int get_num_children ()
Returns the number of this component’s children.
has_child
function int has_child (
string name
)
Returns 1 if this component has a child with the given name, 0 otherwise.
lookup
function uvm_component lookup (
string name
)
Looks for a component with the given hierarchical name relative to this component. If
the given name is preceded with a ‘.’ (dot), then the search begins relative to the top
level (absolute lookup). The handle of the matching component is returned, else null. The name must not contain wildcards.
get_depth
function int unsigned get_depth()
Returns the component’s depth from the root level. uvm_top has a depth of 0. The test
and any other top level components have a depth of 1, and so on.
PhAsING INTERFAcE
These methods implement an interface which allows all components to step through a
standard schedule of phases, or a customized schedule, and also an API to allow
independent phase domains which can jump like state machines to reflect behavior e.g.
power domains on the DUT in different portions of the testbench. The phase tasks and
functions are the phase name with the _phase suffix. For example, the build phase
function is build_phase.
All processes associated with a task-based phase are killed when the phase ends. See
uvm_task_phase for more details.
build_phase
virtual function void build_phase(
uvm_phase phase
)
The uvm_build_phase phase implementation method.
Any override should call super.build_phase(phase) to execute the automatic configuration
of fields registered in the component by calling apply_config_settings. To turn off
automatic configuration for a component, do not call super.build_phase(phase).
UVM 1.2 Class Reference
338
This method should never be called directly.
connect_phase
virtual function void connect_phase(
uvm_phase phase
)
The uvm_connect_phase phase implementation method.
This method should never be called directly.
end_of_elaboration_phase
virtual function void end_of_elaboration_phase(
uvm_phase phase
)
The uvm_end_of_elaboration_phase phase implementation method.
This method should never be called directly.
start_of_simulation_phase
virtual function void start_of_simulation_phase(
uvm_phase phase
)
The uvm_start_of_simulation_phase phase implementation method.
This method should never be called directly.
run_phase
virtual task run_phase(
uvm_phase phase
)
The uvm_run_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. Thus
the phase will automatically end once all objections are dropped using
phase.drop_objection().
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
The run_phase task should never be called directly.
pre_reset_phase
virtual task pre_reset_phase(
uvm_phase phase
)
UVM 1.2 Class Reference
339
The uvm_pre_reset_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
reset_phase
virtual task reset_phase(
uvm_phase phase
)
The uvm_reset_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
post_reset_phase
virtual task post_reset_phase(
uvm_phase phase
)
The uvm_post_reset_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
pre_configure_phase
virtual task pre_configure_phase(
uvm_phase phase
)
The uvm_pre_configure_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
UVM 1.2 Class Reference
340
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
configure_phase
virtual task configure_phase(
uvm_phase phase
)
The uvm_configure_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
post_configure_phase
virtual task post_configure_phase(
uvm_phase phase
)
The uvm_post_configure_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
pre_main_phase
virtual task pre_main_phase(
uvm_phase phase
)
The uvm_pre_main_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
UVM 1.2 Class Reference
341
killed once the phase ends.
This method should not be called directly.
main_phase
virtual task main_phase(
uvm_phase phase
)
The uvm_main_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
post_main_phase
virtual task post_main_phase(
uvm_phase phase
)
The uvm_post_main_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
pre_shutdown_phase
virtual task pre_shutdown_phase(
uvm_phase phase
)
The uvm_pre_shutdown_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
UVM 1.2 Class Reference
342
shutdown_phase
virtual task shutdown_phase(
uvm_phase phase
)
The uvm_shutdown_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
post_shutdown_phase
virtual task post_shutdown_phase(
uvm_phase phase
)
The uvm_post_shutdown_phase phase implementation method.
This task returning or not does not indicate the end or persistence of this phase. It is
necessary to raise an objection using phase.raise_objection() to cause the phase to
persist. Once all components have dropped their respective objection using
phase.drop_objection(), or if no components raises an objection, the phase is ended.
Any processes forked by this task continue to run after the task returns, but they will be
killed once the phase ends.
This method should not be called directly.
extract_phase
virtual function void extract_phase(
uvm_phase phase
)
The uvm_extract_phase phase implementation method.
This method should never be called directly.
check_phase
virtual function void check_phase(
uvm_phase phase
)
The uvm_check_phase phase implementation method.
This method should never be called directly.
UVM 1.2 Class Reference
343
report_phase
virtual function void report_phase(
uvm_phase phase
)
The uvm_report_phase phase implementation method.
This method should never be called directly.
final_phase
virtual function void final_phase(
uvm_phase phase
)
The uvm_final_phase phase implementation method.
This method should never be called directly.
phase_started
virtual function void phase_started (
uvm_phase phase
)
Invoked at the start of each phase. The phase argument specifies the phase being
started. Any threads spawned in this callback are not affected when the phase ends.
phase_ready_to_end
virtual function void phase_ready_to_end (
uvm_phase phase
)
Invoked when all objections to ending the given phase and all sibling phases have been
dropped, thus indicating that phase is ready to begin a clean exit. Sibling phases are
any phases that have a common successor phase in the schedule plus any phases that
sync’d to the current phase. Components needing to consume delta cycles or advance
time to perform a clean exit from the phase may raise the phase’s objection.
phase.raise_objection(this,"Reason");
It is the responsibility of this component to drop the objection once it is ready for this
phase to end (and processes killed). If no objection to the given phase or sibling phases
are raised, then phase_ended() is called after a delta cycle. If any objection is raised,
then when all objections to ending the given phase and siblings are dropped, another
iteration of phase_ready_to_end is called. To prevent endless iterations due to coding
error, after 20 iterations, phase_ended() is called regardless of whether previous iteration
had any objections raised.
phase_ended
UVM 1.2 Class Reference
344
virtual function void phase_ended (
uvm_phase phase
)
Invoked at the end of each phase. The phase argument specifies the phase that is
ending. Any threads spawned in this callback are not affected when the phase ends.
set_domain
function void set_domain(
uvm_domain domain, int hier
= 1
)
Apply a phase domain to this component and, if hier is set, recursively to all its children.
Calls the virtual define_domain method, which derived components can override to
augment or replace the domain definition of its base class.
get_domain
function uvm_domain get_domain()
Return handle to the phase domain set on this component
define_domain
virtual protected function void define_domain(
uvm_domain domain
)
Builds custom phase schedules into the provided domain handle.
This method is called by set_domain, which integrators use to specify this component
belongs in a domain apart from the default ‘uvm’ domain.
Custom component base classes requiring a custom phasing schedule can augment or
replace the domain definition they inherit by overriding their defined_domain. To
augment, overrides would call super.define_domain(). To replace, overrides would not
call super.define_domain().
The default implementation adds a copy of the uvm phasing schedule to the given
domain, if one doesn’t already exist, and only if the domain is currently empty.
Calling set_domain with the default uvm domain (i.e. uvm_domain::get_uvm_domain )
on a component with no define_domain override effectively reverts the that component
to using the default uvm domain. This may be useful if a branch of the testbench
hierarchy defines a custom domain, but some child sub-branch should remain in the
default uvm domain, call set_domain with a new domain instance handle with hier set. Then, in the sub-branch, call set_domain with the default uvm domain handle, obtained
via uvm_domain::get_uvm_domain.
Alternatively, the integrator may define the graph in a new domain externally, then call
set_domain to apply it to a component.
set_phase_imp
UVM 1.2 Class Reference
345
function void set_phase_imp(
uvm_phase phase, uvm_phase imp, int hier = 1
)
Override the default implementation for a phase on this component (tree) with a custom
one, which must be created as a singleton object extending the default one and
implementing required behavior in exec and traverse methods
The hier specifies whether to apply the custom functor to the whole tree or just this
component.
suspend
virtual task suspend ()
Suspend this component.
This method must be implemented by the user to suspend the component according to
the protocol and functionality it implements. A suspended component can be
subsequently resumed using resume().
resume
virtual task resume ()
Resume this component.
This method must be implemented by the user to resume a component that was
previously suspended using suspend(). Some component may start in the suspended
state and may need to be explicitly resumed.
resolve_bindings
virtual function void resolve_bindings ()
Processes all port, export, and imp connections. Checks whether each port’s min and
max connection requirements are met.
It is called just before the end_of_elaboration phase.
Users should not call directly.
CONFIGURATION INTERFAcE
Components can be designed to be user-configurable in terms of its topology (the type
and number of children it has), mode of operation, and run-time parameters (knobs). The configuration interface accommodates this common need, allowing component
composition and state to be modified without having to derive new classes or new class
hierarchies for every configuration scenario.
check_config_usage
UVM 1.2 Class Reference
346
function void check_config_usage (
bit recurse = 1
)
Check all configuration settings in a components configuration table to determine if the
setting has been used, overridden or not used. When recurse is 1 (default),
configuration for this and all child components are recursively checked. This function is
automatically called in the check phase, but can be manually called at any time.
To get all configuration information prior to the run phase, do something like this in your
top object:
function void start_of_simulation_phase(uvm_phase phase);
check_config_usage();
endfunction
apply_config_settings
virtual function void apply_config_settings (
bit verbose = 0
)
Searches for all config settings matching this component’s instance path. For each
match, the appropriate set_*_local method is called using the matching config setting’s
field_name and value. Provided the set_*_local method is implemented, the component
property associated with the field_name is assigned the given value.
This function is called by uvm_component::build_phase.
The apply_config_settings method determines all the configuration settings targeting this
component and calls the appropriate set_*_local method to set each one. To work, you
must override one or more set_*_local methods to accommodate setting of your
component’s specific properties. Any properties registered with the optional
`uvm_*_field macros do not require special handling by the set_*_local methods; the
macros provide the set_*_local functionality for you.
If you do not want apply_config_settings to be called for a component, then the
build_phase() method should be overloaded and you should not call
super.build_phase(phase). Likewise, apply_config_settings can be overloaded to
customize automated configuration.
When the verbose bit is set, all overrides are printed as they are applied. If the
component’s print_config_matches property is set, then apply_config_settings is
automatically called with verbose = 1.
print_config_settings
function void print_config_settings (
string field = "",
uvm_component comp
= null,
bit recurse = 0
)
Called without arguments, print_config_settings prints all configuration information for
this component, as set by previous calls to uvm_config_db#(T)::set(). The settings
are printing in the order of their precedence.
UVM 1.2 Class Reference
347
If field is specified and non-empty, then only configuration settings matching that field, if
any, are printed. The field may not contain wildcards.
If comp is specified and non-null, then the configuration for that component is printed.
If recurse is set, then configuration information for all comp’s children and below are
printed as well.
This function has been deprecated. Use print_config instead.
print_config
function void print_config(
bit recurse = 0,
bit audit = 0
)
Print_config_settings prints all configuration information for this component, as set by
previous calls to uvm_config_db#(T)::set() and exports to the resources pool. The
settings are printing in the order of their precedence.
If recurse is set, then configuration information for all children and below are printed as
well.
if audit is set then the audit trail for each resource is printed along with the resource
name and value
print_config_with_audit
function void print_config_with_audit(
bit recurse = 0
)
Operates the same as print_config except that the audit bit is forced to 1. This interface
makes user code a bit more readable as it avoids multiple arbitrary bit settings in the
argument list.
If recurse is set, then configuration information for all children and below are printed as
well.
print_config_matches
static bit print_config_matches
Setting this static variable causes uvm_config_db#(T)::get() to print info about matching
configuration settings as they are being applied.
OBJEcTION INTERFAcE
These methods provide object level hooks into the uvm_objection mechanism.
raised
virtual function void raised (
UVM 1.2 Class Reference
348
uvm_objection objection,
uvm_object source_obj,
string description,
int count
)
The raised callback is called when this or a descendant of this component instance raises
the specified objection. The source_obj is the object that originally raised the objection. The description is optionally provided by the source_obj to give a reason for raising the
objection. The count indicates the number of objections raised by the source_obj.
dropped
virtual function void dropped (
uvm_objection objection,
uvm_object source_obj,
string description,
int count
)
The dropped callback is called when this or a descendant of this component instance
drops the specified objection. The source_obj is the object that originally dropped the
objection. The description is optionally provided by the source_obj to give a reason for
dropping the objection. The count indicates the number of objections dropped by the
source_obj.
all_dropped
virtual task all_dropped (
uvm_objection objection,
uvm_object source_obj,
string description,
int count
)
The all_droppped callback is called when all objections have been dropped by this
component and all its descendants. The source_obj is the object that dropped the last
objection. The description is optionally provided by the source_obj to give a reason for
raising the objection. The count indicates the number of objections dropped by the
source_obj.
FAcTORY INTERFAcE
The factory interface provides convenient access to a portion of UVM’s uvm_factory
interface. For creating new objects and components, the preferred method of accessing
the factory is via the object or component wrapper (see uvm_component_registry
#(T,Tname) and uvm_object_registry #(T,Tname)). The wrapper also provides functions
for setting type and instance overrides.
create_component
function uvm_component create_component (
string requested_type_name,
string name
)
A convenience function for uvm_factory::create_component_by_name, this method calls
UVM 1.2 Class Reference
349
upon the factory to create a new child component whose type corresponds to the
preregistered type name, requested_type_name, and instance name, name. This method
is equivalent to:
factory.create_component_by_name(requested_type_name,
get_full_name(), name, this);
If the factory determines that a type or instance override exists, the type of the
component created may be different than the requested type. See set_type_override
and set_inst_override. See also uvm_factory for details on factory operation.
create_object
function uvm_object create_object (
string requested_type_name, string name
= ""
)
A convenience function for uvm_factory::create_object_by_name, this method calls upon
the factory to create a new object whose type corresponds to the preregistered type
name, requested_type_name, and instance name, name. This method is equivalent to:
factory.create_object_by_name(requested_type_name,
get_full_name(), name);
If the factory determines that a type or instance override exists, the type of the object
created may be different than the requested type. See uvm_factory for details on
factory operation.
set_type_override_by_type
static function void set_type_override_by_type (
uvm_object_wrapper original_type, uvm_object_wrapper override_type, bit replace
= 1
)
A convenience function for uvm_factory::set_type_override_by_type, this method
registers a factory override for components and objects created at this level of hierarchy
or below. This method is equivalent to:
factory.set_type_override_by_type(original_type, override_type,replace);
The relative_inst_path is relative to this component and may include wildcards. The
original_type represents the type that is being overridden. In subsequent calls to
uvm_factory::create_object_by_type or uvm_factory::create_component_by_type, if the
requested_type matches the original_type and the instance paths match, the factory will
produce the override_type.
The original and override type arguments are lightweight proxies to the types they
represent. See set_inst_override_by_type for information on usage.
UVM 1.2 Class Reference
350
set_inst_override_by_type
function void set_inst_override_by_type(
string relative_inst_path,
uvm_object_wrapper original_type,
uvm_object_wrapper override_type
)
A convenience function for uvm_factory::set_inst_override_by_type, this method registers
a factory override for components and objects created at this level of hierarchy or
below. In typical usage, this method is equivalent to:
factory.set_inst_override_by_type( original_type,
override_type,
{get_full_name(),".",
relative_inst_path});
The relative_inst_path is relative to this component and may include wildcards. The
original_type represents the type that is being overridden. In subsequent calls to
uvm_factory::create_object_by_type or uvm_factory::create_component_by_type, if the
requested_type matches the original_type and the instance paths match, the factory will
produce the override_type.
The original and override types are lightweight proxies to the types they represent. They
can be obtained by calling type::get_type(), if implemented by type, or by directly calling
type::type_id::get(), where type is the user type and type_id is the name of the typedef
to uvm_object_registry #(T,Tname) or uvm_component_registry #(T,Tname).
If you are employing the `uvm_*_utils macros, the typedef and the get_type method
will be implemented for you. For details on the utils macros refer to Utility and Field
Macros for Components and Objects.
The following example shows `uvm_*_utils usage
class comp extends uvm_component;
`uvm_component_utils(comp)
...
endclass
class mycomp extends uvm_component;
`uvm_component_utils(mycomp)
...
endclass
class block extends uvm_component;
`uvm_component_utils(block)
comp c_inst;
virtual function void build_phase(uvm_phase phase);
set_inst_override_by_type("c_inst",comp::get_type(),
mycomp::get_type());
endfunction
...
endclass
set_type_override
static function void set_type_override(
string original_type_name, string override_type_name, replace
= 1
bit )
UVM 1.2 Class Reference
351
A convenience function for uvm_factory::set_type_override_by_name, this method
configures the factory to create an object of type override_type_name whenever the
factory is asked to produce a type represented by original_type_name. This method is
equivalent to:
factory.set_type_override_by_name(original_type_name,
override_type_name, replace);
The original_type_name typically refers to a preregistered type in the factory. It may,
however, be any arbitrary string. Subsequent calls to create_component or
create_object with the same string and matching instance path will produce the type
represented by override_type_name. The override_type_name must refer to a
preregistered type in the factory.
set_inst_override
function void set_inst_override(
string relative_inst_path,
string original_type_name,
string override_type_name
)
A convenience function for uvm_factory::set_inst_override_by_name, this method
registers a factory override for components created at this level of hierarchy or below. In
typical usage, this method is equivalent to:
factory.set_inst_override_by_name(original_type_name,
override_type_name,
{get_full_name(),".",
relative_inst_path}
);
The relative_inst_path is relative to this component and may include wildcards. The
original_type_name typically refers to a preregistered type in the factory. It may,
however, be any arbitrary string. Subsequent calls to create_component or
create_object with the same string and matching instance path will produce the type
represented by override_type_name. The override_type_name must refer to a
preregistered type in the factory.
print_override_info
function void print_override_info(
string requested_type_name, = ""
string name
)
This factory debug method performs the same lookup process as create_object and
create_component, but instead of creating an object, it prints information about what
type of object would be created given the provided arguments.
HIERARchIcAL REpORTING INTERFAcE
This interface provides versions of the set_report_* methods in the uvm_report_object
UVM 1.2 Class Reference
352
base class that are applied recursively to this component and all its children.
When a report is issued and its associated action has the LOG bit set, the report will be
sent to its associated FILE descriptor.
set_report_id_verbosity_hier
function void set_report_id_verbosity_hier (
string id,
int verbosity
)
set_report_severity_id_verbosity_hier
function void set_report_severity_id_verbosity_hier(
uvm_severity severity,
string id,
int verbosity
)
These methods recursively associate the specified verbosity with reports of the given
severity, id, or severity-id pair. A verbosity associated with a particular severity-id pair
takes precedence over a verbosity associated with id, which takes precedence over a
verbosity associated with a severity.
For a list of severities and their default verbosities, refer to uvm_report_handler.
set_report_severity_action_hier
function void set_report_severity_action_hier (
uvm_severity severity,
uvm_action action
)
set_report_id_action_hier
function void set_report_id_action_hier (
string id,
uvm_action action
)
set_report_severity_id_action_hier
function void set_report_severity_id_action_hier(
uvm_severity severity,
string id,
uvm_action action
)
These methods recursively associate the specified action with reports of the given
severity, id, or severity-id pair. An action associated with a particular severity-id pair
takes precedence over an action associated with id, which takes precedence over an
action associated with a severity.
For a list of severities and their default actions, refer to uvm_report_handler.
UVM 1.2 Class Reference
353
set_report_default_file_hier
function void set_report_default_file_hier (
UVM_FILE file
)
set_report_severity_file_hier
function void set_report_severity_file_hier (
uvm_severity severity,
UVM_FILE file
)
set_report_id_file_hier
function void set_report_id_file_hier (
string id,
UVM_FILE file
)
set_report_severity_id_file_hier
function void set_report_severity_id_file_hier(
uvm_severity severity,
string id,
UVM_FILE file
)
These methods recursively associate the specified FILE descriptor with reports of the
given severity, id, or severity-id pair. A FILE associated with a particular severity-id pair
takes precedence over a FILE associated with id, which take precedence over an a FILE
associated with a severity, which takes precedence over the default FILE descriptor.
For a list of severities and other information related to the report mechanism, refer to
uvm_report_handler.
set_report_verbosity_level_hier
function void set_report_verbosity_level_hier (
int verbosity
)
This method recursively sets the maximum verbosity level for reports for this component
and all those below it. Any report from this component subtree whose verbosity exceeds
this maximum will be ignored.
See uvm_report_handler for a list of predefined message verbosity levels and their
meaning.
pre_abort
virtual function void pre_abort
This callback is executed when the message system is executing a UVM_EXIT action. UVM 1.2 Class Reference
354
The exit action causes an immediate termination of the simulation, but the pre_abort
callback hook gives components an opportunity to provide additional information to the
user before the termination happens. For example, a test may want to executed the
report function of a particular component even when an error condition has happened to
force a premature termination you would write a function like:
function void mycomponent::pre_abort();
report();
endfunction
The pre_abort() callback hooks are called in a bottom-up fashion.
REcORdING INTERFAcE
These methods comprise the component-based transaction recording interface. The
methods can be used to record the transactions that this component “sees”, i.e. produces
or consumes.
The API and implementation are subject to change once a vendor-independent use-model
is determined.
accept_tr
function void accept_tr (
uvm_transaction tr,
accept_time = 0
time )
This function marks the acceptance of a transaction, tr, by this component. Specifically,
it performs the following actions:
Calls the tr’s uvm_transaction::accept_tr method, passing to it the accept_time
argument.
Calls this component’s do_accept_tr method to allow for any post-begin action in
derived classes.
Triggers the component’s internal accept_tr event. Any processes waiting on this
event will resume in the next delta cycle.
do_accept_tr
virtual protected function void do_accept_tr (
uvm_transaction tr
)
The accept_tr method calls this function to accommodate any user-defined post-accept
action. Implementations should call super.do_accept_tr to ensure correct operation.
begin_tr
function integer begin_tr (
uvm_transaction tr,
stream_name
string string label
string desc
UVM 1.2 Class Reference
= "main",
= "",
= "",
355
time integer )
begin_time
= 0,
parent_handle = 0
This function marks the start of a transaction, tr, by this component. Specifically, it
performs the following actions:
Calls tr’s uvm_transaction::begin_tr method, passing to it the begin_time
argument. The begin_time should be greater than or equal to the accept time. By
default, when begin_time = 0, the current simulation time is used.
If recording is enabled (recording_detail != UVM_OFF), then a new database-transaction
is started on the component’s transaction stream given by the stream argument. No
transaction properties are recorded at this time.
Calls the component’s do_begin_tr method to allow for any post-begin action in
derived classes.
Triggers the component’s internal begin_tr event. Any processes waiting on this
event will resume in the next delta cycle.
A handle to the transaction is returned. The meaning of this handle, as well as the
interpretation of the arguments stream_name, label, and desc are vendor specific.
begin_child_tr
function integer begin_child_tr (
uvm_transaction tr,
parent_handle = 0,
integer string stream_name = "main",
string label
= "",
string desc
= "",
time begin_time
= 0
)
This function marks the start of a child transaction, tr, by this component. Its operation
is identical to that of begin_tr, except that an association is made between this
transaction and the provided parent transaction. This association is vendor-specific.
do_begin_tr
virtual protected function void do_begin_tr (
uvm_transaction tr,
string stream_name,
integer tr_handle
)
The begin_tr and begin_child_tr methods call this function to accommodate any userdefined post-begin action. Implementations should call super.do_begin_tr to ensure
correct operation.
end_tr
function void end_tr (
uvm_transaction tr,
end_time
= 0,
time bit free_handle = 1
)
This function marks the end of a transaction, tr, by this component. Specifically, it
performs the following actions:
UVM 1.2 Class Reference
356
Calls tr’s uvm_transaction::end_tr method, passing to it the end_time argument. The end_time must at least be greater than the begin time. By default, when
end_time = 0, the current simulation time is used.
The transaction’s properties are recorded to the database-transaction on which it was
started, and then the transaction is ended. Only those properties handled by the
transaction’s do_record method (and optional `uvm_*_field macros) are recorded.
Calls the component’s do_end_tr method to accommodate any post-end action in
derived classes.
Triggers the component’s internal end_tr event. Any processes waiting on this
event will resume in the next delta cycle.
The free_handle bit indicates that this transaction is no longer needed. The
implementation of free_handle is vendor-specific.
do_end_tr
virtual protected function void do_end_tr (
uvm_transaction tr,
integer tr_handle
)
The end_tr method calls this function to accommodate any user-defined post-end action. Implementations should call super.do_end_tr to ensure correct operation.
record_error_tr
function integer record_error_tr (
string stream_name = "main",
uvm_object info
= null,
string label
= "error_tr",
string desc
= "",
time error_time = 0,
bit keep_active = 0
)
This function marks an error transaction by a component. Properties of the given
uvm_object, info, as implemented in its uvm_object::do_record method, are recorded to
the transaction database.
An error_time of 0 indicates to use the current simulation time. The keep_active bit
determines if the handle should remain active. If 0, then a zero-length error transaction
is recorded. A handle to the database-transaction is returned.
Interpretation of this handle, as well as the strings stream_name, label, and desc, are
vendor-specific.
record_event_tr
function integer record_event_tr (
string stream_name = "main",
uvm_object info
= null,
string label
= "event_tr",
string desc
= "",
time event_time = 0,
bit keep_active = 0
)
This function marks an event transaction by a component.
UVM 1.2 Class Reference
357
An event_time of 0 indicates to use the current simulation time.
A handle to the transaction is returned. The keep_active bit determines if the handle
may be used for other vendor-specific purposes.
The strings for stream_name, label, and desc are vendor-specific identifiers for the
transaction.
get_tr_stream
virtual function uvm_tr_stream get_tr_stream(
string name,
string stream_type_name = ""
)
Returns a tr stream with this component’s full name as a scope.
Streams which are retrieved via this method will be stored internally, such that later calls
to get_tr_stream will return the same stream reference.
The stream can be removed from the internal storage via a call to free_tr_stream.
Parameters
name
Name for the stream
stream_type_name
Type name for the stream (Default = “”)
free_tr_stream
virtual function void free_tr_stream(
uvm_tr_stream stream
)
Frees the internal references associated with stream.
The next call to get_tr_stream will result in a newly created uvm_tr_stream. If the
current stream is open (or closed), then it will be freed.
print_enabled
bit print_enabled = 1
This bit determines if this component should automatically be printed as a child of its
parent object.
By default, all children are printed. However, this bit allows a parent component to
disable the printing of specific children.
tr_database
uvm_tr_database tr_database
Specifies the uvm_tr_database object to use for begin_tr and other methods in the
Recording Interface. Default is uvm_coreservice_t::get_default_tr_database.
UVM 1.2 Class Reference
358
17.2 uvm_test
This class is the virtual base class for the user-defined tests.
The uvm_test virtual class should be used as the base class for user-defined tests. Doing so provides the ability to select which test to execute using the UVM_TESTNAME
command line or argument to the uvm_root::run_test task.
For example
prompt> SIM_COMMAND +UVM_TESTNAME=test_bus_retry
The global run_test() task should be specified inside an initial block such as
initial run_test();
Multiple tests, identified by their type name, are compiled in and then selected for
execution from the command line without need for recompilation. Random seed selection
is also available on the command line.
If +UVM_TESTNAME=test_name is specified, then an object of type ‘test_name’ is
created by factory and phasing begins. Here, it is presumed that the test will instantiate
the test environment, or the test environment will have already been instantiated before
the call to run_test().
If the specified test_name cannot be created by the uvm_factory, then a fatal error
occurs. If run_test() is called without UVM_TESTNAME being specified, then all
components constructed before the call to run_test will be cycled through their
simulation phases.
Deriving from uvm_test will allow you to distinguish tests from other component types
that inherit from uvm_component directly. Such tests will automatically inherit features
that may be added to uvm_test in the future.
Summary
uvm_test
This class is the virtual base class for the user-defined tests.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_test
CLAss DEcLARATION
virtual class uvm_test extends uvm_component
UVM 1.2 Class Reference
359
METhOds
new
Creates and initializes an instance of this class using the normal
constructor arguments for uvm_component: name is the name of
the instance, and parent is the handle to the hierarchical parent, if
any.
METhOds
new
function new (
string name,
uvm_component parent
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
UVM 1.2 Class Reference
360
17.3 uvm_env
The base class for hierarchical containers of other components that together comprise a
complete environment. The environment may initially consist of the entire testbench. Later, it can be reused as a sub-environment in even larger system-level environments.
Summary
uvm_env
The base class for hierarchical containers of other components that together
comprise a complete environment.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_env
CLAss DEcLARATION
virtual class uvm_env extends uvm_component
METhOds
new
Creates and initializes an instance of this class using the normal
constructor arguments for uvm_component: name is the name of
the instance, and parent is the handle to the hierarchical parent, if
any.
METhOds
new
function new (
string name = "env",
uvm_component parent = null
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
UVM 1.2 Class Reference
361
17.4 uvm_agent
The uvm_agent virtual class should be used as the base class for the user- defined
agents. Deriving from uvm_agent will allow you to distinguish agents from other
component types also using its inheritance. Such agents will automatically inherit
features that may be added to uvm_agent in the future.
While an agent’s build function, inherited from uvm_component, can be implemented to
define any agent topology, an agent typically contains three subcomponents: a driver,
sequencer, and monitor. If the agent is active, subtypes should contain all three
subcomponents. If the agent is passive, subtypes should contain only the monitor.
Summary
uvm_agent
The uvm_agent virtual class should be used as the base class for the userdefined agents.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_agent
CLAss DEcLARATION
virtual class uvm_agent extends uvm_component
METhOds
new
get_is_active
Creates and initializes an instance of this class using the
normal constructor arguments for uvm_component: name is
the name of the instance, and parent is the handle to the
hierarchical parent, if any.
Returns UVM_ACTIVE is the agent is acting as an active
agent and UVM_PASSIVE if it is acting as a passive agent.
METhOds
new
function new (
string name,
uvm_component parent
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
The int configuration parameter is_active is used to identify whether this agent should be
UVM 1.2 Class Reference
362
acting in active or passive mode. This parameter can be set by doing:
uvm_config_int::set(this, "<relative_path_to_agent>, "is_active",
UVM_ACTIVE);
get_is_active
virtual function uvm_active_passive_enum get_is_active()
Returns UVM_ACTIVE is the agent is acting as an active agent and UVM_PASSIVE if it is
acting as a passive agent. The default implementation is to just return the is_active flag,
but the component developer may override this behavior if a more complex algorithm is
needed to determine the active/passive nature of the agent.
UVM 1.2 Class Reference
363
17.5 uvm_monitor
This class should be used as the base class for user-defined monitors.
Deriving from uvm_monitor allows you to distinguish monitors from generic component
types inheriting from uvm_component. Such monitors will automatically inherit features
that may be added to uvm_monitor in the future.
Summary
uvm_monitor
This class should be used as the base class for user-defined monitors.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_monitor
CLAss DEcLARATION
virtual class uvm_monitor extends uvm_component
METhOds
new
Creates and initializes an instance of this class using the normal
constructor arguments for uvm_component: name is the name of
the instance, and parent is the handle to the hierarchical parent, if
any.
METhOds
new
function new (
string name,
uvm_component parent
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
UVM 1.2 Class Reference
364
17.6 uvm_scoreboard
The uvm_scoreboard virtual class should be used as the base class for user-defined
scoreboards.
Deriving from uvm_scoreboard will allow you to distinguish scoreboards from other
component types inheriting directly from uvm_component. Such scoreboards will
automatically inherit and benefit from features that may be added to uvm_scoreboard in
the future.
Summary
uvm_scoreboard
The uvm_scoreboard virtual class should be used as the base class for userdefined scoreboards.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_scoreboard
CLAss DEcLARATION
virtual class uvm_scoreboard extends uvm_component
METhOds
new
Creates and initializes an instance of this class using the normal
constructor arguments for uvm_component: name is the name of
the instance, and parent is the handle to the hierarchical parent, if
any.
METhOds
new
function new (
string name,
uvm_component parent
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
UVM 1.2 Class Reference
365
17.7 uvm_driver #(REQ,RSP)
The base class for drivers that initiate requests for new transactions via a
uvm_seq_item_pull_port. The ports are typically connected to the exports of an
appropriate sequencer component.
This driver operates in pull mode. Its ports are typically connected to the corresponding
exports in a pull sequencer as follows:
driver.seq_item_port.connect(sequencer.seq_item_export);
driver.rsp_port.connect(sequencer.rsp_export);
The rsp_port needs connecting only if the driver will use it to write responses to the
analysis export in the sequencer.
Summary
uvm_driver #(REQ,RSP)
The base class for drivers that initiate requests for new transactions via a
uvm_seq_item_pull_port.
CLAss HIerArchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_driver#(REQ,RSP)
CLAss DecLArATION
class uvm_driver #(
type REQ = uvm_sequence_item,
type RSP = REQ
) extends uvm_component
POrTs
seq_item_port
rsp_port
MeThOds
new
Derived driver classes should use this port to request items
from the sequencer.
This port provides an alternate way of sending responses
back to the originating sequencer.
Creates and initializes an instance of this class using the
normal constructor arguments for uvm_component: name
is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
POrTs
seq_item_port
UVM 1.2 Class Reference
366
Derived driver classes should use this port to request items from the sequencer. They
may also use it to send responses back.
rsp_port
This port provides an alternate way of sending responses back to the originating
sequencer. Which port to use depends on which export the sequencer provides for
connection.
MeThOds
new
function new (
string name,
uvm_component parent
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
UVM 1.2 Class Reference
367
17.8 uvm_push_driver #(REQ,RSP)
Base class for a driver that passively receives transactions, i.e. does not initiate requests
transactions. Also known as push mode. Its ports are typically connected to the
corresponding ports in a push sequencer as follows:
push_sequencer.req_port.connect(push_driver.req_export);
push_driver.rsp_port.connect(push_sequencer.rsp_export);
The rsp_port needs connecting only if the driver will use it to write responses to the
analysis export in the sequencer.
Summary
uvm_push_driver #(REQ,RSP)
Base class for a driver that passively receives transactions.
CLAss HIerArchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_push_driver#(REQ,RSP)
CLAss DecLArATION
class uvm_push_driver #(
type REQ = uvm_sequence_item,
type RSP = REQ
) extends uvm_component
POrTs
req_export
rsp_port
MeThOds
new
This export provides the blocking put interface whose default
implementation produces an error.
This analysis port is used to send response transactions back
to the originating sequencer.
Creates and initializes an instance of this class using the
normal constructor arguments for uvm_component: name is
the name of the instance, and parent is the handle to the
hierarchical parent, if any.
POrTs
req_export
This export provides the blocking put interface whose default implementation produces
an error. Derived drivers must override put with an appropriate implementation (and not
call super.put). Ports connected to this export will supply the driver with transactions.
UVM 1.2 Class Reference
368
rsp_port
This analysis port is used to send response transactions back to the originating
sequencer.
MeThOds
new
function new (
string name,
uvm_component parent
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
UVM 1.2 Class Reference
369
17.9 uvm_random_stimulus #(T)
A general purpose unidirectional random stimulus class.
The uvm_random_stimulus class generates streams of T transactions. These streams
may be generated by the randomize method of T, or the randomize method of one of its
subclasses. The stream may go indefinitely, until terminated by a call to
stop_stimulus_generation, or we may specify the maximum number of transactions to be
generated.
By using inheritance, we can add directed initialization or tidy up after random stimulus
generation. Simply extend the class and define the run task, calling super.run() when
you want to begin the random stimulus phase of simulation.
While very useful in its own right, this component can also be used as a template for
defining other stimulus generators, or it can be extended to add additional stimulus
generation methods and to simplify test writing.
Summary
uvm_random_stimulus #(T)
A general purpose unidirectional random stimulus class.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_random_stimulus#(T)
CLAss DEcLARAtION
class uvm_random_stimulus #(
type T = uvm_transaction
) extends uvm_component
PORts
blocking_put_port
MEthOds
new
generate_stimulus
stop_stimulus_generation
The blocking_put_port is used to send the
generated stimulus to the rest of the testbench.
Creates a new instance of a specialization of this
class.
Generate up to max_count transactions of type
T.
Stops the generation of stimulus.
PORts
blocking_put_port
The blocking_put_port is used to send the generated stimulus to the rest of the
UVM 1.2 Class Reference
370
testbench.
MEthOds
new
function new(
string name,
uvm_component parent
)
Creates a new instance of a specialization of this class. Also, displays the random state
obtained from a get_randstate call. In subsequent simulations, set_randstate can be
called with the same value to reproduce the same sequence of transactions.
generate_stimulus
virtual task generate_stimulus(
T t
= null,
int max_count = 0
)
Generate up to max_count transactions of type T. If t is not specified, a default instance
of T is allocated and used. If t is specified, that transaction is used when randomizing. It must be a subclass of T.
max_count is the maximum number of transactions to be generated. A value of zero
indicates no maximum - in this case, generate_stimulus will go on indefinitely unless
stopped by some other process
The transactions are cloned before they are sent out over the blocking_put_port
stop_stimulus_generation
virtual function void stop_stimulus_generation
Stops the generation of stimulus. If a subclass of this method has forked additional
processes, those processes will also need to be stopped in an overridden version of this
method
UVM 1.2 Class Reference
371
17.10 uvm_subscriber
This class provides an analysis export for receiving transactions from a connected
analysis export. Making such a connection “subscribes” this component to any
transactions emitted by the connected analysis port.
Subtypes of this class must define the write method to process the incoming
transactions. This class is particularly useful when designing a coverage collector that
attaches to a monitor.
Summary
uvm_subscriber
This class provides an analysis export for receiving transactions from a connected
analysis export.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_subscriber
CLAss DEcLARATION
virtual class uvm_subscriber #(
type T = int
) extends uvm_component
PORTs
analysis_export
METhOds
new
write
This export provides access to the write method, which
derived subscribers must implement.
Creates and initializes an instance of this class using the
normal constructor arguments for uvm_component: name
is the name of the instance, and parent is the handle to
the hierarchical parent, if any.
A pure virtual method that must be defined in each
subclass.
PORTs
analysis_export
This export provides access to the write method, which derived subscribers must
implement.
METhOds
UVM 1.2 Class Reference
372
new
function new (
string name,
uvm_component parent
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
write
pure virtual function void write(
T t
)
A pure virtual method that must be defined in each subclass. Access to this method by
outside components should be done via the analysis_export.
UVM 1.2 Class Reference
373
18. COMPARATORS
A common function of testbenches is to compare streams of transactions for
equivalence. For example, a testbench may compare a stream of transactions from a
DUT with expected results.
The UVM library provides a base class called uvm_in_order_comparator and two derived
classes: uvm_in_order_built_in_comparator for comparing streams of built-in types and
uvm_in_order_class_comparator for comparing streams of class objects.
The uvm_algorithmic_comparator also compares two streams of transactions, but the
transaction streams might be of different type objects. Thus, this comparator will employ
a user-defined transformation function to convert one type to another before performing
a comparison.
Summary
Comparators
A common function of testbenches is to compare streams of transactions for
equivalence.
UVM 1.2 Class Reference
374
18.1 Comparators
The following classes define comparators for objects and built-in types.
Contents
Comparators
The following classes define comparators for
objects and built-in types.
uvm_in_order_comparator
#(T,comp_type,convert,pair_type)
uvm_in_order_built_in_comparator
#(T)
uvm_in_order_class_comparator
#(T)
Compares two streams of data objects of
the type parameter, T.
This class uses the uvm_built_in_*
comparison, converter, and pair classes.
This class uses the uvm_class_*
comparison, converter, and pair classes.
uvm_in_order_comparator
#(T,comp_type,convert,pair_type)
Compares two streams of data objects of the type parameter, T. These transactions may
either be classes or built-in types. To be successfully compared, the two streams of data
must be in the same order. Apart from that, there are no assumptions made about the
relative timing of the two streams of data.
Type parameters
T
Specifies the type of transactions to be compared.
comp_type
A policy class to compare the two transaction streams. It must
provide the static method “function bit comp(T a, T b)” which
returns TRUE if a and b are the same.
convert
A policy class to convert the transactions being compared to a
string. It must provide the static method “function string
convert2string(T a)”.
pair_type
A policy class to allow pairs of transactions to be handled as a
single uvm_object type.
Built in types (such as ints, bits, logic, and structs) can be compared using the default
values for comp_type, convert, and pair_type. For convenience, you can use the
subtype, uvm_in_order_built_in_comparator #(T) for built-in types.
When T is a uvm_object, you can use the convenience subtype
uvm_in_order_class_comparator #(T).
Comparisons are commutative, meaning it does not matter which data stream is
connected to which export, before_export or after_export.
Comparisons are done in order and as soon as a transaction is received from both
streams. Internal fifos are used to buffer incoming transactions on one stream until a
transaction to compare arrives on the other stream.
Summary
uvm_in_order_comparator
#(T,comp_type,convert,pair_type)
Compares two streams of data objects of the type parameter, T.
PORts
before_export
UVM 1.2 Class Reference
The export to which one stream of data is written.
375
after_export
pair_ap
MEtHODs
flush
The export to which the other stream of data is written.
The comparator sends out pairs of transactions across this
analysis port.
This method sets m_matches and m_mismatches back to
zero.
PORts
before_export
The export to which one stream of data is written. The port must be connected to an
analysis port that will provide such data.
after_export
The export to which the other stream of data is written. The port must be connected to
an analysis port that will provide such data.
pair_ap
The comparator sends out pairs of transactions across this analysis port. Both matched
and unmatched pairs are published via a pair_type objects. Any connected analysis
export(s) will receive these transaction pairs.
MEtHODs
flush
virtual function void flush()
This method sets m_matches and m_mismatches back to zero. The
uvm_tlm_fifo::flush takes care of flushing the FIFOs.
uvm_in_order_built_in_comparator #(T)
This class uses the uvm_built_in_* comparison, converter, and pair classes. Use this
class for built-in types (int, bit, string, etc.)
Summary
uvm_in_order_built_in_comparator #(T)
This class uses the uvm_built_in_* comparison, converter, and pair classes.
CLAss HIERARcHY
uvm_in_order_comparator#(T)
uvm_in_order_built_in_comparator#(T)
CLAss DEcLARAtION
UVM 1.2 Class Reference
376
class uvm_in_order_built_in_comparator #(
type T = int
) extends uvm_in_order_comparator #(T)
uvm_in_order_class_comparator #(T)
This class uses the uvm_class_* comparison, converter, and pair classes. Use this class
for comparing user-defined objects of type T, which must provide compare() and
convert2string() method.
Summary
uvm_in_order_class_comparator #(T)
This class uses the uvm_class_* comparison, converter, and pair classes.
CLAss HIERARcHY
uvm_in_order_comparator#(T,uvm_class_comp#(T),uvm_class_converter#(T),uvm_class_pair#(T,T))
uvm_in_order_class_comparator#(T)
CLAss DEcLARAtION
class uvm_in_order_class_comparator #(
type T = int
) extends uvm_in_order_comparator #( T , uvm_class_comp #( T ) , uvm_class_converter #(
T ) , uvm_class_pair #( T, T ) )
UVM 1.2 Class Reference
377
18.2 Algorithmic Comparator
A common function of testbenches is to compare streams of transactions for
equivalence. For example, a testbench may compare a stream of transactions from a
DUT with expected results.
The UVM library provides a base class called uvm_in_order_comparator
#(T,comp_type,convert,pair_type) and two derived classes, which are
uvm_in_order_built_in_comparator #(T) for comparing streams of built-in types and
uvm_in_order_class_comparator #(T) for comparing streams of class objects.
The uvm_algorithmic_comparator also compares two streams of transactions; however,
the transaction streams might be of different type objects. This device will use a userwritten transformation function to convert one type to another before performing a
comparison.
Summary
Algorithmic Comparator
A common function of testbenches is to compare streams of transactions for
equivalence.
uvm_algorithmic_comparator
#(BEFORE,AFTER,TRANSFORMER)
Compares two streams of data objects of different types, BEFORE and AFTER.
The algorithmic comparator is a wrapper around uvm_in_order_class_comparator #(T). Like the in-order comparator, the algorithmic comparator compares two streams of
transactions, the BEFORE stream and the AFTER stream. It is often the case when two
streams of transactions need to be compared that the two streams are in different
forms. That is, the type of the BEFORE transaction stream is different than the type of
the AFTER transaction stream.
The uvm_algorithmic_comparator’s TRANSFORMER type parameter specifies the class
responsible for converting transactions of type BEFORE into those of type AFTER. This
transformer class must provide a transform() method with the following prototype:
function AFTER transform (BEFORE b);
Matches and mismatches are reported in terms of the AFTER transactions. For more
information, see the uvm_in_order_comparator #(T,comp_type,convert,pair_type) class.
Summary
uvm_algorithmic_comparator
#(BEFORE,AFTER,TRANSFORMER)
UVM 1.2 Class Reference
378
Compares two streams of data objects of different types, BEFORE and AFTER.
CLass HIerarchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_algorithmic_comparator#(BEFORE,AFTER,TRANSFORMER)
CLass DecLaratIon
class uvm_algorithmic_comparator #(
type BEFORE
= int,
type AFTER
= int,
type TRANSFORMER = int
) extends uvm_component
Ports
before_export
after_export
Methods
new
The export to which a data stream of type BEFORE is sent via a
connected analysis port.
The export to which a data stream of type AFTER is sent via a
connected analysis port.
Creates an instance of a specialization of this class.
Ports
before_export
The export to which a data stream of type BEFORE is sent via a connected analysis port. Publishers (monitors) can send in an ordered stream of transactions against which the
transformed BEFORE transactions will (be compared.
after_export
The export to which a data stream of type AFTER is sent via a connected analysis port. Publishers (monitors) can send in an ordered stream of transactions to be transformed
and compared to the AFTER transactions.
Methods
new
function new(
string name,
= null,
uvm_component parent
TRANSFORMER transformer = null
)
Creates an instance of a specialization of this class. In addition to the standard
UVM 1.2 Class Reference
379
uvm_component constructor arguments, name and parent, the constructor takes a
handle to a transformer object, which must already be allocated (handles can’t be null)
and must implement the transform() method.
UVM 1.2 Class Reference
380
18.3 uvm_pair classes
This section defines container classes for handling value pairs.
Contents
uvm_pair
classes
This section defines container classes for handling value pairs.
uvm_class_pair
#(T1,T2)
uvm_built_in_pair
#(T1,T2)
Container holding handles to two objects whose types are
specified by the type parameters, T1 and T2.
Container holding two variables of built-in types (int, string,
etc.)
uvm_class_pair #(T1,T2)
Container holding handles to two objects whose types are specified by the type
parameters, T1 and T2.
Summary
uvm_class_pair #(T1,T2)
Container holding handles to two objects whose types are specified by the type
parameters, T1 and T2.
CLAss HIERARchY
uvm_void
uvm_object
uvm_class_pair#(T1,T2)
CLAss DEcLARAtION
class uvm_class_pair #(
type T1 = int,
T2 = T1
) extends uvm_object
VARIABLEs
T1 first
T2 second
The handle to the first object in the pair
The handle to the second object in the pair
MEthOds
new
Creates an instance that holds a handle to two objects.
VARIABLEs
T1 first
UVM 1.2 Class Reference
381
T1 first
The handle to the first object in the pair
T2 second
T2 second
The handle to the second object in the pair
MEthOds
new
function new (
string name = "",
T1 f
= null,
T2 s
= null
)
Creates an instance that holds a handle to two objects. The optional name argument
gives a name to the new pair object.
uvm_built_in_pair #(T1,T2)
Container holding two variables of built-in types (int, string, etc.). The types are
specified by the type parameters, T1 and T2.
Summary
uvm_built_in_pair #(T1,T2)
Container holding two variables of built-in types (int, string, etc.)
CLAss HIERARchY
uvm_void
uvm_object
uvm_built_in_pair#(T1,T2)
CLAss DEcLARAtION
class uvm_built_in_pair #(
type T1 = int,
T2 = T1
) extends uvm_object
VARIABLEs
T1 first
T2 second
The first value in the pair
The second value in the pair
MEthOds
new
Creates an instance that holds two built-in type values.
UVM 1.2 Class Reference
382
VARIABLEs
T1 first
T1 first
The first value in the pair
T2 second
T2 second
The second value in the pair
MEthOds
new
function new (
string name = ""
)
Creates an instance that holds two built-in type values. The optional name argument
gives a name to the new pair object.
UVM 1.2 Class Reference
383
18.4 Policy Classes
Policy classes are used to implement polymorphic operations that differ between built-in
types and class-based types. Generic components can then be built that work with either
classes or built-in types, depending on what policy class is used.
Contents
Policy Classes
Policy classes are used to implement polymorphic
operations that differ between built-in types and classbased types.
uvm_built_in_comp
#(T)
uvm_built_in_converter
#(T)
uvm_built_in_clone
#(T)
uvm_class_comp #(T)
This policy class is used to compare built-in types.
uvm_class_converter
#(T)
uvm_class_clone #(T)
This policy class
strings.
This policy class
operator.
This policy class
same type.
This policy class
string.
This policy class
is used to convert built-in types to
is used to clone built-in types via the =
is used to compare two objects of the
is used to convert a class object to a
is used to clone class objects.
uvm_built_in_comp #(T)
This policy class is used to compare built-in types.
Provides a comp method that compares the built-in type, T, for which the == operator is
defined.
Summary
uvm_built_in_comp #(T)
This policy class is used to compare built-in types.
CLAss DEcLARAtION
class uvm_built_in_comp #(
type T = int
)
uvm_built_in_converter #(T)
This policy class is used to convert built-in types to strings.
Provides a convert2string method that converts the built-in type, T, to a string using the
%p format specifier.
UVM 1.2 Class Reference
384
Summary
uvm_built_in_converter #(T)
This policy class is used to convert built-in types to strings.
CLAss DEcLARAtION
class uvm_built_in_converter #(
type T = int
)
uvm_built_in_clone #(T)
This policy class is used to clone built-in types via the = operator.
Provides a clone method that returns a copy of the built-in type, T.
Summary
uvm_built_in_clone #(T)
This policy class is used to clone built-in types via the = operator.
CLAss DEcLARAtION
class uvm_built_in_clone #(
type T = int
)
uvm_class_comp #(T)
This policy class is used to compare two objects of the same type.
Provides a comp method that compares two objects of type T. The class T must provide
the method “function bit compare(T rhs)”, similar to the uvm_object::compare method.
Summary
uvm_class_comp #(T)
This policy class is used to compare two objects of the same type.
CLAss DEcLARAtION
class uvm_class_comp #(
type T = int
)
UVM 1.2 Class Reference
385
uvm_class_converter #(T)
This policy class is used to convert a class object to a string.
Provides a convert2string method that converts an instance of type T to a string. The
class T must provide the method “function string convert2string()”, similar to the
uvm_object::convert2string method.
Summary
uvm_class_converter #(T)
This policy class is used to convert a class object to a string.
CLAss DEcLARAtION
class uvm_class_converter #(
type T = int
)
uvm_class_clone #(T)
This policy class is used to clone class objects.
Provides a clone method that returns a copy of the built-in type, T. The class T must
implement the clone method, to which this class delegates the operation. If T is derived
from uvm_object, then T must instead implement uvm_object::do_copy, either directly
or indirectly through use of the `uvm_field macros.
Summary
uvm_class_clone #(T)
This policy class is used to clone class objects.
CLAss DEcLARAtION
class uvm_class_clone #(
type T = int
)
UVM 1.2 Class Reference
386
19. Sequencer Classes
The sequencer serves as an arbiter for controlling transaction flow from multiple stimulus
generators. More specifically, the sequencer controls the flow of uvm_sequence_itembased transactions generated by one or more uvm_sequence #(REQ,RSP)-based
sequences.
There are two sequencer variants available.
uvm_sequencer #(REQ,RSP) - Requests for new sequence items are initiated by
the driver. Upon such requests, the sequencer selects a sequence from a list of
available sequences to produce and deliver the next item to execute. This
sequencer is typically connected to a user-extension of uvm_driver #(REQ,RSP).
uvm_push_sequencer #(REQ,RSP) - Sequence items (from the currently running
sequences) are pushed by the sequencer to the driver, which blocks item flow
when it is not ready to accept new transactions. This sequencer is typically
connected to a user-extension of uvm_push_driver #(REQ,RSP).
Sequencer-driver communication follows a pull or push semantic, depending on which
sequencer type is used. However, sequence-sequencer communication is always initiated
by the user-defined sequence, i.e. follows a push semantic.
See Sequence Classes for an overview on sequences and sequence items.
Sequence Item Ports
As with all UVM components, the sequencers and drivers described above use TLM
Interfaces to communicate transactions.
The uvm_sequencer #(REQ,RSP) and uvm_driver #(REQ,RSP) pair also uses a sequence
item pull port to achieve the special execution semantic needed by the sequencer-driver
pair.
UVM 1.2 Class Reference
387
Sequencers and drivers use a seq_item_port specifically supports sequencer-driver
communication. Connections to these ports are made in the same fashion as the TLM
ports.
Summary
Sequencer Classes
The sequencer serves as an arbiter for controlling transaction flow from multiple
stimulus generators.
UVM 1.2 Class Reference
388
19.1 uvm_sequencer_base
Controls the flow of sequences, which generate the stimulus (sequence item
transactions) that is passed on to drivers for execution.
Summary
uvm_sequencer_base
Controls the flow of sequences, which generate the stimulus (sequence item
transactions) that is passed on to drivers for execution.
CLAss HIERARchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_sequencer_base
CLAss DEcLARATION
class uvm_sequencer_base extends uvm_component
METhOds
new
is_child
user_priority_arbitration
execute_item
start_phase_sequence
stop_phase_sequence
wait_for_grant
wait_for_item_done
is_blocked
has_lock
UVM 1.2 Class Reference
Creates and initializes an
instance of this class using the
normal constructor arguments
for uvm_component: name is the
name of the instance, and parent
is the handle to the hierarchical
parent.
Returns 1 if the child sequence is
a child of the parent sequence, 0
otherwise.
When the sequencer arbitration
mode is set to
UVM_SEQ_ARB_USER (via the
set_arbitration method), the
sequencer will call this function
each time that it needs to
arbitrate among sequences.
Executes the given transaction
item directly on this sequencer.
Start the default sequence for
this phase, if any.
Stop the default sequence for
this phase, if any exists, and it is
still executing.
This task issues a request for the
specified sequence.
A sequence may optionally call
wait_for_item_done.
Returns 1 if the sequence
referred to by sequence_ptr is
currently locked out of the
sequencer.
Returns 1 if the sequence
referred to in the parameter
currently has a lock on this
sequencer, 0 otherwise.
389
lock
grab
unlock
ungrab
stop_sequences
is_grabbed
current_grabber
has_do_available
set_arbitration
get_arbitration
wait_for_sequences
send_request
set_max_zero_time_wait_relevant_count
Requests a lock for the sequence
specified by sequence_ptr.
Requests a lock for the sequence
specified by sequence_ptr.
Removes any locks and grabs
obtained by the specified
sequence_ptr.
Removes any locks and grabs
obtained by the specified
sequence_ptr.
Tells the sequencer to kill all
sequences and child sequences
currently operating on the
sequencer, and remove all
requests, locks and responses
that are currently queued.
Returns 1 if any sequence
currently has a lock or grab on
this sequencer, 0 otherwise.
Returns a reference to the
sequence that currently has a
lock or grab on the sequence.
Returns 1 if any sequence
running on this sequencer is
ready to supply a transaction, 0
otherwise.
Specifies the arbitration mode for
the sequencer.
Return the current arbitration
mode set for this sequencer.
Waits for a sequence to have a
new item available.
Derived classes implement this
function to send a request item
to the sequencer, which will
forward it to the driver.
Can be called at any time to
change the maximum number of
times wait_for_relevant() can be
called by the sequencer in zero
time before an error is declared.
METhOds
new
function new (
string name,
uvm_component parent
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent.
is_child
function bit is_child (
uvm_sequence_base parent,
uvm_sequence_base child
UVM 1.2 Class Reference
390
)
Returns 1 if the child sequence is a child of the parent sequence, 0 otherwise.
user_priority_arbitration
virtual function integer user_priority_arbitration(
integer avail_sequences[$]
)
When the sequencer arbitration mode is set to UVM_SEQ_ARB_USER (via the
set_arbitration method), the sequencer will call this function each time that it needs to
arbitrate among sequences.
Derived sequencers may override this method to perform a custom arbitration policy. The override must return one of the entries from the avail_sequences queue, which are
indexes into an internal queue, arb_sequence_q.
The default implementation behaves like UVM_SEQ_ARB_FIFO, which returns the entry at
avail_sequences[0].
execute_item
virtual task execute_item(
uvm_sequence_item item
)
Executes the given transaction item directly on this sequencer. A temporary parent
sequence is automatically created for the item. There is no capability to retrieve
responses. If the driver returns responses, they will accumulate in the sequencer,
eventually causing response overflow unless
uvm_sequence_base::set_response_queue_error_report_disabled is called.
start_phase_sequence
virtual function void start_phase_sequence(
uvm_phase phase
)
Start the default sequence for this phase, if any. The default sequence is configured via
resources using either a sequence instance or sequence type (object wrapper). If both
are used, the sequence instance takes precedence. When attempting to override a
previous default sequence setting, you must override both the instance and type
(wrapper) resources, else your override may not take effect.
When setting the resource using set, the 1st argument specifies the context pointer,
usually this for components or null when executed from outside the component hierarchy
(i.e. in module). The 2nd argument is the instance string, which is a path name to the
target sequencer, relative to the context pointer. The path must include the name of the
phase with a “_phase” suffix. The 3rd argument is the resource name, which is
“default_sequence”. The 4th argument is either an object wrapper for the sequence
type, or an instance of a sequence.
Configuration by instances allows pre-initialization, setting rand_mode, use of inline
constraints, etc.
UVM 1.2 Class Reference
391
myseq_t myseq = new("myseq");
myseq.randomize() with { ... };
uvm_config_db #(uvm_sequence_base)::set(null, "top.agent.myseqr.main_phase",
"default_sequence",
myseq);
Configuration by type is shorter and can be substituted via the factory.
uvm_config_db #(uvm_object_wrapper)::set(null,
"top.agent.myseqr.main_phase",
"default_sequence",
myseq_type::type_id::get());
The uvm_resource_db can similarly be used.
myseq_t myseq = new("myseq");
myseq.randomize() with { ... };
uvm_resource_db #(uvm_sequence_base)::set({get_full_name(),
".myseqr.main_phase",
"default_sequence",
myseq, this);
uvm_resource_db #(uvm_object_wrapper)::set({get_full_name(),
".myseqr.main_phase",
"default_sequence",
myseq_t::type_id::get(),
this );
stop_phase_sequence
virtual function void stop_phase_sequence(
uvm_phase phase
)
Stop the default sequence for this phase, if any exists, and it is still executing.
wait_for_grant
virtual task wait_for_grant(
uvm_sequence_base sequence_ptr, item_priority = -1,
int bit lock_request = 0
)
This task issues a request for the specified sequence. If item_priority is not specified,
then the current sequence priority will be used by the arbiter. If a lock_request is made,
then the sequencer will issue a lock immediately before granting the sequence. (Note
that the lock may be granted without the sequence being granted if is_relevant is not
asserted).
When this method returns, the sequencer has granted the sequence, and the sequence
must call send_request without inserting any simulation delay other than delta cycles. The driver is currently waiting for the next item to be sent via the send_request call.
UVM 1.2 Class Reference
392
wait_for_item_done
virtual task wait_for_item_done(
uvm_sequence_base sequence_ptr,
int transaction_id
)
A sequence may optionally call wait_for_item_done. This task will block until the driver
calls item_done() or put() on a transaction issued by the specified sequence. If no
transaction_id parameter is specified, then the call will return the next time that the
driver calls item_done() or put(). If a specific transaction_id is specified, then the call
will only return when the driver indicates that it has completed that specific item.
Note that if a specific transaction_id has been specified, and the driver has already
issued an item_done or put for that transaction, then the call will hang waiting for that
specific transaction_id.
is_blocked
function bit is_blocked(
uvm_sequence_base sequence_ptr
)
Returns 1 if the sequence referred to by sequence_ptr is currently locked out of the
sequencer. It will return 0 if the sequence is currently allowed to issue operations.
Note that even when a sequence is not blocked, it is possible for another sequence to
issue a lock before this sequence is able to issue a request or lock.
has_lock
function bit has_lock(
uvm_sequence_base sequence_ptr
)
Returns 1 if the sequence referred to in the parameter currently has a lock on this
sequencer, 0 otherwise.
Note that even if this sequence has a lock, a child sequence may also have a lock, in
which case the sequence is still blocked from issuing operations on the sequencer
lock
virtual task lock(
uvm_sequence_base sequence_ptr
)
Requests a lock for the sequence specified by sequence_ptr.
A lock request will be arbitrated the same as any other request. A lock is granted after
all earlier requests are completed and no other locks or grabs are blocking this sequence.
The lock call will return when the lock has been granted.
grab
virtual task grab(
UVM 1.2 Class Reference
393
uvm_sequence_base sequence_ptr
)
Requests a lock for the sequence specified by sequence_ptr.
A grab request is put in front of the arbitration queue. It will be arbitrated before any
other requests. A grab is granted when no other grabs or locks are blocking this
sequence.
The grab call will return when the grab has been granted.
unlock
virtual function void unlock(
uvm_sequence_base sequence_ptr
)
Removes any locks and grabs obtained by the specified sequence_ptr.
ungrab
virtual function void ungrab(
uvm_sequence_base sequence_ptr
)
Removes any locks and grabs obtained by the specified sequence_ptr.
stop_sequences
virtual function void stop_sequences()
Tells the sequencer to kill all sequences and child sequences currently operating on the
sequencer, and remove all requests, locks and responses that are currently queued. This
essentially resets the sequencer to an idle state.
is_grabbed
virtual function bit is_grabbed()
Returns 1 if any sequence currently has a lock or grab on this sequencer, 0 otherwise.
current_grabber
virtual function uvm_sequence_base current_grabber()
Returns a reference to the sequence that currently has a lock or grab on the sequence. If multiple hierarchical sequences have a lock, it returns the child that is currently
allowed to perform operations on the sequencer.
has_do_available
virtual function bit has_do_available()
UVM 1.2 Class Reference
394
Returns 1 if any sequence running on this sequencer is ready to supply a transaction, 0
otherwise. A sequence is ready if it is not blocked (via grab or lock and is_relevant
returns 1.
set_arbitration
function void set_arbitration(
UVM_SEQ_ARB_TYPE val
)
Specifies the arbitration mode for the sequencer. It is one of
UVM_SEQ_ARB_FIFO
Requests are granted in FIFO order
(default)
UVM_SEQ_ARB_WEIGHTED
Requests are granted randomly by weight
UVM_SEQ_ARB_RANDOM
Requests are granted randomly
UVM_SEQ_ARB_STRICT_FIFO
Requests at highest priority granted in
FIFO order
UVM_SEQ_ARB_STRICT_RANDOM
Requests at highest priority granted in
randomly
UVM_SEQ_ARB_USER
Arbitration is delegated to the user-defined
function, user_priority_arbitration. That
function will specify the next sequence to
grant.
The default user function specifies FIFO order.
get_arbitration
function UVM_SEQ_ARB_TYPE get_arbitration()
Return the current arbitration mode set for this sequencer. See set_arbitration for a list
of possible modes.
wait_for_sequences
virtual task wait_for_sequences()
Waits for a sequence to have a new item available. Uses uvm_wait_for_nba_region to
give a sequence as much time as possible to deliver an item before advancing time.
send_request
virtual function void send_request(
uvm_sequence_base sequence_ptr, uvm_sequence_item t,
rerandomize = 0
bit )
Derived classes implement this function to send a request item to the sequencer, which
will forward it to the driver. If the rerandomize bit is set, the item will be randomized
before being sent to the driver.
UVM 1.2 Class Reference
395
This function may only be called after a wait_for_grant call.
set_max_zero_time_wait_relevant_count
virtual function void set_max_zero_time_wait_relevant_count(
int new_val
)
Can be called at any time to change the maximum number of times wait_for_relevant()
can be called by the sequencer in zero time before an error is declared. The default
maximum is 10.
UVM 1.2 Class Reference
396
19.2 uvm_sequencer_param_base #(REQ,RSP)
Extends uvm_sequencer_base with an API depending on specific request (REQ) and
response (RSP) types.
Summary
uvm_sequencer_param_base #(REQ,RSP)
Extends uvm_sequencer_base with an API depending on specific request (REQ)
and response (RSP) types.
CLAss HIerArchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_sequencer_base
uvm_sequencer_param_base#(REQ,RSP)
CLAss DecLArATION
class uvm_sequencer_param_base #(
type REQ = uvm_sequence_item,
type RSP = REQ
) extends uvm_sequencer_base
new
send_request
get_current_item
ReqUesTs
get_num_reqs_sent
set_num_last_reqs
get_num_last_reqs
last_req
RespONses
rsp_export
get_num_rsps_received
set_num_last_rsps
get_num_last_rsps
last_rsp
Creates and initializes an instance of this class using
the normal constructor arguments for
uvm_component: name is the name of the instance,
and parent is the handle to the hierarchical parent,
if any.
The send_request function may only be called after
a wait_for_grant call.
Returns the request_item currently being executed
by the sequencer.
Returns the number of requests that have been
sent by this sequencer.
Sets the size of the last_requests buffer.
Returns the size of the last requests buffer, as set
by set_num_last_reqs.
Returns the last request item by default.
Drivers or monitors can connect to this port to
send responses to the sequencer.
Returns the number of responses received thus far
by this sequencer.
Sets the size of the last_responses buffer.
Returns the max size of the last responses buffer,
as set by set_num_last_rsps.
Returns the last response item by default.
new
UVM 1.2 Class Reference
397
function new (
string name,
uvm_component parent
)
Creates and initializes an instance of this class using the normal constructor arguments
for uvm_component: name is the name of the instance, and parent is the handle to the
hierarchical parent, if any.
send_request
virtual function void send_request(
uvm_sequence_base sequence_ptr, uvm_sequence_item t,
bit rerandomize = 0
)
The send_request function may only be called after a wait_for_grant call. This call will
send the request item, t, to the sequencer pointed to by sequence_ptr. The sequencer
will forward it to the driver. If rerandomize is set, the item will be randomized before
being sent to the driver.
get_current_item
function REQ get_current_item()
Returns the request_item currently being executed by the sequencer. If the sequencer is
not currently executing an item, this method will return null.
The sequencer is executing an item from the time that get_next_item or peek is called
until the time that get or item_done is called.
Note that a driver that only calls get() will never show a current item, since the item is
completed at the same time as it is requested.
ReqUesTs
get_num_reqs_sent
function int get_num_reqs_sent()
Returns the number of requests that have been sent by this sequencer.
set_num_last_reqs
function void set_num_last_reqs(
int unsigned max
)
Sets the size of the last_requests buffer. Note that the maximum buffer size is 1024. If
max is greater than 1024, a warning is issued, and the buffer is set to 1024. The
default value is 1.
UVM 1.2 Class Reference
398
get_num_last_reqs
function int unsigned get_num_last_reqs()
Returns the size of the last requests buffer, as set by set_num_last_reqs.
last_req
function REQ last_req(
int unsigned n = 0
)
Returns the last request item by default. If n is not 0, then it will get the n�th before
last request item. If n is greater than the last request buffer size, the function will
return null.
RespONses
rsp_export
Drivers or monitors can connect to this port to send responses to the sequencer. Alternatively, a driver can send responses via its seq_item_port.
seq_item_port.item_done(response)
seq_item_port.put(response)
rsp_port.write(response)
<--- via this export
The rsp_port in the driver and/or monitor must be connected to the rsp_export in this
sequencer in order to send responses through the response analysis port.
get_num_rsps_received
function int get_num_rsps_received()
Returns the number of responses received thus far by this sequencer.
set_num_last_rsps
function void set_num_last_rsps(
int unsigned max
)
Sets the size of the last_responses buffer. The maximum buffer size is 1024. If max is
greater than 1024, a warning is issued, and the buffer is set to 1024. The default value
is 1.
get_num_last_rsps
function int unsigned get_num_last_rsps()
UVM 1.2 Class Reference
399
Returns the max size of the last responses buffer, as set by set_num_last_rsps.
last_rsp
function RSP last_rsp(
int unsigned n = 0
)
Returns the last response item by default. If n is not 0, then it will get the nth-beforelast response item. If n is greater than the last response buffer size, the function will
return null.
UVM 1.2 Class Reference
400
19.3 uvm_sequencer #(REQ,RSP)
Summary
uvm_sequencer #(REQ,RSP)
CLAss HIerArchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_sequencer_base
uvm_sequencer_param_base#(REQ,RSP)
uvm_sequencer#(REQ,RSP)
CLAss DecLArATION
class uvm_sequencer #(
type REQ = uvm_sequence_item,
RSP = REQ
) extends uvm_sequencer_param_base #(REQ, RSP)
new
stop_sequences
SeqUeNcer INTerFAce
seq_item_export
get_next_item
try_next_item
item_done
put
get
peek
wait_for_sequences
has_do_available
Standard component constructor that creates an
instance of this class using the given name and parent,
if any.
Tells the sequencer to kill all sequences and child
sequences currently operating on the sequencer, and
remove all requests, locks and responses that are
currently queued.
This is an interface for communicating with sequencers.
This export provides access to this sequencer’s
implementation of the sequencer interface.
Retrieves the next available item from a sequence.
Retrieves the next available item from a sequence if
one is available.
Indicates that the request is completed.
Sends a response back to the sequence that issued
the request.
Retrieves the next available item from a sequence.
Returns the current request item if one is in the FIFO.
Waits for a sequence to have a new item available.
Returns 1 if any sequence running on this sequencer is
ready to supply a transaction, 0 otherwise.
new
function new (
string name, uvm_component parent = null
)
Standard component constructor that creates an instance of this class using the given
name and parent, if any.
UVM 1.2 Class Reference
401
stop_sequences
virtual function void stop_sequences()
Tells the sequencer to kill all sequences and child sequences currently operating on the
sequencer, and remove all requests, locks and responses that are currently queued. This
essentially resets the sequencer to an idle state.
SeqUeNcer INTerFAce
This is an interface for communicating with sequencers.
The interface is defined as
Requests:
virtual task
get_next_item
virtual task
try_next_item
virtual task
get
virtual task
peek
Responses:
virtual function void item_done
virtual task
put
Sync Control:
virtual task
wait_for_sequences
virtual function bit has_do_available
(output
(output
(output
(output
REQ request);
REQ request);
REQ request);
REQ request);
(input RSP response=null);
(input RSP response);
();
();
See uvm_sqr_if_base #(REQ,RSP) for information about this interface.
seq_item_export
uvm_seq_item_pull_imp #(
REQ,
RSP,
this_type
) seq_item_export
This export provides access to this sequencer’s implementation of the sequencer
interface.
get_next_item
virtual task get_next_item (
output REQ t
)
Retrieves the next available item from a sequence.
try_next_item
virtual task try_next_item (
output REQ t
)
Retrieves the next available item from a sequence if one is available.
UVM 1.2 Class Reference
402
item_done
virtual function void item_done (
RSP item = null
)
Indicates that the request is completed.
put
virtual task put (
RSP t
)
Sends a response back to the sequence that issued the request.
get
task get (
output REQ t
)
Retrieves the next available item from a sequence.
peek
task peek (
output REQ t
)
Returns the current request item if one is in the FIFO.
wait_for_sequences
Waits for a sequence to have a new item available.
has_do_available
Returns 1 if any sequence running on this sequencer is ready to supply a transaction, 0
otherwise.
UVM 1.2 Class Reference
403
19.4 uvm_push_sequencer #(REQ,RSP)
Summary
uvm_push_sequencer #(REQ,RSP)
CLAss HIerArchY
uvm_void
uvm_object
uvm_report_object
uvm_component
uvm_sequencer_base
uvm_sequencer_param_base#(REQ,RSP)
uvm_push_sequencer#(REQ,RSP)
CLAss DecLArATION
class uvm_push_sequencer #(
type REQ = uvm_sequence_item,
RSP = REQ
) extends uvm_sequencer_param_base #(REQ, RSP)
POrTs
req_port
MeThOds
new
run_phase
The push sequencer requires access to a blocking put interface.
Standard component constructor that creates an instance of
this class using the given name and parent, if any.
The push sequencer continuously selects from its list of
available sequences and sends the next item from the selected
sequence out its req_port using req_port.put(item).
POrTs
req_port
The push sequencer requires access to a blocking put interface. A continuous stream of
sequence items are sent out this port, based on the list of available sequences loaded
into this sequencer.
MeThOds
new
function new (
string name, uvm_component parent = null
UVM 1.2 Class Reference
404
)
Standard component constructor that creates an instance of this class using the given
name and parent, if any.
run_phase
task run_phase(
uvm_phase phase
)
The push sequencer continuously selects from its list of available sequences and sends
the next item from the selected sequence out its req_port using req_port.put(item). Typically, the req_port would be connected to the req_export on an instance of a
uvm_push_driver #(REQ,RSP), which would be responsible for executing the item.
UVM 1.2 Class Reference
405
20. Sequence Classes
Sequences encapsulate user-defined procedures that generate multiple
uvm_sequence_item-based transactions. Such sequences can be reused, extended,
randomized, and combined sequentially and hierarchically in interesting ways to produce
realistic stimulus to your DUT.
With uvm_sequence objects, users can encapsulate DUT initialization code, bus-based
stress tests, network protocol stacks-- anything procedural-- then have them all execute
in specific or random order to more quickly reach corner cases and coverage goals.
The UVM sequence item and sequence class hierarchy is shown below.
uvm_sequence_item - The uvm_sequence_item is the base class for user-defined
transactions that leverage the stimulus generation and control capabilities of the
sequence-sequencer mechanism.
uvm_sequence #(REQ,RSP) - The uvm_sequence extends uvm_sequence_item to
add the ability to generate streams of uvm_sequence_items, either directly or by
recursively executing other uvm_sequences.
Summary
Sequence Classes
Sequences encapsulate user-defined procedures that generate multiple
uvm_sequence_item-based transactions.
UVM 1.2 Class Reference
406
20.1 uvm_sequence_item
The base class for user-defined sequence items and also the base class for the
uvm_sequence class. The uvm_sequence_item class provides the basic functionality for
objects, both sequence items and sequences, to operate in the sequence mechanism.
Summary
uvm_sequence_item
The base class for user-defined sequence items and also the base class for the
uvm_sequence class.
CLAss HIERARchY
uvm_void
uvm_object
uvm_transaction
uvm_sequence_item
CLAss DEcLARATION
class uvm_sequence_item extends uvm_transaction
new
get_sequence_id
set_item_context
set_use_sequence_info
get_use_sequence_info
set_id_info
set_sequencer
get_sequencer
set_parent_sequence
get_parent_sequence
set_depth
get_depth
is_item
get_root_sequence_name
get_root_sequence
get_sequence_path
REPORTING INTERFAcE
uvm_report
uvm_report_info
uvm_report_warning
uvm_report_error
uvm_report_fatal
UVM 1.2 Class Reference
The constructor method for uvm_sequence_item.
private
Set the sequence and sequencer execution context
for a sequence item
These methods are used to set and get the status
of the use_sequence_info bit.
Copies the sequence_id and transaction_id from
the referenced item into the calling item.
Sets the default sequencer for the sequence to
sequencer.
Returns a reference to the default sequencer used
by this sequence.
Sets the parent sequence of this sequence_item.
Returns a reference to the parent sequence of any
sequence on which this method was called.
The depth of any sequence is calculated
automatically.
Returns the depth of a sequence from its parent.
This function may be called on any sequence_item
or sequence.
Provides the name of the root sequence (the topmost parent sequence).
Provides a reference to the root sequence (the topmost parent sequence).
Provides a string of names of each sequence in the
full hierarchical path.
Sequence items and sequences will use the
sequencer which they are associated with for
reporting messages.
These are the primary reporting methods in the
UVM.
407
new
function new (
string name = "uvm_sequence_item"
)
The constructor method for uvm_sequence_item.
get_sequence_id
function int get_sequence_id()
private
Get_sequence_id is an internal method that is not intended for user code. The
sequence_id is not a simple integer. The get_transaction_id is meant for users to
identify specific transactions.
These methods allow access to the sequence_item sequence and transaction IDs.
get_transaction_id and set_transaction_id are methods on the uvm_transaction
base_class. These IDs are used to identify sequences to the sequencer, to route
responses back to the sequence that issued a request, and to uniquely identify
transactions.
The sequence_id is assigned automatically by a sequencer when a sequence initiates
communication through any sequencer calls (i.e. `uvm_do_*, wait_for_grant). A
sequence_id will remain unique for this sequence until it ends or it is killed. However, a
single sequence may have multiple valid sequence ids at any point in time. Should a
sequence start again after it has ended, it will be given a new unique sequence_id.
The transaction_id is assigned automatically by the sequence each time a transaction is
sent to the sequencer with the transaction_id in its default (-1) value. If the user sets
the transaction_id to any non-default value, that value will be maintained.
Responses are routed back to this sequences based on sequence_id. The sequence may
use the transaction_id to correlate responses with their requests.
set_item_context
function void set_item_context(
uvm_sequence_base parent_seq, uvm_sequencer_base sequencer = null
)
Set the sequence and sequencer execution context for a sequence item
set_use_sequence_info
function void set_use_sequence_info(
bit value
)
get_use_sequence_info
UVM 1.2 Class Reference
408
function bit get_use_sequence_info()
These methods are used to set and get the status of the use_sequence_info bit. Use_sequence_info controls whether the sequence information (sequencer,
parent_sequence, sequence_id, etc.) is printed, copied, or recorded. When
use_sequence_info is the default value of 0, then the sequence information is not used. When use_sequence_info is set to 1, the sequence information will be used in printing
and copying.
set_id_info
function void set_id_info(
uvm_sequence_item item
)
Copies the sequence_id and transaction_id from the referenced item into the calling
item. This routine should always be used by drivers to initialize responses for future
compatibility.
set_sequencer
virtual function void set_sequencer(
uvm_sequencer_base sequencer
)
Sets the default sequencer for the sequence to sequencer. It will take effect
immediately, so it should not be called while the sequence is actively communicating with
the sequencer.
get_sequencer
function uvm_sequencer_base get_sequencer()
Returns a reference to the default sequencer used by this sequence.
set_parent_sequence
function void set_parent_sequence(
uvm_sequence_base parent
)
Sets the parent sequence of this sequence_item. This is used to identify the source
sequence of a sequence_item.
get_parent_sequence
function uvm_sequence_base get_parent_sequence()
Returns a reference to the parent sequence of any sequence on which this method was
called. If this is a parent sequence, the method returns null.
set_depth
UVM 1.2 Class Reference
409
function void set_depth(
int value
)
The depth of any sequence is calculated automatically. However, the user may use
set_depth to specify the depth of a particular sequence. This method will override the
automatically calculated depth, even if it is incorrect.
get_depth
function int get_depth()
Returns the depth of a sequence from its parent. A parent sequence will have a depth of
1, its child will have a depth of 2, and its grandchild will have a depth of 3.
is_item
virtual function bit is_item()
This function may be called on any sequence_item or sequence. It will return 1 for items
and 0 for sequences (which derive from this class).
get_root_sequence_name
function string get_root_sequence_name()
Provides the name of the root sequence (the top -most parent sequence).
get_root_sequence
function uvm_sequence_base get_root_sequence()
Provides a reference to the root sequence (the top -most parent sequence).
get_sequence_path
function string get_sequence_path()
Provides a string of names of each sequence in the full hierarchical path. A “.” is used as
the separator between each sequence.
REPORTING INTERFAcE
Sequence items and sequences will use the sequencer which they are associated with for
reporting messages. If no sequencer has been set for the item/sequence using
set_sequencer or indirectly via uvm_sequence_base::start_item or
uvm_sequence_base::start), then the global reporter will be used.
UVM 1.2 Class Reference
410
uvm_report
virtual function void uvm_report(
uvm_severity severity,
string id,
string message,
verbosity
int string int string bit )
= (severity ==
uvm_severity'(UVM_ERROR)) ?
UVM_LOW : (severity ==
uvm_severity'(UVM_FATAL)) ?
UVM_NONE : UVM_MEDIUM,
filename
= "",
line
= 0,
context_name
= "",
report_enabled_checked = 0
uvm_report_info
virtual function void uvm_report_info(
string id,
string message,
int verbosity
= UVM_MEDIUM,
string filename
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
uvm_report_warning
virtual function void uvm_report_warning(
string id,
string message,
int verbosity
= UVM_MEDIUM,
string filename
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
uvm_report_error
virtual function void uvm_report_error(
string id,
string message,
int verbosity
= UVM_LOW,
string filename
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
uvm_report_fatal
virtual function void uvm_report_fatal(
string id,
string message,
verbosity
= UVM_NONE,
int string filename
= "",
int line
= 0,
string context_name
= "",
bit report_enabled_checked = 0
)
UVM 1.2 Class Reference
411
These are the primary reporting methods in the UVM. uvm_sequence_item derived types
delegate these functions to their associated sequencer if they have one, or to the global
reporter. See uvm_report_object::Reporting for details on the messaging functions.
UVM 1.2 Class Reference
412
20.2 uvm_sequence_base
The uvm_sequence_base class provides the interfaces needed to create streams of
sequence items and/or other sequences.
A sequence is executed by calling its start method, either directly or invocation of any of
the `uvm_do_* macros.
Executing sequences via start
A sequence’s start method has a parent_sequence argument that controls whether
pre_do, mid_do, and post_do are called in the parent sequence. It also has a
call_pre_post argument that controls whether its pre_body and post_body methods are
called. In all cases, its pre_start and post_start methods are always called.
When start is called directly, you can provide the appropriate arguments according to
your application.
The sequence execution flow looks like this
User code
sub_seq.randomize(...); // optional
sub_seq.start(seqr, parent_seq, priority, call_pre_post)
The following methods are called, in order
sub_seq.pre_start()
sub_seq.pre_body()
parent_seq.pre_do(0)
parent_seq.mid_do(this)
sub_seq.body
parent_seq.post_do(this)
sub_seq.post_body()
sub_seq.post_start()
(task)
(task) if call_pre_post==1
(task) if parent_sequence!=null
(func) if parent_sequence!=null
(task) YOUR STIMULUS CODE
(func) if parent_sequence!=null
(task) if call_pre_post==1
(task)
Executing sub-sequences via `uvm_do macros
A sequence can also be indirectly started as a child in the body of a parent sequence. The child sequence’s start method is called indirectly by invoking any of the `uvm_do
macros. In these cases, start is called with call_pre_post set to 0, preventing the started
sequence’s pre_body and post_body methods from being called. During execution of the
child sequence, the parent’s pre_do, mid_do, and post_do methods are called.
The sub-sequence execution flow looks like
User code
`uvm_do_with_prior(seq_seq, { constraints }, priority)
The following methods are called, in order
sub_seq.pre_start()
parent_seq.pre_do(0)
UVM 1.2 Class Reference
(task)
(task)
413
parent_req.mid_do(sub_seq) (func)
sub_seq.body()
(task)
parent_seq.post_do(sub_seq) (func)
sub_seq.post_start()
(task)
Remember, it is the parent sequence’s pre|mid|post_do that are called, not the
sequence being executed.
Executing sequence items via start_item/finish_item or `uvm_do macros
Items are started in the body of a parent sequence via calls to start_item/finish_item or
invocations of any of the `uvm_do macros. The pre_do, mid_do, and post_do methods
of the parent sequence will be called as the item is executed.
The sequence-item execution flow looks like
User code
parent_seq.start_item(item, priority);
item.randomize(...) [with {constraints}];
parent_seq.finish_item(item);
or
`uvm_do_with_prior(item, constraints, priority)
The following methods are called, in order
sequencer.wait_for_grant(prior) (task) \ start_item
parent_seq.pre_do(1)
(task) /
parent_seq.mid_do(item)
sequencer.send_request(item)
sequencer.wait_for_item_done()
parent_seq.post_do(item)
\
\
`uvm_do* macros
(func) \
/
(func) \finish_item /
(task) /
(func) /
Attempting to execute a sequence via start_item/finish_item will produce a run-time
error.
Summary
uvm_sequence_base
The uvm_sequence_base class provides the interfaces needed to create streams
of sequence items and/or other sequences.
CLAss HIeRARchY
uvm_void
uvm_object
uvm_transaction
uvm_sequence_item
uvm_sequence_base
CLAss DecLARATION
class uvm_sequence_base extends uvm_sequence_item
UVM 1.2 Class Reference
414
do_not_randomize
new
is_item
get_sequence_state
wait_for_sequence_state
get_tr_handle
SeQUeNce EXecUTION
start
pre_start
pre_body
pre_do
mid_do
body
post_do
post_body
post_start
RUN-TIMe PhAsING
get_starting_phase
set_starting_phase
set_automatic_phase_objection
UVM 1.2 Class Reference
If set, prevents the sequence
from being randomized before
being executed by the
`uvm_do*() and
`uvm_rand_send*() macros, or
as a default sequence.
The constructor for
uvm_sequence_base.
Returns 1 on items and 0 on
sequences.
Returns the sequence state as
an enumerated value.
Waits until the sequence
reaches one of the given state.
Returns the integral recording
transaction handle for this
sequence.
Executes this sequence,
returning when the sequence
has completed.
This task is a user-definable
callback that is called before
the optional execution of
pre_body.
This task is a user-definable
callback that is called before
the execution of body only
when the sequence is started
with start.
This task is a user-definable
callback task that is called on
the parent sequence, if any
sequence has issued a
wait_for_grant() call and after
the sequencer has selected
this sequence, and before the
item is randomized.
This function is a userdefinable callback function that
is called after the sequence
item has been randomized,
and just before the item is
sent to the driver.
This is the user-defined task
where the main sequence code
resides.
This function is a userdefinable callback function that
is called after the driver has
indicated that it has completed
the item, using either this
item_done or put methods.
This task is a user-definable
callback task that is called
after the execution of body
only when the sequence is
started with start.
This task is a user-definable
callback that is called after the
optional execution of
post_body.
Returns the ‘starting phase’.
Sets the ‘starting phase’.
Sets the ‘automatically object
to starting phase’ bit.
415
get_automatic_phase_objection
SeQUeNce CONTROL
set_priority
get_priority
is_relevant
wait_for_relevant
lock
grab
unlock
ungrab
is_blocked
has_lock
kill
do_kill
SeQUeNce ITeM EXecUTION
create_item
start_item
finish_item
wait_for_grant
send_request
wait_for_item_done
RespONse API
use_response_handler
UVM 1.2 Class Reference
Returns (and locks) the value
of the ‘automatically object to
starting phase’ bit.
The priority of a sequence may
be changed at any point in
time.
This function returns the
current priority of the
sequence.
The default is_relevant
implementation returns 1,
indicating that the sequence is
always relevant.
This method is called by the
sequencer when all available
sequences are not relevant.
Requests a lock on the
specified sequencer.
Requests a lock on the
specified sequencer.
Removes any locks or grabs
obtained by this sequence on
the specified sequencer.
Removes any locks or grabs
obtained by this sequence on
the specified sequencer.
Returns a bit indicating
whether this sequence is
currently prevented from
running due to another lock or
grab.
Returns 1 if this sequence has
a lock, 0 otherwise.
This function will kill the
sequence, and cause all
current locks and requests in
the sequence’s default
sequencer to be removed.
This function is a user hook
that is called whenever a
sequence is terminated by
using either sequence.kill() or
sequencer.stop_sequences()
(which effectively calls
sequence.kill()).
Create_item will create and
initialize a sequence_item or
sequence using the factory.
start_item and finish_item
together will initiate operation
of a sequence item.
finish_item, together with
start_item together will initiate
operation of a sequence_item.
This task issues a request to
the current sequencer.
The send_request function
may only be called after a
wait_for_grant call.
A sequence may optionally call
wait_for_item_done.
When called with enable set to
1, responses will be sent to
416
get_use_response_handler
response_handler
set_response_queue_error_report_disabled
get_response_queue_error_report_disabled
set_response_queue_depth
get_response_queue_depth
clear_response_queue
the response handler.
Returns the state of the
use_response_handler bit.
When the
use_response_handler bit is
set to 1, this virtual task is
called by the sequencer for
each response that arrives for
this sequence.
By default, if the
response_queue overflows, an
error is reported.
When this bit is 0 (default
value), error reports are
generated when the response
queue overflows.
The default maximum depth of
the response queue is 8.
Returns the current depth
setting for the response
queue.
Empties the response queue
for this sequence.
do_not_randomize
bit do_not_randomize
If set, prevents the sequence from being randomized before being executed by the
`uvm_do*() and `uvm_rand_send*() macros, or as a default sequence.
new
function new (
string name = "uvm_sequence"
)
The constructor for uvm_sequence_base.
is_item
virtual function bit is_item()
Returns 1 on items and 0 on sequences. As this object is a sequence, is_item will
always return 0.
get_sequence_state
function uvm_sequence_state_enum get_sequence_state()
Returns the sequence state as an enumerated value. Can use to wait on the sequence
reaching or changing from one or more states.
wait(get_sequence_state() & (UVM_STOPPED|UVM_FINISHED));
UVM 1.2 Class Reference
417
wait_for_sequence_state
task wait_for_sequence_state(
int unsigned state_mask
)
Waits until the sequence reaches one of the given state. If the sequence is already in
one of the state, this method returns immediately.
wait_for_sequence_state(UVM_STOPPED|UVM_FINISHED);
get_tr_handle
function integer get_tr_handle()
Returns the integral recording transaction handle for this sequence. Can be used to
associate sub-sequences and sequence items as child transactions when calling
uvm_component::begin_child_tr.
SeQUeNce EXecUTION
start
virtual task start (
uvm_sequencer_base sequencer,
uvm_sequence_base parent_sequence = null,
int this_priority = -1,
bit call_pre_post = 1
)
Executes this sequence, returning when the sequence has completed.
The sequencer argument specifies the sequencer on which to run this sequence. The
sequencer must be compatible with the sequence.
If parent_sequence is null, then this sequence is a root parent, otherwise it is a child of
parent_sequence. The parent_sequence’s pre_do, mid_do, and post_do methods will be
called during the execution of this sequence.
By default, the priority of a sequence is the priority of its parent sequence. If it is a root
sequence, its default priority is 100. A different priority may be specified by
this_priority. Higher numbers indicate higher priority.
If call_pre_post is set to 1 (default), then the pre_body and post_body tasks will be
called before and after the sequence body is called.
pre_start
virtual task pre_start()
UVM 1.2 Class Reference
418
This task is a user-definable callback that is called before the optional execution of
pre_body. This method should not be called directly by the user.
pre_body
virtual task pre_body()
This task is a user-definable callback that is called before the execution of body only
when the sequence is started with start. If start is called with call_pre_post set to 0,
pre_body is not called. This method should not be called directly by the user.
pre_do
virtual task pre_do(
bit is_item
)
This task is a user-definable callback task that is called on the parent sequence, if any
sequence has issued a wait_for_grant() call and after the sequencer has selected this
sequence, and before the item is randomized.
Although pre_do is a task, consuming simulation cycles may result in unexpected
behavior on the driver.
This method should not be called directly by the user.
mid_do
virtual function void mid_do(
uvm_sequence_item this_item
)
This function is a user-definable callback function that is called after the sequence item
has been randomized, and just before the item is sent to the driver. This method should
not be called directly by the user.
body
virtual task body()
This is the user-defined task where the main sequence code resides. This method should
not be called directly by the user.
post_do
virtual function void post_do(
uvm_sequence_item this_item
)
This function is a user-definable callback function that is called after the driver has
indicated that it has completed the item, using either this item_done or put methods. This method should not be called directly by the user.
UVM 1.2 Class Reference
419
post_body
virtual task post_body()
This task is a user-definable callback task that is called after the execution of body only
when the sequence is started with start. If start is called with call_pre_post set to 0,
post_body is not called. This task is a user-definable callback task that is called after
the execution of the body, unless the sequence is started with call_pre_post=0. This
method should not be called directly by the user.
post_start
virtual task post_start()
This task is a user-definable callback that is called after the optional execution of
post_body. This method should not be called directly by the user.
RUN-TIMe PhAsING
get_starting_phase
function uvm_phase get_starting_phase()
Returns the ‘starting phase’.
If non-null, the starting phase specifies the phase in which this sequence was started. The starting phase is set automatically when this sequence is started as the default
sequence on a sequencer. See uvm_sequencer_base::start_phase_sequence for more
information.
Internally, the uvm_sequence_base uses a uvm_get_to_lock_dap to protect the starting
phase value from being modified after the reference has been read. Once the sequence
has ended its execution (either via natural termination, or being killed), then the starting
phase value can be modified again.
set_starting_phase
function void set_starting_phase(
uvm_phase phase
)
Sets the ‘starting phase’.
Internally, the uvm_sequence_base uses a uvm_get_to_lock_dap to protect the starting
phase value from being modified after the reference has been read. Once the sequence
has ended its execution (either via natural termination, or being killed), then the starting
phase value can be modified again.
set_automatic_phase_objection
function void set_automatic_phase_objection(
bit value
UVM 1.2 Class Reference
420
)
Sets the ‘automatically object to starting phase’ bit.
The most common interaction with the starting phase within a sequence is to simply
raise the phase’s objection prior to executing the sequence, and drop the objection after
ending the sequence (either naturally, or via a call to kill). In order to simplify this
interaction for the user, the UVM provides the ability to perform this functionality
automatically.
For example
function my_sequence::new(string name="unnamed");
super.new(name);
set_automatic_phase_objection(1);
endfunction : new
From a timeline point of view, the automatic phase objection looks like:
start() is executed
--! Objection is raised !-pre_start() is executed
pre_body() is optionally executed
body() is executed
post_body() is optionally executed
post_start() is executed
--! Objection is dropped !-start() unblocks
This functionality can also be enabled in sequences which were not written with UVM
Run-Time Phasing in mind:
my_legacy_seq_type seq = new("seq");
seq.set_automatic_phase_objection(1);
seq.start(my_sequencer);
Internally, the uvm_sequence_base uses a uvm_get_to_lock_dap to protect the
automatic_phase_objection value from being modified after the reference has been read. Once the sequence has ended its execution (either via natural termination, or being
killed), then the automatic_phase_objection value can be modified again.
NEVER set the automatic phase objection bit to 1 if your sequence runs with a forever
loop inside of the body, as the objection will never get dropped!
get_automatic_phase_objection
function bit get_automatic_phase_objection()
Returns (and locks) the value of the ‘automatically object to starting phase’ bit.
If 1, then the sequence will automatically raise an objection to the starting phase (if the
starting phase is not null) immediately prior to pre_start being called. The objection will
be dropped after post_start has executed, or kill has been called.
UVM 1.2 Class Reference
421
SeQUeNce CONTROL
set_priority
function void set_priority (
int value
)
The priority of a sequence may be changed at any point in time. When the priority of a
sequence is changed, the new priority will be used by the sequencer the next time that it
arbitrates between sequences.
The default priority value for a sequence is 100. Higher values result in higher priorities.
get_priority
function int get_priority()
This function returns the current priority of the sequence.
is_relevant
virtual function bit is_relevant()
The default is_relevant implementation returns 1, indicating that the sequence is always
relevant.
Users may choose to override with their own virtual function to indicate to the sequencer
that the sequence is not currently relevant after a request has been made.
When the sequencer arbitrates, it will call is_relevant on each requesting, unblocked
sequence to see if it is relevant. If a 0 is returned, then the sequence will not be
chosen.
If all requesting sequences are not relevant, then the sequencer will call
wait_for_relevant on all sequences and re-arbitrate upon its return.
Any sequence that implements is_relevant must also implement wait_for_relevant so that
the sequencer has a way to wait for a sequence to become relevant.
wait_for_relevant
virtual task wait_for_relevant()
This method is called by the sequencer when all available sequences are not relevant. When wait_for_relevant returns the sequencer attempt to re-arbitrate.
Returning from this call does not guarantee a sequence is relevant, although that would
be the ideal. The method provide some delay to prevent an infinite loop.
If a sequence defines is_relevant so that it is not always relevant (by default, a sequence
is always relevant), then the sequence must also supply a wait_for_relevant method.
UVM 1.2 Class Reference
422
lock
task lock(
uvm_sequencer_base sequencer = null
)
Requests a lock on the specified sequencer. If sequencer is null, the lock will be
requested on the current default sequencer.
A lock request will be arbitrated the same as any other request. A lock is granted after
all earlier requests are completed and no other locks or grabs are blocking this sequence.
The lock call will return when the lock has been granted.
grab
task grab(
uvm_sequencer_base sequencer = null
)
Requests a lock on the specified sequencer. If no argument is supplied, the lock will be
requested on the current default sequencer.
A grab request is put in front of the arbitration queue. It will be arbitrated before any
other requests. A grab is granted when no other grabs or locks are blocking this
sequence.
The grab call will return when the grab has been granted.
unlock
function void unlock(
uvm_sequencer_base sequencer = null
)
Removes any locks or grabs obtained by this sequence on the specified sequencer. If
sequencer is null, then the unlock will be done on the current default sequencer.
ungrab
function void ungrab(
uvm_sequencer_base sequencer = null
)
Removes any locks or grabs obtained by this sequence on the specified sequencer. If
sequencer is null, then the unlock will be done on the current default sequencer.
is_blocked
function bit is_blocked()
Returns a bit indicating whether this sequence is currently prevented from running due
to another lock or grab. A 1 is returned if the sequence is currently blocked. A 0 is
returned if no lock or grab prevents this sequence from executing. Note that even if a
sequence is not blocked, it is possible for another sequence to issue a lock or grab
before this sequence can issue a request.
UVM 1.2 Class Reference
423
has_lock
function bit has_lock()
Returns 1 if this sequence has a lock, 0 otherwise.
Note that even if this sequence has a lock, a child sequence may also have a lock, in
which case the sequence is still blocked from issuing operations on the sequencer.
kill
function void kill()
This function will kill the sequence, and cause all current locks and requests in the
sequence’s default sequencer to be removed. The sequence state will change to
UVM_STOPPED, and the post_body() and post_start() callback methods will not be
executed.
If a sequence has issued locks, grabs, or requests on sequencers other than the default
sequencer, then care must be taken to unregister the sequence with the other
sequencer(s) using the sequencer unregister_sequence() method.
do_kill
virtual function void do_kill()
This function is a user hook that is called whenever a sequence is terminated by using
either sequence.kill() or sequencer.stop_sequences() (which effectively calls
sequence.kill()).
SeQUeNce ITeM EXecUTION
create_item
protected function uvm_sequence_item create_item(
uvm_object_wrapper type_var,
uvm_sequencer_base l_sequencer,
string name
)
Create_item will create and initialize a sequence_item or sequence using the factory. The sequence_item or sequence will be initialized to communicate with the specified
sequencer.
start_item
virtual task start_item (
uvm_sequence_item item,
set_priority = -1,
int uvm_sequencer_base sequencer
= null
)
UVM 1.2 Class Reference
424
start_item and finish_item together will initiate operation of a sequence item. If the item
has not already been initialized using create_item, then it will be initialized here to use
the default sequencer specified by m_sequencer. Randomization may be done between
start_item and finish_item to ensure late generation
finish_item
virtual task finish_item (
uvm_sequence_item item,
int set_priority = -1
)
finish_item, together with start_item together will initiate operation of a sequence_item. Finish_item must be called after start_item with no delays or delta-cycles. Randomization, or other functions may be called between the start_item and finish_item
calls.
wait_for_grant
virtual task wait_for_grant(
int item_priority = -1,
bit lock_request = 0
)
This task issues a request to the current sequencer. If item_priority is not specified,
then the current sequence priority will be used by the arbiter. If a lock_request is made,
then the sequencer will issue a lock immediately before granting the sequence. (Note
that the lock may be granted without the sequence being granted if is_relevant is not
asserted).
When this method returns, the sequencer has granted the sequence, and the sequence
must call send_request without inserting any simulation delay other than delta cycles. The driver is currently waiting for the next item to be sent via the send_request call.
send_request
virtual function void send_request(
uvm_sequence_item request,
rerandomize = 0
bit )
The send_request function may only be called after a wait_for_grant call. This call will
send the request item to the sequencer, which will forward it to the driver. If the
rerandomize bit is set, the item will be randomized before being sent to the driver.
wait_for_item_done
virtual task wait_for_item_done(
int transaction_id = -1
)
A sequence may optionally call wait_for_item_done. This task will block until the driver
calls item_done or put. If no transaction_id parameter is specified, then the call will
return the next time that the driver calls item_done or put. If a specific transaction_id is
specified, then the call will return when the driver indicates completion of that specific
item.
UVM 1.2 Class Reference
425
Note that if a specific transaction_id has been specified, and the driver has already
issued an item_done or put for that transaction, then the call will hang, having missed
the earlier notification.
RespONse API
use_response_handler
function void use_response_handler(
bit enable
)
When called with enable set to 1, responses will be sent to the response handler. Otherwise, responses must be retrieved using get_response.
By default, responses from the driver are retrieved in the sequence by calling
get_response.
An alternative method is for the sequencer to call the response_handler function with
each response.
get_use_response_handler
function bit get_use_response_handler()
Returns the state of the use_response_handler bit.
response_handler
virtual function void response_handler(
uvm_sequence_item response
)
When the use_response_handler bit is set to 1, this virtual task is called by the
sequencer for each response that arrives for this sequence.
set_response_queue_error_report_disabled
function void set_response_queue_error_report_disabled(
bit value
)
By default, if the response_queue overflows, an error is reported. The response_queue
will overflow if more responses are sent to this sequence from the driver than
get_response calls are made. Setting value to 0 disables these errors, while setting it to
1 enables them.
get_response_queue_error_report_disabled
function bit get_response_queue_error_report_disabled()
UVM 1.2 Class Reference
426
When this bit is 0 (default value), error reports are generated when the response queue
overflows. When this bit is 1, no such error reports are generated.
set_response_queue_depth
function void set_response_queue_depth(
int value
)
The default maximum depth of the response queue is 8. These method is used to
examine or change the maximum depth of the response queue.
Setting the response_queue_depth to -1 indicates an arbitrarily deep response queue. No checking is done.
get_response_queue_depth
function int get_response_queue_depth()
Returns the current depth setting for the response queue.
clear_response_queue
virtual function void clear_response_queue()
Empties the response queue for this sequence.
UVM 1.2 Class Reference
427
20.3 uvm_sequence #(REQ,RSP)
The uvm_sequence class provides the interfaces necessary in order to create streams of
sequence items and/or other sequences.
Summary
uvm_sequence #(REQ,RSP)
The uvm_sequence class provides the interfaces necessary in order to create
streams of sequence items and/or other sequences.
CLAss HIerArchY
uvm_void
uvm_object
uvm_transaction
uvm_sequence_item
uvm_sequence_base
uvm_sequence#(REQ,RSP)
CLAss DecLArATION
virtual class uvm_sequence #(
type REQ = uvm_sequence_item,
type RSP = REQ
) extends uvm_sequence_base
VArIABLes
req
rsp
MeThOds
new
send_request
get_current_item
get_response
The sequence contains a field of the request type called
req.
The sequence contains a field of the response type called
rsp.
Creates and initializes a new sequence object.
This method will send the request item to the sequencer,
which will forward it to the driver.
Returns the request item currently being executed by the
sequencer.
By default, sequences must retrieve responses by calling
get_response.
VArIABLes
req
REQ req
The sequence contains a field of the request type called req. The user can use this field,
if desired, or create another field to use. The default do_print will print this field.
UVM 1.2 Class Reference
428
rsp
RSP rsp
The sequence contains a field of the response type called rsp. The user can use this
field, if desired, or create another field to use. The default do_print will print this field.
MeThOds
new
function new (
string name = "uvm_sequence"
)
Creates and initializes a new sequence object.
send_request
function void send_request(
uvm_sequence_item request,
rerandomize = 0
bit )
This method will send the request item to the sequencer, which will forward it to the
driver. If the rerandomize bit is set, the item will be randomized before being sent to
the driver. The send_request function may only be called after
uvm_sequence_base::wait_for_grant returns.
get_current_item
function REQ get_current_item()
Returns the request item currently being executed by the sequencer. If the sequencer is
not currently executing an item, this method will return null.
The sequencer is executing an item from the time that get_next_item or peek is called
until the time that get or item_done is called.
Note that a driver that only calls get will never show a current item, since the item is
completed at the same time as it is requested.
get_response
virtual task get_response(
output RSP response,
input int transaction_id = -1
)
By default, sequences must retrieve responses by calling get_response. If no
transaction_id is specified, this task will return the next response sent to this sequence. If no response is available in the response queue, the method will block until a response
is received.
UVM 1.2 Class Reference
429
If a transaction_id is parameter is specified, the task will block until a response with that
transaction_id is received in the response queue.
The default size of the response queue is 8. The get_response method must be called
soon enough to avoid an overflow of the response queue to prevent responses from
being dropped.
If a response is dropped in the response queue, an error will be reported unless the error
reporting is disabled via set_response_queue_error_report_disabled.
UVM 1.2 Class Reference
430
20.4 uvm_sequence_library
The uvm_sequence_library is a sequence that contains a list of registered sequence
types. It can be configured to create and execute these sequences any number of times
using one of several modes of operation, including a user-defined mode.
When started (as any other sequence), the sequence library will randomly select and
execute a sequence from its sequences queue. If in UVM_SEQ_LIB_RAND mode, its
select_rand property is randomized and used as an index into sequences. When in
UVM_SEQ_LIB_RANDC mode, the select_randc property is used. When in
UVM_SEQ_LIB_ITEM mode, only sequence items of the REQ type are generated and
executed--no sequences are executed. Finally, when in UVM_SEQ_LIB_USER mode, the
select_sequence method is called to obtain the index for selecting the next sequence to
start. Users can override this method in subtypes to implement custom selection
algorithms.
Creating a subtype of a sequence library requires invocation of the
`uvm_sequence_library_utils macro in its declaration and calling the
init_sequence_library method in its constructor. The macro and function are needed to
populate the sequence library with any sequences that were statically registered with it
or any of its base classes.
class my_seq_lib extends uvm_sequence_library #(my_item);
`uvm_object_utils(my_seq_lib)
`uvm_sequence_library_utils(my_seq_lib)
function new(string name="");
super.new(name);
init_sequence_library();
endfunction
...
endclass
Contents
uvm_sequence_library
uvm_sequence_library_cfg
The uvm_sequence_library is a sequence that
contains a list of registered sequence types.
A convenient container class for configuring all the
sequence library parameters using a single set
command.
new
function new(
string name = ""
)
Create a new instance of this class
get_type_name
virtual function string get_type_name()
Get the type name of this class
UVM 1.2 Class Reference
431
SEQUENcE
sELEcTION
selection_mode
uvm_sequence_lib_mode selection_mode
Specifies the mode used to select sequences for execution
If you do not have access to an instance of the library, use the configuration resource
interface.
The following example sets the config_seq_lib as the default sequence for the ‘main’
phase on the sequencer to be located at “env.agent.sequencer” and set the selection
mode to UVM_SEQ_LIB_RANDC. If the settings are being done from within a
component, the first argument must be this and the second argument a path relative to
that component.
uvm_config_db #(uvm_object_wrapper)::set(null,
"env.agent.sequencer.main_phase",
"default_sequence",
main_seq_lib::get_type());
uvm_config_db #(uvm_sequence_lib_mode)::set(null,
"env.agent.sequencer.main_phase",
"default_sequence.selection_mode",
UVM_SEQ_LIB_RANDC);
Alternatively, you may create an instance of the sequence library a priori, initialize all its
parameters, randomize it, then set it to run as-is on the sequencer.
main_seq_lib my_seq_lib;
my_seq_lib = new("my_seq_lib");
my_seq_lib.selection_mode = UVM_SEQ_LIB_RANDC;
my_seq_lib.min_random_count = 500;
my_seq_lib.max_random_count = 1000;
void'(my_seq_lib.randomize());
uvm_config_db #(uvm_sequence_base)::set(null,
"env.agent.sequencer.main_phase",
"default_sequence",
my_seq_lib);
min_random_count
int unsigned min_random_count=10
Sets the minimum number of items to execute. Use the configuration mechanism to
set. See selection_mode for an example.
max_random_count
int unsigned max_random_count=10
Sets the maximum number of items to execute. Use the configuration mechanism to
set. See selection_mode for an example.
UVM 1.2 Class Reference
432
sequences_executed
protected int unsigned sequences_executed
Indicates the number of sequences executed, not including the currently executing
sequence, if any.
sequence_count
rand int unsigned sequence_count = 10
Specifies the number of sequences to execute when this sequence library is started. If in
UVM_SEQ_LIB_ITEM mode, specifies the number of sequence items that will be
generated.
select_rand
rand int unsigned select_rand
The index variable that is randomized to select the next sequence to execute when in
UVM_SEQ_LIB_RAND mode
Extensions may place additional constraints on this variable.
select_randc
randc bit [15:0] select_randc
The index variable that is randomized to select the next sequence to execute when in
UVM_SEQ_LIB_RANDC mode
Extensions may place additional constraints on this variable.
select_sequence
virtual function int unsigned select_sequence(
int unsigned max
)
Generates an index used to select the next sequence to execute. Overrides must return
a value between 0 and max, inclusive. Used only for UVM_SEQ_LIB_USER selection
mode. The default implementation returns 0, incrementing on successive calls, wrapping
back to 0 when reaching max.
SEQUENcE
REGIsTRATION
add_typewide_sequence
static function void add typewide sequence(
UVM 1.2 Class Reference
433
uvm_object_wrapper seq_type
)
Registers the provided sequence type with this sequence library type. The sequence type
will be available for selection by all instances of this class. Sequence types already
registered are silently ignored.
add_typewide_sequences
static function void add_typewide_sequences(
uvm_object_wrapper seq_types[$]
)
Registers the provided sequence types with this sequence library type. The sequence
types will be available for selection by all instances of this class. Sequence types already
registered are silently ignored.
add_sequence
function void add_sequence(
uvm_object_wrapper seq_type
)
Registers the provided sequence type with this sequence library instance. Sequence
types already registered are silently ignored.
add_sequences
virtual function void add_sequences(
uvm_object_wrapper seq_types[$]
)
Registers the provided sequence types with this sequence library instance. Sequence
types already registered are silently ignored.
remove_sequence
virtual function void remove_sequence(
uvm_object_wrapper seq_type
)
Removes the given sequence type from this sequence library instance. If the type was
registered statically, the sequence queues of all instances of this library will be updated
accordingly. A warning is issued if the sequence is not registered.
get_sequences
virtual function void get_sequences(
ref uvm_object_wrapper seq_types[$]
)
Append to the provided seq_types array the list of registered sequences.
UVM 1.2 Class Reference
434
init_sequence_library
function void init_sequence_library()
All subtypes of this class must call init_sequence_library in its constructor.
uvm_sequence_library_utils
All subtypes of this class must invoke the `uvm_sequence_library_utils macro.
class my_seq_lib extends uvm_sequence_library #(my_item);
`uvm_object_utils(my_seq_lib)
`uvm_sequence_library_utils(my_seq_lib)
function new(string name="");
super.new(name);
init_sequence_library();
endfunction
...
endclass
uvm_sequence_library_cfg
A convenient container class for configuring all the sequence library parameters using a
single set command.
uvm_sequence_library_cfg cfg;
cfg = new("seqlib_cfg", UVM_SEQ_LIB_RANDC, 1000, 2000);
uvm_config_db #(uvm_sequence_library_cfg)::set(null,
"env.agent.sequencer.main_ph",
"default_sequence.config",
cfg);
Summary
uvm_sequence_library_cfg
A convenient container class for configuring all the sequence library parameters
using a single set command.
CLAss HIERARchY
uvm_void
uvm_object
uvm_sequence_library_cfg
CLAss DEcLARATION
class uvm_sequence_library_cfg extends uvm_object
UVM 1.2 Class Reference
435
21. Macros and Defines
UVM includes some macros to allow the user to specify intent without the need to
specify multiple types of SystemVerilog constructs. These macros assist with reporting,
object behavior (interaction with the factory and field usage in comparing/copying/etc),
sequence specification, and TLM connection.
UVM also includes some defines to specify sizing in the register space and to determine
version of the UVM standard and/or implementation.
Summary
Macros and Defines
UVM includes some macros to allow the user to specify intent without the need to
specify multiple types of SystemVerilog constructs.
UVM 1.2 Class Reference
436
21.1 Report Macros
This set of macros provides wrappers around the uvm_report_* Reporting functions. The
macros serve two essential purposes:
To reduce the processing overhead associated with filtered out messages, a check
is made against the report’s verbosity setting and the action for the id/severity
pair before any string formatting is performed. This affects only `uvm_info
reports.
The `__FILE__ and `__LINE__ information is automatically provided to the
underlying uvm_report_* call. Having the file and line number from where a
report was issued aides in debug. You can disable display of file and line
information in reports by defining UVM_REPORT_DISABLE_FILE_LINE on the
command line.
The macros also enforce a verbosity setting of UVM_NONE for warnings, errors and fatals
so that they cannot be mistakenly turned off by setting the verbosity level too low
(warning and errors can still be turned off by setting the actions appropriately).
To use the macros, replace the previous call to uvm_report_* with the corresponding
macro.
//Previous calls to uvm_report_*
uvm_report_info("MYINFO1", $sformatf("val: %0d", val), UVM_LOW);
uvm_report_warning("MYWARN1", "This is a warning");
uvm_report_error("MYERR", "This is an error");
uvm_report_fatal("MYFATAL", "A fatal error has occurred");
The above code is replaced by
//New calls to `uvm_*
`uvm_info("MYINFO1", $sformatf("val: %0d", val), UVM_LOW)
`uvm_warning("MYWARN1", "This is a warning")
`uvm_error("MYERR", "This is an error")
`uvm_fatal("MYFATAL", "A fatal error has occurred")
Macros represent text substitutions, not statements, so they should not be terminated
with semi-colons.
Summary
Report Macros
This set of macros provides wrappers around the uvm_report_* Reporting
functions.
BAsIC MEssAGING MACrOs
`uvm_info
`uvm_warning
`uvm_error
`uvm_fatal
`uvm_info_context
UVM 1.2 Class Reference
Calls uvm_report_info if VERBOSITY is lower
than the configured verbosity of the
associated reporter.
Calls uvm_report_warning with a verbosity
of UVM_NONE.
Calls uvm_report_error with a verbosity of
UVM_NONE.
Calls uvm_report_fatal with a verbosity of
UVM_NONE.
437
`uvm_warning_context
`uvm_error_context
`uvm_fatal_context
MEssAGE TrACE MACrOs
`uvm_info_begin
`uvm_info_end
`uvm_warning_begin
`uvm_warning_end
`uvm_error_begin
`uvm_error_end
`uvm_fatal_begin
`uvm_fatal_end
`uvm_info_context_begin
`uvm_info_context_end
`uvm_warning_context_begin
`uvm_warning_context_end
`uvm_error_context_begin
`uvm_error_context_end
`uvm_fatal_context_begin
`uvm_fatal_context_end
MEssAGE ELEmENt MACrOs
`uvm_message_add_tag
`uvm_message_add_int
`uvm_message_add_string
`uvm_message_add_object
This macro pair provides the ability to add
elements to messages.
This macro pair operates identically to
`uvm_info_begin/`uvm_info_end with
exception that the message severity is
UVM_WARNING and has no verbosity
threshold.
This macro pair operates identically to
`uvm_info_begin/`uvm_info_end with
exception that the message severity is
UVM_ERROR and has no verbosity
threshold.
This macro pair operates identically to
`uvm_info_begin/`uvm_info_end with
exception that the message severity is
UVM_FATAL and has no verbosity threshold.
These macros allow the user to provide
elements that are associated with
uvm_report_messages.
BAsIC MEssAGING MACrOs
`uvm_info
Calls uvm_report_info if VERBOSITY is lower than the configured verbosity of the
associated reporter. ID is given as the message tag and MSG is given as the message
text. The file and line are also sent to the uvm_report_info call.
`uvm_info(ID, MSG, VERBOSITY)
`uvm_warning
Calls uvm_report_warning with a verbosity of UVM_NONE. The message cannot be
turned off using the reporter’s verbosity setting, but can be turned off by setting the
UVM 1.2 Class Reference
438
action for the message. ID is given as the message tag and MSG is given as the
message text. The file and line are also sent to the uvm_report_warning call.
`uvm_warning(ID, MSG)
`uvm_error
Calls uvm_report_error with a verbosity of UVM_NONE. The message cannot be turned
off using the reporter’s verbosity setting, but can be turned off by setting the action for
the message. ID is given as the message tag and MSG is given as the message text. The file and line are also sent to the uvm_report_error call.
`uvm_error(ID, MSG)
`uvm_fatal
Calls uvm_report_fatal with a verbosity of UVM_NONE. The message cannot be turned
off using the reporter’s verbosity setting, but can be turned off by setting the action for
the message. ID is given as the message tag and MSG is given as the message text. The file and line are also sent to the uvm_report_fatal call.
`uvm_fatal(ID, MSG)
`uvm_info_context
`uvm_info_context(ID, MSG, VERBOSITY, RO)
Operates identically to `uvm_info but requires that the context, or uvm_report_object, in
which the message is printed be explicitly supplied as a macro argument.
`uvm_warning_context
`uvm_warning_context(ID, MSG, RO)
Operates identically to `uvm_warning but requires that the context, or
uvm_report_object, in which the message is printed be explicitly supplied as a macro
argument.
UVM 1.2 Class Reference
439
`uvm_error_context
`uvm_error_context(ID, MSG, RO)
Operates identically to `uvm_error but requires that the context, or uvm_report_object
in which the message is printed be explicitly supplied as a macro argument.
`uvm_fatal_context
`uvm_fatal_context(ID, MSG, RO)
Operates identically to `uvm_fatal but requires that the context, or uvm_report_object,
in which the message is printed be explicitly supplied as a macro argument.
MEssAGE TrACE MACrOs
`uvm_info_begin
`uvm_info_begin(ID, MSG, VERBOSITY, RM = __uvm_msg)
`uvm_info_end
This macro pair provides the ability to add elements to messages.
`uvm_info_end
Example usage is shown here.
...
task my_task();
...
`uvm_info_begin("MY_ID", "This is my message...", UVM_LOW)
`uvm_message_add_tag("my_color", "red")
`uvm_message_add_int(my_int, UVM_DEC)
`uvm_message_add_string(my_string)
`uvm_message_add_object(my_obj)
`uvm_info_end
...
endtask
UVM 1.2 Class Reference
440
`uvm_warning_begin
`uvm_warning_begin(ID, MSG, RM = __uvm_msg)
`uvm_warning_end
This macro pair operates identically to `uvm_info_begin/`uvm_info_end with exception
that the message severity is UVM_WARNING and has no verbosity threshold.
`uvm_warning_end
The usage shown in `uvm_info_end works identically for this pair.
`uvm_error_begin
`uvm_error_begin(ID, MSG, RM = __uvm_msg)
`uvm_error_end
This macro pair operates identically to `uvm_info_begin/`uvm_info_end with exception
that the message severity is UVM_ERROR and has no verbosity threshold.
`uvm_error_end
The usage shown in `uvm_info_end works identically for this pair.
`uvm_fatal_begin
`uvm_fatal_begin(ID, MSG, RM = __uvm_msg)
`uvm_fatal_end
This macro pair operates identically to `uvm_info_begin/`uvm_info_end with exception
that the message severity is UVM_FATAL and has no verbosity threshold.
`uvm_fatal_end
UVM 1.2 Class Reference
441
The usage shown in `uvm_info_end works identically for this pair.
`uvm_info_context_begin
`uvm_info_context_begin(ID, MSG, UVM_NONE, RO, RM = __uvm_msg)
`uvm_info_context_end
`uvm_info_context_end
This macro pair operates identically to `uvm_info_begin/`uvm_info_end, but requires
that the context, or uvm_report_object in which the message is printed be explicitly
supplied as a macro argument.
`uvm_warning_context_begin
`uvm_warning_context_begin(ID, MSG, RO, RM = __uvm_msg)
`uvm_warning_context_end
`uvm_warning_context_end
This macro pair operates identically to `uvm_warning_begin/`uvm_warning_end, but
requires that the context, or uvm_report_object in which the message is printed be
explicitly supplied as a macro argument.
`uvm_error_context_begin
`uvm_error_context_begin(ID, MSG, RO, RM = __uvm_msg)
`uvm_error_context_end
UVM 1.2 Class Reference
442
`uvm_error_context_end
This macro pair operates identically to `uvm_error_begin/`uvm_error_end, but requires
that the context, or uvm_report_object in which the message is printed be explicitly
supplied as a macro argument.
`uvm_fatal_context_begin
`uvm_fatal_context_begin(ID, MSG, RO, RM = __uvm_msg)
`uvm_fatal_context_end
`uvm_fatal_context_end
This macro pair operates identically to `uvm_fatal_begin/`uvm_fatal_end, but requires
that the context, or uvm_report_object in which the message is printed be explicitly
supplied as a macro argument.
MEssAGE ELEmENt MACrOs
`uvm_message_add_tag
`uvm_message_add_tag(NAME, VALUE, ACTION=(UVM_LOG|UVM_RM_RECORD))
`uvm_message_add_int
`uvm_message_add_int(VAR, RADIX, LABEL = "", ACTION=(UVM_LOG|UVM_RM_RECORD))
`uvm_message_add_string
`uvm_message_add_string(VAR, LABEL = "", ACTION=(UVM_LOG|UVM_RM_RECORD))
UVM 1.2 Class Reference
443
`uvm_message_add_object
These macros allow the user to provide elements that are associated with
uvm_report_messages. Separate macros are provided such that the user can supply
arbitrary string/string pairs using `uvm_message_add_tag, integral types along with a
radix using `uvm_message_add_int, string using `uvm_message_add_string and
uvm_objects using `uvm_message_add_object.
`uvm_message_add_object(VAR, LABEL = "", ACTION=(UVM_LOG|UVM_RM_RECORD))
Example usage is shown in `uvm_info_end.
UVM 1.2 Class Reference
444
21.2 Utility and Field Macros for Components and
Objects
Summary
Utility and Field Macros for Components and Objects
UTILITY MAcRos
The utils macros define the
infrastructure needed to enable the
object/component for correct factory
operation.
`uvm_field_utils_begin
`uvm_field_utils_end
`uvm_object_utils
`uvm_object_param_utils
`uvm_object_utils_begin
`uvm_object_param_utils_begin
`uvm_object_utils_end
`uvm_component_utils
`uvm_component_param_utils
`uvm_component_utils_begin
`uvm_component_param_utils_begin
`uvm_component_end
`uvm_object_registry
`uvm_component_registry
FIELD MAcRos
`uVm_fIELD_*
uvm_object-based class declarations
may contain one of the above forms
of utility macros.
uvm_component-based class
declarations may contain one of the
above forms of utility macros.
Register a uvm_object-based class
with the factory
Registers a uvm_component-based
class with the factory
The `uvm_field_* macros are invoked
inside of the `uvm_*_utils_begin and
`uvm_*_utils_end macro blocks to
form “automatic” implementations of
the core data methods: copy,
compare, pack, unpack, record, print,
and sprint.
Macros that implement data
operations for scalar properties.
Implements the data operations
any packed integral property.
Implements the data operations
a uvm_object-based property.
Implements the data operations
a string property.
Implements the data operations
an enumerated property.
Implements the data operations
any real property.
Implements the data operations
an event property.
mAcRos
`uvm_field_int
`uvm_field_object
`uvm_field_string
`uvm_field_enum
`uvm_field_real
`uvm_field_event
`uVm_fIELD_sARRAY_*
mAcRos
`uvm_field_sarray_int
`uvm_field_sarray_object
UVM 1.2 Class Reference
These macros form a block in which
`uvm_field_* macros can be placed.
for
for
for
for
for
for
Macros that implement data
operations for one-dimensional static
array properties.
Implements the data operations for
a one-dimensional static array of
integrals.
Implements the data operations for
445
`uvm_field_sarray_string
`uvm_field_sarray_enum
`uVm_fIELD_ARRAY_*
mAcRos
`uvm_field_array_int
`uvm_field_array_object
`uvm_field_array_string
`uvm_field_array_enum
`uVm_fIELD_QuEuE_*
mAcRos
`uvm_field_queue_int
`uvm_field_queue_object
`uvm_field_queue_string
`uvm_field_queue_enum
`uVm_fIELD_AA_*_sTRING
mAcRos
`uvm_field_aa_int_string
`uvm_field_aa_object_string
`uvm_field_aa_string_string
`uVm_fIELD_AA_*_INT
mAcRos
`uvm_field_aa_object_int
`uvm_field_aa_int_int
`uvm_field_aa_int_int_unsigned
`uvm_field_aa_int_integer
`uvm_field_aa_int_integer_unsigned
UVM 1.2 Class Reference
a one-dimensional static array of
uvm_object-based objects.
Implements the data operations for
a one-dimensional static array of
strings.
Implements the data operations for
a one-dimensional static array of
enums.
Macros that implement data
operations for one-dimensional
dynamic array properties.
Implements the data operations for
a one-dimensional dynamic array of
integrals.
Implements the data operations for
a one-dimensional dynamic array of
uvm_object-based objects.
Implements the data operations for
a one-dimensional dynamic array of
strings.
Implements the data operations for
a one-dimensional dynamic array of
enums.
Macros that implement data
operations for dynamic queues.
Implements the data operations for
a queue of integrals.
Implements the data operations for
a queue of uvm_object-based
objects.
Implements the data operations for
a queue of strings.
Implements the data operations for
a one-dimensional queue of enums.
Macros that implement data
operations for associative arrays
indexed by string.
Implements the data operations for
an associative array of integrals
indexed by string.
Implements the data operations for
an associative array of uvm_objectbased objects indexed by string.
Implements the data operations for
an associative array of strings
indexed by string.
Macros that implement data
operations for associative arrays
indexed by an integral type.
Implements the data operations for
an associative array of uvm_objectbased objects indexed by the int
data type.
Implements the data operations for
an associative array of integral types
indexed by the int data type.
Implements the data operations for
an associative array of integral types
indexed by the int unsigned data
type.
Implements the data operations for
an associative array of integral types
indexed by the integer data type.
Implements the data operations for
an associative array of integral types
indexed by the integer unsigned
446
`uvm_field_aa_int_byte
`uvm_field_aa_int_byte_unsigned
`uvm_field_aa_int_shortint
`uvm_field_aa_int_shortint_unsigned
`uvm_field_aa_int_longint
`uvm_field_aa_int_longint_unsigned
`uvm_field_aa_int_key
`uvm_field_aa_int_enumkey
REcoRDING MAcRos
`uvm_record_attribute
`uvm_record_int
`uvm_record_string
`uvm_record_time
`uvm_record_real
`uvm_record_field
PAcKING MAcRos
PAcKING - WITH SIZE INfo
`uvm_pack_intN
`uvm_pack_enumN
`uvm_pack_sarrayN
`uvm_pack_arrayN
`uvm_pack_queueN
PAcKING - No SIZE INfo
`uvm_pack_int
`uvm_pack_enum
`uvm_pack_string
`uvm_pack_real
`uvm_pack_sarray
`uvm_pack_array
`uvm_pack_queue
UVM 1.2 Class Reference
data type.
Implements the data operations for
an associative array of integral types
indexed by the byte data type.
Implements the data operations for
an associative array of integral types
indexed by the byte unsigned data
type.
Implements the data operations for
an associative array of integral types
indexed by the shortint data type.
Implements the data operations for
an associative array of integral types
indexed by the shortint unsigned
data type.
Implements the data operations for
an associative array of integral types
indexed by the longint data type.
Implements the data operations for
an associative array of integral types
indexed by the longint unsigned data
type.
Implements the data operations for
an associative array of integral types
indexed by any integral key data
type.
Implements the data operations for
an associative array of integral types
indexed by any enumeration key
data type.
The recording macros assist users who
implement the uvm_object::do_record
method.
Vendor-independent macro to hide
tool-specific interface for recording
attributes (fields) to a transaction
database.
Macro for recording arbitrary namevalue pairs into a transaction
recording database.
The packing macros assist users who
implement the uvm_object::do_pack
method.
Pack
Pack
Pack
Pack
Pack
an integral variable.
an integral variable.
a static array of integrals.
a dynamic array of integrals.
a queue of integrals.
Pack an integral variable without
having to also specify the bit size.
Pack an enumeration value.
Pack a string variable.
Pack a variable of type real.
Pack a static array without having to
also specify the bit size of its
elements.
Pack a dynamic array without having
to also specify the bit size of its
elements.
Pack a queue without having to also
447
specify the bit size of its elements.
UNpAcKING MAcRos
UNpAcKING - WITH SIZE INfo
`uvm_unpack_intN
`uvm_unpack_enumN
`uvm_unpack_sarrayN
`uvm_unpack_arrayN
`uvm_unpack_queueN
UNpAcKING - No SIZE INfo
`uvm_unpack_int
`uvm_unpack_enum
`uvm_unpack_string
`uvm_unpack_real
`uvm_unpack_sarray
`uvm_unpack_array
`uvm_unpack_queue
The unpacking macros assist users
who implement the
uvm_object::do_unpack method.
Unpack into an integral variable.
Unpack enum of type TYPE into VAR.
Unpack a static (fixed) array of
integrals.
Unpack into a dynamic array of
integrals.
Unpack into a queue of integrals.
Unpack an integral variable without
having to also specify the bit size.
Unpack an enumeration value, which
requires its type be specified.
Unpack a string variable.
Unpack a variable of type real.
Unpack a static array without having
to also specify the bit size of its
elements.
Unpack a dynamic array without
having to also specify the bit size of
its elements.
Unpack a queue without having to
also specify the bit size of its
elements.
UTILITY MAcRos
The utils macros define the infrastructure needed to enable the object/component for
correct factory operation. See `uvm_object_utils and `uvm_component_utils for details.
A utils macro should be used inside every user-defined class that extends uvm_object
directly or indirectly, including uvm_sequence_item and uvm_component.
Below is an example usage of the utils macro for a user-defined object.
class mydata extends uvm_object;
`uvm_object_utils(mydata)
// declare data properties
function new(string name="mydata_inst");
super.new(name);
endfunction
endclass
Below is an example usage of a utils macro for a user-defined component.
class my_comp extends uvm_component;
`uvm_component_utils(my_comp)
// declare data properties
function new(string name, uvm_component parent=null);
super.new(name,parent);
endfunction
UVM 1.2 Class Reference
448
endclass
`uvm_field_utils_begin
`uvm_field_utils_end
These macros form a block in which `uvm_field_* macros can be placed. Used as
`uvm_field_utils_begin(TYPE)
`uvm_field_* macros here
`uvm_field_utils_end
These macros do not perform factory registration nor implement the get_type_name and
create methods. Use this form when you need custom implementations of these two
methods, or when you are setting up field macros for an abstract class (i.e. virtual
class).
`uvm_object_utils
`uvm_object_param_utils
`uvm_object_utils_begin
`uvm_object_param_utils_begin
`uvm_object_utils_end
uvm_object-based class declarations may contain one of the above forms of utility
macros.
For simple objects with no field macros, use
`uvm_object_utils(TYPE)
For simple objects with field macros, use
`uvm_object_utils_begin(TYPE)
`uvm_field_* macro invocations here
`uvm_object_utils_end
UVM 1.2 Class Reference
449
For parameterized objects with no field macros, use
`uvm_object_param_utils(TYPE)
For parameterized objects, with field macros, use
`uvm_object_param_utils_begin(TYPE)
`uvm_field_* macro invocations here
`uvm_object_utils_end
Simple (non-parameterized) objects use the uvm_object_utils* versions, which do the
following:
Implements get_type_name, which returns TYPE as a string
Implements create, which allocates an object of type TYPE by calling its
constructor with no arguments. TYPE’s constructor, if defined, must have default
values on all it arguments.
Registers the TYPE with the factory, using the string TYPE as the factory lookup
string for the type.
Implements the static get_type() method which returns a factory proxy object for
the type.
Implements the virtual get_object_type() method which works just like the static
get_type() method, but operates on an already allocated object.
Parameterized classes must use the uvm_object_param_utils* versions. They differ from
`uvm_object_utils only in that they do not supply a type name when registering the
object with the factory. As such, name-based lookup with the factory for parameterized
classes is not possible.
The macros with _begin suffixes are the same as the non-suffixed versions except that
they also start a block in which `uvm_field_* macros can be placed. The block must be
terminated by `uvm_object_utils_end.
`uvm_component_utils
`uvm_component_param_utils
`uvm_component_utils_begin
`uvm_component_param_utils_begin
`uvm_component_end
uvm_component-based class declarations may contain one of the above forms of utility
macros.
For simple components with no field macros, use
UVM 1.2 Class Reference
450
`uvm_component_utils(TYPE)
For simple components with field macros, use
`uvm_component_utils_begin(TYPE)
`uvm_field_* macro invocations here
`uvm_component_utils_end
For parameterized components with no field macros, use
`uvm_component_param_utils(TYPE)
For parameterized components with field macros, use
`uvm_component_param_utils_begin(TYPE)
`uvm_field_* macro invocations here
`uvm_component_utils_end
Simple (non-parameterized) components must use the uvm_components_utils* versions,
which do the following:
Implements get_type_name, which returns TYPE as a string.
Implements create, which allocates a component of type TYPE using a two
argument constructor. TYPE’s constructor must have a name and a parent
argument.
Registers the TYPE with the factory, using the string TYPE as the factory lookup
string for the type.
Implements the static get_type() method which returns a factory proxy object for
the type.
Implements the virtual get_object_type() method which works just like the static
get_type() method, but operates on an already allocated object.
Parameterized classes must use the uvm_object_param_utils* versions. They differ from
`uvm_object_utils only in that they do not supply a type name when registering the
object with the factory. As such, name-based lookup with the factory for parameterized
classes is not possible.
The macros with _begin suffixes are the same as the non-suffixed versions except that
they also start a block in which `uvm_field_* macros can be placed. The block must be
terminated by `uvm_component_utils_end.
`uvm_object_registry
Register a uvm_object-based class with the factory
`uvm_object_registry(T,S)
UVM 1.2 Class Reference
451
Registers a uvm_object-based class T and lookup string S with the factory. S typically is
the name of the class in quotes. The `uvm_object_utils family of macros uses this
macro.
`uvm_component_registry
Registers a uvm_component-based class with the factory
`uvm_component_registry(T,S)
Registers a uvm_component-based class T and lookup string S with the factory. S
typically is the name of the class in quotes. The `uvm_object_utils family of macros
uses this macro.
FIELD MAcRos
The `uvm_field_* macros are invoked inside of the `uvm_*_utils_begin and
`uvm_*_utils_end macro blocks to form “automatic” implementations of the core data
methods: copy, compare, pack, unpack, record, print, and sprint.
By using the macros, you do not have to implement any of the do_* methods inherited
from uvm_object. However, be aware that the field macros expand into general inline
code that is not as run-time efficient nor as flexible as direct implementations of the
do_* methods.
Below is an example usage of the field macros for a sequence item.
class my_trans extends uvm_sequence_item;
cmd_t
int
int
my_ext
string
cmd;
addr;
data[$];
ext;
str;
`uvm_object_utils_begin(my_trans)
`uvm_field_enum
(cmd_t, cmd, UVM_ALL_ON)
`uvm_field_int
(addr, UVM_ALL_ON)
`uvm_field_queue_int(data, UVM_ALL_ON)
`uvm_field_object
(ext, UVM_ALL_ON)
`uvm_field_string
(str, UVM_ALL_ON)
`uvm_object_utils_end
function new(string name="mydata_inst");
super.new(name);
endfunction
endclass
Below is an example usage of the field macros for a component.
class my_comp extends uvm_component;
my_comp_cfg
cfg;
`uvm_component_utils_begin(my_comp)
`uvm_field_object
(cfg, UVM_ALL_ON)
`uvm_object_utils_end
function new(string name="my_comp_inst", uvm_component parent=null);
super.new(name);
UVM 1.2 Class Reference
452
endfunction
endclass
Each `uvm_field_* macro is named according to the particular data type it handles:
integrals, strings, objects, queues, etc., and each has at least two arguments: ARG and
FLAG.
ARG
is the instance name of the variable, whose type must be compatible
with the macro being invoked. In the example, class variable addr is
an integral type, so we use the `uvm_field_int macro.
FLAG
if set to UVM_ALL_ON, as in the example, the ARG variable will be
included in all data methods. If FLAG is set to something other than
UVM_ALL_ON or UVM_DEFAULT, it specifies which data method
implementations will not include the given variable. Thus, if FLAG is
specified as NO_COMPARE, the ARG variable will not affect comparison
operations, but it will be included in everything else.
All possible values for FLAG are listed and described below. Multiple flag values can be
bitwise OR’ed together (in most cases they may be added together as well, but care must
be taken when using the + operator to ensure that the same bit is not added more than
once).
UVM_ALL_ON
Set all operations on.
UVM_DEFAULT
This is the recommended set of flags to pass to the field
macros. Currently, it enables all of the operations,
making it functionally identical to UVM_ALL_ON. In the
future however, additional flags could be added with a
recommended default value of off.
UVM_NOCOPY
Do not copy this field.
UVM_NOCOMPARE
Do not compare this field.
UVM_NOPRINT
Do not print this field.
UVM_NOPACK
Do not pack or unpack this field.
UVM_REFERENCE
For object types, operate only on the handle (e.g. no
deep copy)
UVM_PHYSICAL
Treat as a physical field. Use physical setting in policy
class for this field.
UVM_ABSTRACT
Treat as an abstract field. Use the abstract setting in the
policy class for this field.
UVM_READONLY
Do not allow setting of this field from the set_*_local
methods or during uvm_component::apply_config_settings
operation.
A radix for printing and recording can be specified by OR’ing one of the following
constants in the FLAG argument
UVM_BIN
Print / record the field in binary (base-2).
UVM_DEC
Print / record the field in decimal (base-10).
UVM_UNSIGNED
Print / record the field in unsigned decimal (base-10).
UVM_OCT
Print / record the field in octal (base-8).
UVM_HEX
Print / record the field in hexadecimal (base-16).
UVM_STRING
Print / record the field in string format.
UVM_TIME
Print / record the field in time format.
UVM 1.2 Class Reference
453
Radix settings for integral types. Hex is the default radix if none is specified.
A UVM component should not be specified using the `uvm_field_object macro unless its
flag includes UVM_REFERENCE. Otherwise, the field macro will implement deep copy,
which is an illegal operation for uvm_components. You will get a FATAL error if you tried
to copy or clone an object containing a component handle that was registered with a
field macro without the UVM_REFERENCE flag. You will also get duplicate entries when
printing component topology, as this functionality is already provided by UVM.
`uVm_fIELD_*
mAcRos
Macros that implement data operations for scalar properties.
`uvm_field_int
Implements the data operations for any packed integral property.
`uvm_field_int(ARG,FLAG)
ARG is an integral property of the class, and FLAG is a bitwise OR of one or more flag
settings as described in Field Macros above.
`uvm_field_object
Implements the data operations for a uvm_object-based property.
`uvm_field_object(ARG,FLAG)
ARG is an object property of the class, and FLAG is a bitwise OR of one or more flag
settings as described in Field Macros above.
`uvm_field_string
Implements the data operations for a string property.
`uvm_field_string(ARG,FLAG)
ARG is a string property of the class, and FLAG is a bitwise OR of one or more flag
settings as described in Field Macros above.
`uvm_field_enum
Implements the data operations for an enumerated property.
UVM 1.2 Class Reference
454
`uvm_field_enum(T,ARG,FLAG)
T is an enumerated type, ARG is an instance of that type, and FLAG is a bitwise OR of
one or more flag settings as described in Field Macros above.
`uvm_field_real
Implements the data operations for any real property.
`uvm_field_real(ARG,FLAG)
ARG is an real property of the class, and FLAG is a bitwise OR of one or more flag
settings as described in Field Macros above.
`uvm_field_event
Implements the data operations for an event property.
`uvm_field_event(ARG,FLAG)
ARG is an event property of the class, and FLAG is a bitwise OR of one or more flag
settings as described in Field Macros above.
`uVm_fIELD_sARRAY_*
mAcRos
Macros that implement data operations for one-dimensional static array properties.
`uvm_field_sarray_int
Implements the data operations for a one-dimensional static array of integrals.
`uvm_field_sarray_int(ARG,FLAG)
ARG is a one-dimensional static array of integrals, and FLAG is a bitwise OR of one or
more flag settings as described in Field Macros above.
`uvm_field_sarray_object
Implements the data operations for a one-dimensional static array of uvm_object-based
objects.
UVM 1.2 Class Reference
455
`uvm_field_sarray_object(ARG,FLAG)
ARG is a one-dimensional static array of uvm_object-based objects, and FLAG is a
bitwise OR of one or more flag settings as described in Field Macros above.
`uvm_field_sarray_string
Implements the data operations for a one-dimensional static array of strings.
`uvm_field_sarray_string(ARG,FLAG)
ARG is a one-dimensional static array of strings, and FLAG is a bitwise OR of one or
more flag settings as described in Field Macros above.
`uvm_field_sarray_enum
Implements the data operations for a one-dimensional static array of enums.
`uvm_field_sarray_enum(T,ARG,FLAG)
T is a one-dimensional dynamic array of enums type, ARG is an instance of that type,
and FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uVm_fIELD_ARRAY_*
mAcRos
Macros that implement data operations for one-dimensional dynamic array properties.
Implementation note
lines flagged with empty multi-line comments, /**/, are not needed or need to be
different for fixed arrays, which cannot be resized. Fixed arrays do not need to
pack/unpack their size either, because their size is known; wouldn’t hurt though if it
allowed code consolidation. Unpacking would necessarily be different. */
`uvm_field_array_int
Implements the data operations for a one-dimensional dynamic array of integrals.
`uvm_field_array_int(ARG,FLAG)
ARG is a one-dimensional dynamic array of integrals, and FLAG is a bitwise OR of one or
more flag settings as described in Field Macros above.
UVM 1.2 Class Reference
456
`uvm_field_array_object
Implements the data operations for a one-dimensional dynamic array of uvm_objectbased objects.
`uvm_field_array_object(ARG,FLAG)
ARG is a one-dimensional dynamic array of uvm_object-based objects, and FLAG is a
bitwise OR of one or more flag settings as described in Field Macros above.
`uvm_field_array_string
Implements the data operations for a one-dimensional dynamic array of strings.
`uvm_field_array_string(ARG,FLAG)
ARG is a one-dimensional dynamic array of strings, and FLAG is a bitwise OR of one or
more flag settings as described in Field Macros above.
`uvm_field_array_enum
Implements the data operations for a one-dimensional dynamic array of enums.
`uvm_field_array_enum(T,ARG,FLAG)
T is a one-dimensional dynamic array of enums type, ARG is an instance of that type,
and FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uVm_fIELD_QuEuE_*
mAcRos
Macros that implement data operations for dynamic queues.
`uvm_field_queue_int
Implements the data operations for a queue of integrals.
`uvm_field_queue_int(ARG,FLAG)
ARG is a one-dimensional queue of integrals, and FLAG is a bitwise OR of one or more
flag settings as described in Field Macros above.
UVM 1.2 Class Reference
457
`uvm_field_queue_object
Implements the data operations for a queue of uvm_object-based objects.
`uvm_field_queue_object(ARG,FLAG)
ARG is a one-dimensional queue of uvm_object-based objects, and FLAG is a bitwise OR
of one or more flag settings as described in Field Macros above.
`uvm_field_queue_string
Implements the data operations for a queue of strings.
`uvm_field_queue_string(ARG,FLAG)
ARG is a one-dimensional queue of strings, and FLAG is a bitwise OR of one or more flag
settings as described in Field Macros above.
`uvm_field_queue_enum
Implements the data operations for a one-dimensional queue of enums.
`uvm_field_queue_enum(T,ARG,FLAG)
T is a queue of enums type, ARG is an instance of that type, and FLAG is a bitwise OR of
one or more flag settings as described in Field Macros above.
`uVm_fIELD_AA_*_sTRING
mAcRos
Macros that implement data operations for associative arrays indexed by string.
`uvm_field_aa_int_string
Implements the data operations for an associative array of integrals indexed by string.
`uvm_field_aa_int_string(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with string key,
and FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uvm_field_aa_object_string
UVM 1.2 Class Reference
458
Implements the data operations for an associative array of uvm_object-based objects
indexed by string.
`uvm_field_aa_object_string(ARG,FLAG)
ARG is the name of a property that is an associative array of objects with string key, and
FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uvm_field_aa_string_string
Implements the data operations for an associative array of strings indexed by string.
`uvm_field_aa_string_string(ARG,FLAG)
ARG is the name of a property that is an associative array of strings with string key, and
FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uVm_fIELD_AA_*_INT
mAcRos
Macros that implement data operations for associative arrays indexed by an integral
type.
`uvm_field_aa_object_int
Implements the data operations for an associative array of uvm_object-based objects
indexed by the int data type.
`uvm_field_aa_object_int(ARG,FLAG)
ARG is the name of a property that is an associative array of objects with int key, and
FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uvm_field_aa_int_int
Implements the data operations for an associative array of integral types indexed by the
int data type.
`uvm_field_aa_int_int(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with int key, and
FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
UVM 1.2 Class Reference
459
`uvm_field_aa_int_int_unsigned
Implements the data operations for an associative array of integral types indexed by the
int unsigned data type.
`uvm_field_aa_int_int_unsigned(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with int unsigned
key, and FLAG is a bitwise OR of one or more flag settings as described in Field Macros
above.
`uvm_field_aa_int_integer
Implements the data operations for an associative array of integral types indexed by the
integer data type.
`uvm_field_aa_int_integer(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with integer key,
and FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uvm_field_aa_int_integer_unsigned
Implements the data operations for an associative array of integral types indexed by the
integer unsigned data type.
`uvm_field_aa_int_integer_unsigned(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with integer
unsigned key, and FLAG is a bitwise OR of one or more flag settings as described in Field
Macros above.
`uvm_field_aa_int_byte
Implements the data operations for an associative array of integral types indexed by the
byte data type.
`uvm_field_aa_int_byte(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with byte key, and
FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uvm_field_aa_int_byte_unsigned
UVM 1.2 Class Reference
460
Implements the data operations for an associative array of integral types indexed by the
byte unsigned data type.
`uvm_field_aa_int_byte_unsigned(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with byte
unsigned key, and FLAG is a bitwise OR of one or more flag settings as described in Field
Macros above.
`uvm_field_aa_int_shortint
Implements the data operations for an associative array of integral types indexed by the
shortint data type.
`uvm_field_aa_int_shortint(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with shortint key,
and FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uvm_field_aa_int_shortint_unsigned
Implements the data operations for an associative array of integral types indexed by the
shortint unsigned data type.
`uvm_field_aa_int_shortint_unsigned(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with shortint
unsigned key, and FLAG is a bitwise OR of one or more flag settings as described in Field
Macros above.
`uvm_field_aa_int_longint
Implements the data operations for an associative array of integral types indexed by the
longint data type.
`uvm_field_aa_int_longint(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with longint key,
and FLAG is a bitwise OR of one or more flag settings as described in Field Macros above.
`uvm_field_aa_int_longint_unsigned
Implements the data operations for an associative array of integral types indexed by the
longint unsigned data type.
UVM 1.2 Class Reference
461
`uvm_field_aa_int_longint_unsigned(ARG,FLAG)
ARG is the name of a property that is an associative array of integrals with longint
unsigned key, and FLAG is a bitwise OR of one or more flag settings as described in Field
Macros above.
`uvm_field_aa_int_key
Implements the data operations for an associative array of integral types indexed by any
integral key data type.
`uvm_field_aa_int_key(KEY,ARG,FLAG)
KEY is the data type of the integral key, ARG is the name of a property that is an
associative array of integrals, and FLAG is a bitwise OR of one or more flag settings as
described in Field Macros above.
`uvm_field_aa_int_enumkey
Implements the data operations for an associative array of integral types indexed by any
enumeration key data type.
`uvm_field_aa_int_enumkey(KEY, ARG,FLAG)
KEY is the enumeration type of the key, ARG is the name of a property that is an
associative array of integrals, and FLAG is a bitwise OR of one or more flag settings as
described in Field Macros above.
REcoRDING MAcRos
The recording macros assist users who implement the uvm_object::do_record method. They help ensure that the fields are recorded using a vendor- independent API. Unlike
the uvm_recorder policy, fields recorded using the macros do not lose type information-they are passed directly to the vendor-specific API. This results in more efficient
recording and no artificial limit on bit-widths. See your simulator vendor’s
documentation for more information on its transaction recording capabilities.
`uvm_record_attribute
Vendor-independent macro to hide tool-specific interface for recording attributes (fields)
to a transaction database.
`uvm_record_attribute(TR_HANDLE, NAME, VALUE)
UVM 1.2 Class Reference
462
The default implementation of the macro passes NAME and VALUE through to the
uvm_recorder::record_generic method.
This macro should not be called directly by the user, the other recording macros will call
it automatically if uvm_recorder::use_record_attribute returns true.
`uvm_record_int
`uvm_record_int(NAME,VALUE,SIZE[,RADIX])
The `uvm_record_int macro takes the same arguments as the
uvm_recorder::record_field method (including the optional RADIX).
The default implementation will pass the name/value pair to `uvm_record_attribute if
enabled, otherwise the information will be passed to uvm_recorder::record_field.
`uvm_record_string
`uvm_record_string(NAME,VALUE)
The `uvm_record_string macro takes the same arguments as the
uvm_recorder::record_string method.
The default implementation will pass the name/value pair to `uvm_record_attribute if
enabled, otherwise the information will be passed to uvm_recorder::record_string.
`uvm_record_time
`uvm_record_time(NAME,VALUE)
The `uvm_record_time macro takes the same arguments as the
uvm_recorder::record_time method.
The default implementation will pass the name/value pair to `uvm_record_attribute if
enabled, otherwise the information will be passed to uvm_recorder::record_time.
`uvm_record_real
`uvm_record_real(NAME,VALUE)
UVM 1.2 Class Reference
463
The `uvm_record_real macro takes the same arguments as the
uvm_recorder::record_field_real method.
The default implementation will pass the name/value pair to `uvm_record_attribute if
enabled, otherwise the information will be passed to uvm_recorder::record_field_real.
`uvm_record_field
Macro for recording arbitrary name-value pairs into a transaction recording database. Requires a valid transaction handle, as provided by the uvm_transaction::begin_tr and
uvm_component::begin_tr methods.
`uvm_record_field(NAME, VALUE)
The default implementation will pass the name/value pair to `uvm_record_attribute if
enabled, otherwise the information will be passed to uvm_recorder::record_generic, with
the VALUE being converted to a string using “%p” notation.
recorder.record_generic(NAME,$sformatf("%p",VALUE));
PAcKING MAcRos
The packing macros assist users who implement the uvm_object::do_pack method. They
help ensure that the pack operation is the exact inverse of the unpack operation. See
also Unpacking Macros.
virtual function void do_pack(uvm_packer packer);
`uvm_pack_int(cmd)
`uvm_pack_int(addr)
`uvm_pack_array(data)
endfunction
The ‘N’ versions of these macros take an explicit size argument, which must be compiletime constant value greater than 0.
PAcKING - WITH SIZE INfo
`uvm_pack_intN
Pack an integral variable.
`uvm_pack_intN(VAR,SIZE)
UVM 1.2 Class Reference
464
`uvm_pack_enumN
Pack an integral variable.
`uvm_pack_enumN(VAR,SIZE)
`uvm_pack_sarrayN
Pack a static array of integrals.
`uvm_pack_sarray(VAR,SIZE)
`uvm_pack_arrayN
Pack a dynamic array of integrals.
`uvm_pack_arrayN(VAR,SIZE)
`uvm_pack_queueN
Pack a queue of integrals.
`uvm_pack_queueN(VAR,SIZE)
PAcKING - No SIZE INfo
`uvm_pack_int
Pack an integral variable without having to also specify the bit size.
`uvm_pack_int(VAR)
`uvm_pack_enum
Pack an enumeration value. Packing does not require its type be specified.
UVM 1.2 Class Reference
465
`uvm_pack_enum(VAR)
`uvm_pack_string
Pack a string variable.
`uvm_pack_string(VAR)
`uvm_pack_real
Pack a variable of type real.
`uvm_pack_real(VAR)
`uvm_pack_sarray
Pack a static array without having to also specify the bit size of its elements.
`uvm_pack_sarray(VAR)
`uvm_pack_array
Pack a dynamic array without having to also specify the bit size of its elements. Array
size must be non-zero.
`uvm_pack_array(VAR)
`uvm_pack_queue
Pack a queue without having to also specify the bit size of its elements. Queue must not
be empty.
`uvm_pack_queue(VAR)
UVM 1.2 Class Reference
466
UNpAcKING MAcRos
The unpacking macros assist users who implement the uvm_object::do_unpack method. They help ensure that the unpack operation is the exact inverse of the pack operation. See also Packing Macros.
virtual function void do_unpack(uvm_packer packer);
`uvm_unpack_enum(cmd,cmd_t)
`uvm_unpack_int(addr)
`uvm_unpack_array(data)
endfunction
The ‘N’ versions of these macros take an explicit size argument, which must be a compiletime constant value greater than 0.
UNpAcKING - WITH SIZE INfo
`uvm_unpack_intN
Unpack into an integral variable.
`uvm_unpack_intN(VAR,SIZE)
`uvm_unpack_enumN
Unpack enum of type TYPE into VAR.
`uvm_unpack_enumN(VAR,SIZE,TYPE)
`uvm_unpack_sarrayN
Unpack a static (fixed) array of integrals.
`uvm_unpack_sarrayN(VAR,SIZE)
`uvm_unpack_arrayN
Unpack into a dynamic array of integrals.
`uvm_unpack_arrayN(VAR,SIZE)
UVM 1.2 Class Reference
467
`uvm_unpack_queueN
Unpack into a queue of integrals.
`uvm_unpack_queue(VAR,SIZE)
UNpAcKING - No SIZE INfo
`uvm_unpack_int
Unpack an integral variable without having to also specify the bit size.
`uvm_unpack_int(VAR)
`uvm_unpack_enum
Unpack an enumeration value, which requires its type be specified.
`uvm_unpack_enum(VAR,TYPE)
`uvm_unpack_string
Unpack a string variable.
`uvm_unpack_string(VAR)
`uvm_unpack_real
Unpack a variable of type real.
`uvm_unpack_real(VAR)
`uvm_unpack_sarray
Unpack a static array without having to also specify the bit size of its elements.
UVM 1.2 Class Reference
468
`uvm_unpack_sarray(VAR)
`uvm_unpack_array
Unpack a dynamic array without having to also specify the bit size of its elements. Array
size must be non-zero.
`uvm_unpack_array(VAR)
`uvm_unpack_queue
Unpack a queue without having to also specify the bit size of its elements. Queue must
not be empty.
`uvm_unpack_queue(VAR)
UVM 1.2 Class Reference
469
21.3 Sequence-Related Macros
Summary
Sequence-Related Macros
SEQUENCE ACTION MaCrOs
These macros are used to start sequences
and sequence items on the default
sequencer, m_sequencer.
`uvm_create
`uvm_do
`uvm_do_pri
`uvm_do_with
`uvm_do_pri_with
SEQUENCE
MaCrOs
ON
SEQUENCEr ACTION
These macros are used to start sequences
and sequence items on a specific
sequencer.
`uvm_create_on
`uvm_do_on
`uvm_do_on_pri
`uvm_do_on_with
`uvm_do_on_pri_with
SEQUENCE ACTION MaCrOs
EXIsTING SEQUENCEs
FOr
PrE -
`uvm_send
`uvm_send_pri
`uvm_rand_send
`uvm_rand_send_pri
`uvm_rand_send_with
`uvm_rand_send_pri_with
`uvm_add_to_sequence_library
`uvm_sequence_library_utils
SEQUENCEr SUBTYpEs
`uvm_declare_p_sequencer
These macros are used to start sequences
and sequence items that do not need to be
created.
Adds the given sequence TYPE to the
given sequence library LIBTYPE
This macro is used to declare a variable
p_sequencer whose type is specified by
SEQUENCER.
SEQUENCE ACTION MaCrOs
These macros are used to start sequences and sequence items on the default sequencer,
m_sequencer. This is determined a number of ways.
the sequencer handle provided in the uvm_sequence_base::start method
the sequencer used by the parent sequence
the sequencer that was set using the uvm_sequence_item::set_sequencer method
`uvm_create
`uvm_create(SEQ_OR_ITEM)
UVM 1.2 Class Reference
470
This action creates the item or sequence using the factory. It intentionally does zero
processing. After this action completes, the user can manually set values, manipulate
rand_mode and constraint_mode, etc.
`uvm_do
`uvm_do(SEQ_OR_ITEM)
This macro takes as an argument a uvm_sequence_item variable or object. The
argument is created using `uvm_create if necessary, then randomized. In the case of an
item, it is randomized after the call to uvm_sequence_base::start_item() returns. This is
called late-randomization. In the case of a sequence, the sub-sequence is started using
uvm_sequence_base::start() with call_pre_post set to 0. In the case of an item, the
item is sent to the driver through the associated sequencer.
For a sequence item, the following are called, in order
`uvm_create(item)
sequencer.wait_for_grant(prior) (task)
this.pre_do(1)
(task)
item.randomize()
this.mid_do(item)
(func)
sequencer.send_request(item)
(func)
sequencer.wait_for_item_done() (task)
this.post_do(item)
(func)
For a sequence, the following are called, in order
`uvm_create(sub_seq)
sub_seq.randomize()
sub_seq.pre_start()
this.pre_do(0)
this.mid_do(sub_seq)
sub_seq.body()
this.post_do(sub_seq)
sub_seq.post_start()
(task)
(task)
(func)
(task)
(func)
(task)
`uvm_do_pri
`uvm_do_pri(SEQ_OR_ITEM, PRIORITY)
This is the same as `uvm_do except that the sequence item or sequence is executed
with the priority specified in the argument
`uvm_do_with
`uvm do with(SEQ OR ITEM, CONSTRAINTS)
UVM 1.2 Class Reference
471
This is the same as `uvm_do except that the constraint block in the 2nd argument is
applied to the item or sequence in a randomize with statement before execution.
`uvm_do_pri_with
`uvm_do_pri_with(SEQ_OR_ITEM, PRIORITY, CONSTRAINTS)
This is the same as `uvm_do_pri except that the given constraint block is applied to the
item or sequence in a randomize with statement before execution.
SEQUENCE
ON
SEQUENCEr ACTION MaCrOs
These macros are used to start sequences and sequence items on a specific sequencer. The sequence or item is created and executed on the given sequencer.
`uvm_create_on
`uvm_create_on(SEQ_OR_ITEM, SEQR)
This is the same as `uvm_create except that it also sets the parent sequence to the
sequence in which the macro is invoked, and it sets the sequencer to the specified SEQR
argument.
`uvm_do_on
`uvm_do_on(SEQ_OR_ITEM, SEQR)
This is the same as `uvm_do except that it also sets the parent sequence to the
sequence in which the macro is invoked, and it sets the sequencer to the specified SEQR
argument.
`uvm_do_on_pri
`uvm_do_on_pri(SEQ_OR_ITEM, SEQR, PRIORITY)
This is the same as `uvm_do_pri except that it also sets the parent sequence to the
UVM 1.2 Class Reference
472
sequence in which the macro is invoked, and it sets the sequencer to the specified SEQR
argument.
`uvm_do_on_with
`uvm_do_on_with(SEQ_OR_ITEM, SEQR, CONSTRAINTS)
This is the same as `uvm_do_with except that it also sets the parent sequence to the
sequence in which the macro is invoked, and it sets the sequencer to the specified SEQR
argument. The user must supply brackets around the constraints.
`uvm_do_on_pri_with
`uvm_do_on_pri_with(SEQ_OR_ITEM, SEQR, PRIORITY, CONSTRAINTS)
This is the same as `uvm_do_pri_with except that it also sets the parent sequence to
the sequence in which the macro is invoked, and it sets the sequencer to the specified
SEQR argument.
SEQUENCE ACTION MaCrOs
FOr
PrE-EXIsTING SEQUENCEs
These macros are used to start sequences and sequence items that do not need to be
created.
`uvm_send
`uvm_send(SEQ_OR_ITEM)
This macro processes the item or sequence that has been created using `uvm_create. The processing is done without randomization. Essentially, an `uvm_do without the
create or randomization.
`uvm_send_pri
`uvm_send_pri(SEQ_OR_ITEM, PRIORITY)
This is the same as `uvm_send except that the sequence item or sequence is executed
with the priority specified in the argument.
UVM 1.2 Class Reference
473
`uvm_rand_send
`uvm_rand_send(SEQ_OR_ITEM)
This macro processes the item or sequence that has been already been allocated
(possibly with `uvm_create). The processing is done with randomization. Essentially, an
`uvm_do without the create.
`uvm_rand_send_pri
`uvm_rand_send_pri(SEQ_OR_ITEM, PRIORITY)
This is the same as `uvm_rand_send except that the sequence item or sequence is
executed with the priority specified in the argument.
`uvm_rand_send_with
`uvm_rand_send_with(SEQ_OR_ITEM, CONSTRAINTS)
This is the same as `uvm_rand_send except that the given constraint block is applied to
the item or sequence in a randomize with statement before execution.
`uvm_rand_send_pri_with
`uvm_rand_send_pri_with(SEQ_OR_ITEM, PRIORITY, CONSTRAINTS)
This is the same as `uvm_rand_send_pri except that the given constraint block is
applied to the item or sequence in a randomize with statement before execution.
`uvm_add_to_sequence_library
Adds the given sequence TYPE to the given sequence library LIBTYPE
`uvm_add_to_seq_lib(TYPE,LIBTYPE)
Invoke any number of times within a sequence declaration to statically add that
sequence to one or more sequence library types. The sequence will then be available for
selection and execution in all instances of the given sequencer types.
UVM 1.2 Class Reference
474
class seqA extends uvm_sequence_base #(simple_item);
function new(string name=`"TYPE`");
super.new(name);
endfunction
`uvm_object_utils(seqA)
`uvm_add_to_seq_lib(seqA, simple_seq_lib_RST)
`uvm_add_to_seq_lib(seqA, simple_seq_lib_CFG)
virtual task body(); \
`uvm_info("SEQ_START", {"Executing sequence '", get_full_name(),
"' (",get_type_name(),")"},UVM_HIGH)
#10;
endtask
endclass
`uvm_sequence_library_utils
`uvm_sequence_library_utils(TYPE)
Declares the infrastructure needed to define extensions to the uvm_sequence_library
class. You define new sequence library subtypes to statically specify sequence
membership from within sequence definitions. See also `uvm_add_to_sequence_library
for more information.
typedef simple_seq_lib uvm_sequence_library #(simple_item);
class simple_seq_lib_RST extends simple_seq_lib;
`uvm_object_utils(simple_seq_lib_RST)
`uvm_sequence_library_utils(simple_seq_lib_RST)
function new(string name="");
super.new(name);
endfunction
endclass
Each library, itself a sequence, can then be started independently on different sequencers
or in different phases of the same sequencer. See
uvm_sequencer_base::start_phase_sequence for information on starting default
sequences.
SEQUENCEr SUBTYpEs
`uvm_declare_p_sequencer
This macro is used to declare a variable p_sequencer whose type is specified by
SEQUENCER.
`uvm_declare_p_sequencer(SEQUENCER)
UVM 1.2 Class Reference
475
The example below shows using the `uvm_declare_p_sequencer macro along with the
uvm_object_utils macros to set up the sequence but not register the sequence in the
sequencer’s library.
class mysequence extends uvm_sequence#(mydata);
`uvm_object_utils(mysequence)
`uvm_declare_p_sequencer(some_seqr_type)
task body;
//Access some variable in the user's custom sequencer
if(p_sequencer.some_variable) begin
...
end
endtask
endclass
UVM 1.2 Class Reference
476
21.4 Callback Macros
These macros are used to register and execute callbacks extending from uvm_callbacks.
Summary
Callback Macros
These macros are used to register and execute callbacks extending from
uvm_callbacks.
MAcROs
`uvm_register_cb
`uvm_set_super_type
`uvm_do_callbacks
`uvm_do_obj_callbacks
`uvm_do_callbacks_exit_on
`uvm_do_obj_callbacks_exit_on
MAcROs
`uvm_register_cb
`uvm_register_cb(T,CB)
Registers the given CB callback type with the given T object type. If a type-callback pair
is not registered then a warning is issued if an attempt is made to use the pair (add,
delete, etc.).
The registration will typically occur in the component that executes the given type of
callback. For instance:
virtual class mycb extends uvm_callback;
virtual function void doit();
endclass
class my_comp extends uvm_component;
`uvm_register_cb(my_comp,mycb)
...
task run_phase(uvm_phase phase);
...
`uvm_do_callbacks(my_comp, mycb, doit())
endtask
endclass
`uvm_set_super_type
`uvm_set_super_type(T,ST)
UVM 1.2 Class Reference
477
Defines the super type of T to be ST. This allows for derived class objects to inherit
typewide callbacks that are registered with the base class.
The registration will typically occur in the component that executes the given type of
callback. For instance:
virtual class mycb extend uvm_callback;
virtual function void doit();
endclass
class my_comp extends uvm_component;
`uvm_register_cb(my_comp,mycb)
...
task run_phase(uvm_phase phase);
...
`uvm_do_callbacks(my_comp, mycb, doit())
endtask
endclass
class my_derived_comp extends my_comp;
`uvm_set_super_type(my_derived_comp,my_comp)
...
task run_phase(uvm_phase phase);
...
`uvm_do_callbacks(my_comp, mycb, doit())
endtask
endclass
`uvm_do_callbacks
`uvm_do_callbacks(T,CB,METHOD)
Calls the given METHOD of all callbacks of type CB registered with the calling object (i.e. this object), which is or is based on type T.
This macro executes all of the callbacks associated with the calling object (i.e. this
object). The macro takes three arguments:
CB is the class type of the callback objects to execute. The class type must have
a function signature that matches the METHOD argument.
T is the type associated with the callback. Typically, an instance of type T is
passed as one the arguments in the METHOD call.
METHOD is the method call to invoke, with all required arguments as if they were
invoked directly.
For example, given the following callback class definition
virtual class mycb extends uvm_cb;
pure function void my_function (mycomp comp, int addr, int data);
endclass
A component would invoke the macro as
task mycomp::run_phase(uvm_phase phase);
int curr_addr, curr_data;
...
`uvm_do_callbacks(mycb, mycomp, my_function(this, curr_addr, curr_data))
UVM 1.2 Class Reference
478
...
endtask
`uvm_do_obj_callbacks
`uvm_do_obj_callbacks(T,CB,OBJ,METHOD)
Calls the given METHOD of all callbacks based on type CB registered with the given
object, OBJ, which is or is based on type T.
This macro is identical to `uvm_do_callbacks macro, but it has an additional OBJ
argument to allow the specification of an external object to associate the callback with. For example, if the callbacks are being applied in a sequence, OBJ could be specified as
the associated sequencer or parent sequence.
...
`uvm_do_callbacks(mycb, mycomp, seqr, my_function(seqr, curr_addr,
curr_data))
...
`uvm_do_callbacks_exit_on
`uvm_do_callbacks_exit_on(T,CB,METHOD,VAL)
Calls the given METHOD of all callbacks of type CB registered with the calling object (i.e. this object), which is or is based on type T, returning upon the first callback returning
the bit value given by VAL.
This macro executes all of the callbacks associated with the calling object (i.e. this
object). The macro takes three arguments:
CB is the class type of the callback objects to execute. The class type must have
a function signature that matches the METHOD argument.
T is the type associated with the callback. Typically, an instance of type T is
passed as one the arguments in the METHOD call.
METHOD is the method call to invoke, with all required arguments as if they were
invoked directly.
VAL, if 1, says return upon the first callback invocation that returns 1. If 0, says
return upon the first callback invocation that returns 0.
For example, given the following callback class definition
virtual class mycb extends uvm_cb;
pure function bit drop_trans (mycomp comp, my_trans trans);
endclass
UVM 1.2 Class Reference
479
A component would invoke the macro as
task mycomp::run_phase(uvm_phase phase);
my_trans trans;
forever begin
get_port.get(trans);
if(do_callbacks(trans) == 0)
uvm_report_info("DROPPED",{"trans dropped:
%s",trans.convert2string()});
else
// execute transaction
end
endtask
function bit do_callbacks(my_trans);
// Returns 0 if drop happens and 1 otherwise
`uvm_do_callbacks_exit_on(mycomp, mycb, extobj, drop_trans(this,trans), 1)
endfunction
Because this macro calls return, its use is restricted to implementations of functions that
return a bit value, as in the above example.
`uvm_do_obj_callbacks_exit_on
`uvm_do_obj_callbacks_exit_on(T,CB,OBJ,METHOD,VAL)
Calls the given METHOD of all callbacks of type CB registered with the given object OBJ,
which must be or be based on type T, and returns upon the first callback that returns
the bit value given by VAL. It is exactly the same as the `uvm_do_callbacks_exit_on but
has a specific object instance (instead of the implicit this instance) as the third
argument.
...
// Exit if a callback returns a 1
`uvm_do_callbacks_exit_on(mycomp, mycb, seqr, drop_trans(seqr,trans), 1)
...
Because this macro calls return, its use is restricted to implementations of functions that
return a bit value, as in the above example.
UVM 1.2 Class Reference
480
21.5 TLM Implementation Port Declaration Macros
The TLM implementation declaration macros provide a way for components to provide
multiple implementation ports of the same implementation interface. When an
implementation port is defined using the built-in set of imps, there must be exactly one
implementation of the interface.
For example, if a component needs to provide a put implementation then it would have
an implementation port defined like:
class mycomp extends uvm_component;
uvm_put_imp#(data_type, mycomp) put_imp;
...
virtual task put (data_type t);
...
endtask
endclass
There are times, however, when you need more than one implementation for an
interface. This set of declarations allow you to easily create a new implementation class
to allow for multiple implementations. Although the new implementation class is a
different class, it can be bound to the same types of exports and ports as the original
class. Extending the put example above, let’s say that mycomp needs to provide two put
implementation ports. In that case, you would do something like:
//Define two new put interfaces which are compatible with uvm_put_ports
//and uvm_put_exports.
`uvm_put_imp_decl(_1)
`uvm_put_imp_decl(_2)
class my_put_imp#(type T=int) extends uvm_component;
uvm_put_imp_1#(T,my_put_imp#(T)) put_imp1;
uvm_put_imp_2#(T,my_put_imp#(T)) put_imp2;
...
function void put_1 (input T t);
//puts coming into put_imp1
...
endfunction
function void put_2(input T t);
//puts coming into put_imp2
...
endfunction
endclass
The important thing to note is that each `uvm_<interface>_imp_decl creates a new class
of type uvm_<interface>_imp<suffix>, where suffix is the input argument to the macro. For this reason, you will typically want to put these macros in a separate package to
avoid collisions and to allow sharing of the definitions.
Summary
TLM Implementation Port Declaration Macros
The TLM implementation declaration macros provide a way for components to
provide multiple implementation ports of the same implementation interface.
MACROs
`uvm_blocking_put_imp_decl
`uvm_nonblocking_put_imp_decl
`uvm_put_imp_decl
`uvm_blocking_get_imp_decl
UVM 1.2 Class Reference
481
`uvm_nonblocking_get_imp_decl
`uvm_get_imp_decl
`uvm_blocking_peek_imp_decl
`uvm_nonblocking_peek_imp_decl
`uvm_peek_imp_decl
`uvm_blocking_get_peek_imp_decl
`uvm_nonblocking_get_peek_imp_decl
`uvm_get_peek_imp_decl
`uvm_blocking_master_imp_decl
`uvm_nonblocking_master_imp_decl
`uvm_master_imp_decl
`uvm_blocking_slave_imp_decl
`uvm_nonblocking_slave_imp_decl
`uvm_slave_imp_decl
`uvm_blocking_transport_imp_decl
`uvm_nonblocking_transport_imp_decl
`uvm_transport_imp_decl
`uvm_analysis_imp_decl
MACROs
`uvm_blocking_put_imp_decl
`uvm_blocking_put_imp_decl(SFX)
Define the class uvm_blocking_put_impSFX for providing blocking put implementations. SFX is the suffix for the new class type.
`uvm_nonblocking_put_imp_decl
`uvm_nonblocking_put_imp_decl(SFX)
Define the class uvm_nonblocking_put_impSFX for providing non-blocking put
implementations. SFX is the suffix for the new class type.
`uvm_put_imp_decl
`uvm_put_imp_decl(SFX)
Define the class uvm_put_impSFX for providing both blocking and non-blocking put
implementations. SFX is the suffix for the new class type.
`uvm_blocking_get_imp_decl
UVM 1.2 Class Reference
482
`uvm_blocking_get_imp_decl(SFX)
Define the class uvm_blocking_get_impSFX for providing blocking get implementations. SFX is the suffix for the new class type.
`uvm_nonblocking_get_imp_decl
`uvm_nonblocking_get_imp_decl(SFX)
Define the class uvm_nonblocking_get_impSFX for providing non-blocking get
implementations. SFX is the suffix for the new class type.
`uvm_get_imp_decl
`uvm_get_imp_decl(SFX)
Define the class uvm_get_impSFX for providing both blocking and non-blocking get
implementations. SFX is the suffix for the new class type.
`uvm_blocking_peek_imp_decl
`uvm_blocking_peek_imp_decl(SFX)
Define the class uvm_blocking_peek_impSFX for providing blocking peek
implementations. SFX is the suffix for the new class type.
`uvm_nonblocking_peek_imp_decl
`uvm_nonblocking_peek_imp_decl(SFX)
Define the class uvm_nonblocking_peek_impSFX for providing non-blocking peek
implementations. SFX is the suffix for the new class type.
`uvm_peek_imp_decl
UVM 1.2 Class Reference
483
`uvm_peek_imp_decl(SFX)
Define the class uvm_peek_impSFX for providing both blocking and non-blocking peek
implementations. SFX is the suffix for the new class type.
`uvm_blocking_get_peek_imp_decl
`uvm_blocking_get_peek_imp_decl(SFX)
Define the class uvm_blocking_get_peek_impSFX for providing the blocking get_peek
implementation.
`uvm_nonblocking_get_peek_imp_decl
`uvm_nonblocking_get_peek_imp_decl(SFX)
Define the class uvm_nonblocking_get_peek_impSFX for providing non-blocking get_peek
implementation.
`uvm_get_peek_imp_decl
`uvm_get_peek_imp_decl(SFX)
Define the class uvm_get_peek_impSFX for providing both blocking and non-blocking
get_peek implementations. SFX is the suffix for the new class type.
`uvm_blocking_master_imp_decl
`uvm_blocking_master_imp_decl(SFX)
Define the class uvm_blocking_master_impSFX for providing the blocking master
implementation.
`uvm_nonblocking_master_imp_decl
`uvm_nonblocking_master_imp_decl(SFX)
UVM 1.2 Class Reference
484
Define the class uvm_nonblocking_master_impSFX for providing the non-blocking master
implementation.
`uvm_master_imp_decl
`uvm_master_imp_decl(SFX)
Define the class uvm_master_impSFX for providing both blocking and non-blocking
master implementations. SFX is the suffix for the new class type.
`uvm_blocking_slave_imp_decl
`uvm_blocking_slave_imp_decl(SFX)
Define the class uvm_blocking_slave_impSFX for providing the blocking slave
implementation.
`uvm_nonblocking_slave_imp_decl
`uvm_nonblocking_slave_imp_decl(SFX)
Define the class uvm_nonblocking_slave_impSFX for providing the non-blocking slave
implementation.
`uvm_slave_imp_decl
`uvm_slave_imp_decl(SFX)
Define the class uvm_slave_impSFX for providing both blocking and non-blocking slave
implementations. SFX is the suffix for the new class type.
`uvm_blocking_transport_imp_decl
`uvm_blocking_transport_imp_decl(SFX)
UVM 1.2 Class Reference
485
Define the class uvm_blocking_transport_impSFX for providing the blocking transport
implementation.
`uvm_nonblocking_transport_imp_decl
`uvm_nonblocking_transport_imp_decl(SFX)
Define the class uvm_nonblocking_transport_impSFX for providing the non-blocking
transport implementation.
`uvm_transport_imp_decl
`uvm_transport_imp_decl(SFX)
Define the class uvm_transport_impSFX for providing both blocking and non-blocking
transport implementations. SFX is the suffix for the new class type.
`uvm_analysis_imp_decl
`uvm_analysis_imp_decl(SFX)
Define the class uvm_analysis_impSFX for providing an analysis implementation. SFX is
the suffix for the new class type. The analysis implementation is the write function. The
`uvm_analysis_imp_decl allows for a scoreboard (or other analysis component) to
support input from many places. For example:
`uvm_analysis_imp_decl(_ingress)
`uvm_analysis_imp_decl(_egress)
class myscoreboard extends uvm_component;
uvm_analysis_imp_ingress#(mydata, myscoreboard) ingress;
uvm_analysis_imp_egress#(mydata, myscoreboard) egress;
mydata ingress_list[$];
...
function new(string name, uvm_component parent);
super.new(name,parent);
ingress = new("ingress", this);
egress = new("egress", this);
endfunction
function void write_ingress(mydata t);
ingress_list.push_back(t);
endfunction
function void write_egress(mydata t);
find_match_in_ingress_list(t);
endfunction
function void find_match_in_ingress_list(mydata t);
//implement scoreboarding for this particular dut
...
endfunction
endclass
UVM 1.2 Class Reference
486
21.6 Register Defines
Summary
Register Defines
MACrOs
`UVM_REG_ADDR_WIDTH
`UVM_REG_DATA_WIDTH
`UVM_REG_BYTENABLE_WIDTH
`UVM_REG_CVR_WIDTH
Maximum address width in bits
Maximum data width in bits
Maximum number of byte enable bits
Maximum number of bits in a uvm_reg_cvr_t
coverage model set.
MACrOs
`UVM_REG_ADDR_WIDTH
Maximum address width in bits
Default value is 64. Used to define the uvm_reg_addr_t type.
`UVM_REG_DATA_WIDTH
Maximum data width in bits
Default value is 64. Used to define the uvm_reg_data_t type.
`UVM_REG_BYTENABLE_WIDTH
Maximum number of byte enable bits
Default value is one per byte in `UVM_REG_DATA_WIDTH. Used to define the
uvm_reg_byte_en_t type.
`UVM_REG_CVR_WIDTH
Maximum number of bits in a uvm_reg_cvr_t coverage model set.
Default value is 32.
UVM 1.2 Class Reference
487
21.7 UVM Version Defines
Summary
UVM Version Defines
UVM REvIsION VALuEs
UVM_MAJOR_REV
UVM_MINOR_REV
UVM_FIX_REV
UVM_NAME
UVM_VERSION_STRING
CONdITIONAL COmPILATION
UVM_MAJOR_REV_1
UVM_MINOR_REV_2
UVM_VERSION_1_2
UVM VErsION LAddEr
UVM_POST_VERSION_1_1
These macros provide the current values for the
MAJOR, MINOR, and optionally the FIX revision.
Defines the MAJOR revision number.
Defines the MINOR revision number.
(Optionally) Defines the FIX revision letter.
The name used by the library when displaying
the name of the library.
Provides a string-ized version of the UVM
Library version number.
These macros provide the ability to conditionally
compile based on the revision of the library which
is being used.
Indicates that the MAJOR version of this release
is ‘1’.
Indicates that the MINOR version of this release
is ‘2’.
Indicates that the version of this release is
‘1.2’.
Indicates that this version of the UVM came
after the 1.1 versions, including the various 1.1
fix revisions.
UVM REvIsION VALuEs
These macros provide the current values for the MAJOR, MINOR, and optionally the FIX
revision.
Example with UVM version 1.2
UVM_MAJOR_REV
’1’
UVM_MINOR_REV
’2’
UVM_FIX_REV
’undefined’
Example with UVM version 1.1a
UVM_MAJOR_REV
’1’
UVM_MINOR_REV
’1’
UVM_FIX_REV
’a’
UVM_MAJOR_REV
Defines the MAJOR revision number.
For UVM version 1.2, the MAJOR revision number is ‘1’
UVM 1.2 Class Reference
488
`define UVM_MAJOR_REV 1
UVM_MINOR_REV
Defines the MINOR revision number.
For UVM version 1.2, the MINOR revision number is ‘2’
`define UVM_MINOR_REV 2
UVM_FIX_REV
(Optionally) Defines the FIX revision letter.
For the first “X.Y” release of the UVM, there is no FIX revision letter. In these cases, the
UVM_FIX_REV is left undefined.
For any subsequent “X.Y” fix releases, the UVM_FIX_REV value is set to the appropriate
fix release letter.
Example
1.1
First release, UVM_FIX_REV is undefined
1.1a
Fix release, UVM_FIX_REV is ‘a’
UVM_NAME
The name used by the library when displaying the name of the library.
`define UVM_NAME UVM
UVM_VERSION_STRING
Provides a string-ized version of the UVM Library version number.
When there is a FIX_REV, the string is “<name>-<major>.<minor><fix>” (such as
“UVM-1.1d”). When there is NO FIX_REV, the string is “<name>-<major>.<minor>”
(such as “UVM-1.2”).
CONdITIONAL COmPILATION
These macros provide the ability to conditionally compile based on the revision of the
library which is being used.
UVM 1.2 Class Reference
489
These macros are required for conditional compilation, as SystemVerilog does not support
conditionals with `ifdefs.
For example
// Illegal:
`if (UVM_MAJOR_REV == 1)
// Legal:
`ifdef UVM_MAJOR_REV_1
UVM_MAJOR_REV_1
Indicates that the MAJOR version of this release is ‘1’.
`define UVM_MAJOR_REV_1
UVM_MINOR_REV_2
Indicates that the MINOR version of this release is ‘2’.
`define UVM_MINOR_REV_2
UVM_VERSION_1_2
Indicates that the version of this release is ‘1.2’.
`define UVM_VERSION_1_2
UVM VErsION LAddEr
UVM_POST_VERSION_1_1
Indicates that this version of the UVM came after the 1.1 versions, including the various
1.1 fix revisions.
The first UVM version wherein this macro is defined is 1.2, and the macro will continue to
be defined for all future revisions of the UVM library.
`define UVM_POST_VERSION_1_1
UVM 1.2 Class Reference
490
22. Policy Classes
Each of UVM’s policy classes perform a specific task for uvm_object-based objects:
printing, comparing, recording, packing, and unpacking. They are implemented
separately from uvm_object so that users can plug in different ways to print, compare,
etc. without modifying the object class being operated on. The user can simply apply a
different printer or compare “policy” to change how an object is printed or compared.
Each policy class includes several user-configurable parameters that control the
operation. Users may also customize operations by deriving new policy subtypes from
these base types. For example, the UVM provides four different uvm_printer-based
policy classes, each of which print objects in a different format.
uvm_printer - performs deep printing of uvm_object-based objects. The UVM
provides several subtypes to uvm_printer that print objects in a specific format:
uvm_table_printer, uvm_tree_printer, and uvm_line_printer. Each such printer
has many configuration options that govern what and how object members are
printed.
uvm_comparer - performs deep comparison of uvm_object-based objects. Users
may configure what is compared and how miscompares are reported.
uvm_recorder - performs the task of recording uvm_object-based objects to a
transaction data base. The implementation is vendor-specific.
uvm_packer - used to pack (serialize) and unpack uvm_object-based properties
into bit, byte, or int arrays and back again.
Summary
Policy Classes
Each of UVM’s policy classes perform a specific task for uvm_object-based
objects: printing, comparing, recording, packing, and unpacking.
UVM 1.2 Class Reference
491
22.1 uvm_printer
The uvm_printer class provides an interface for printing uvm_objects in various formats. Subtypes of uvm_printer implement different print formats, or policies.
A user-defined printer format can be created, or one of the following four built-in printers
can be used:
uvm_printer - provides base printer functionality; must be overridden.
uvm_table_printer - prints the object in a tabular form.
uvm_tree_printer - prints the object in a tree form.
uvm_line_printer - prints the information on a single line, but uses the same
object separators as the tree printer.
Printers have knobs that you use to control what and how information is printed. These
knobs are contained in a separate knob class:
uvm_printer_knobs - common printer settings
For convenience, global instances of each printer type are available for direct reference in
your testbenches.
uvm_default_tree_printer
uvm_default_line_printer
uvm_default_table_printer
uvm_default_printer (set to default_table_printer by default)
When uvm_object::print and uvm_object::sprint are called without specifying a printer,
the uvm_default_printer is used.
Contents
uvm_printer
uvm_table_printer
uvm_tree_printer
uvm_line_printer
uvm_printer_knobs
The uvm_printer class provides an interface for printing
uvm_objects in various formats.
The table printer prints output in a tabular format.
By overriding various methods of the uvm_printer super
class, the tree printer prints output in a tree format.
The line printer prints output in a line format.
The uvm_printer_knobs class defines the printer settings
available to all printer subtypes.
knobs
uvm_printer_knobs knobs = new
The knob object provides access to the variety of knobs associated with a specific printer
instance.
METHODS
FOR PRINTER USAGE
print_field
UVM 1.2 Class Reference
492
virtual function void print_field (
string name,
uvm_bitstream_t value,
int size,
uvm_radix_enum radix
= UVM_NORADIX,
byte scope_separator = ".",
string type_name
= ""
)
Prints an integral field (up to 4096 bits).
name
The name of the field.
value
The value of the field.
size
The number of bits of the field (maximum is 4096).
radix
The radix to use for printing. The printer knob for radix is
used if no radix is specified.
scope_separator
is used to find the leaf name since many printers only print
the leaf name of a field. Typical values for the separator
are . (dot) or [ (open bracket).
print_field_int
virtual function void print_field_int (
string name,
uvm_integral_t value,
int size,
= UVM_NORADIX,
uvm_radix_enum radix
byte scope_separator = ".",
string type_name
= ""
)
Prints an integral field (up to 64 bits).
name
The name of the field.
value
The value of the field.
size
The number of bits of the field (maximum is 64).
radix
The radix to use for printing. The printer knob for radix is
used if no radix is specified.
scope_separator
is used to find the leaf name since many printers only print
the leaf name of a field. Typical values for the separator
are . (dot) or [ (open bracket).
print_object
virtual function void print_object (
string name,
uvm_object value,
byte scope_separator = "."
)
Prints an object. Whether the object is recursed depends on a variety of knobs, such as
the depth knob; if the current depth is at or below the depth setting, then the object is
not recursed.
By default, the children of uvm_components are printed. To turn this behavior off, you
must set the uvm_component::print_enabled bit to 0 for the specific children you do not
want automatically printed.
UVM 1.2 Class Reference
493
print_string
virtual function void print_string (
string name,
string value,
byte scope_separator = "."
)
Prints a string field.
print_time
virtual function void print_time (
string name,
time value,
byte scope_separator = "."
)
Prints a time value. name is the name of the field, and value is the value to print.
The print is subject to the $timeformat system task for formatting time values.
print_real
virtual function void print_real (
string name,
real value,
byte scope_separator = "."
)
Prints a real field.
print_generic
virtual function void print_generic (
string name,
string type_name,
int size,
string value,
byte scope_separator = "."
)
Prints a field having the given name, type_name, size, and value.
METHODS
FOR PRINTER SUBTYPING
emit
virtual function string emit ()
Emits a string representing the contents of an object in a format defined by an extension
of this object.
UVM 1.2 Class Reference
494
format_row
virtual function string format_row (
uvm_printer_row_info row
)
Hook for producing custom output of a single field (row).
format_row
Hook to override base header with a custom header.
format_header
Hook to override base footer with a custom footer.
adjust_name
virtual protected function string adjust_name (
string id,
byte scope_separator = "."
)
Prints a field’s name, or id, which is the full instance name.
The intent of the separator is to mark where the leaf name starts if the printer if
configured to print only the leaf name of the identifier.
print_array_header
virtual function void print_array_header(
string name,
size,
int string arraytype
= "array",
byte scope_separator = "."
)
Prints the header of an array. This function is called before each individual element is
printed. print_array_footer is called to mark the completion of array printing.
print_array_range
virtual function void print_array_range (
int min,
int max
)
Prints a range using ellipses for values. This method is used when honoring the array
knobs for partial printing of large arrays, uvm_printer_knobs::begin_elements and
uvm_printer_knobs::end_elements.
This function should be called after begin_elements have been printed and before
end_elements have been printed.
UVM 1.2 Class Reference
495
print_array_footer
virtual function void print_array_footer (
int size = 0
)
Prints the header of a footer. This function marks the end of an array print. Generally,
there is no output associated with the array footer, but this method let’s the printer
know that the array printing is complete.
uvm_table_printer
The table printer prints output in a tabular format.
The following shows sample output from the table printer.
--------------------------------------------------Name
Type
Size
Value
--------------------------------------------------c1
container
@1013
d1
mydata
@1022
v1
integral
32
'hcb8f1c97
e1
enum
32
THREE
str
string
2
hi
value
integral
12
'h2d
---------------------------------------------------
Summary
uvm_table_printer
The table printer prints output in a tabular format.
CLASS HIERARcHY
uvm_printer
uvm_table_printer
CLASS DEcLARATION
class uvm_table_printer extends uvm_printer
VARIABLES
new
METHODS
emit
Creates a new instance of uvm_table_printer.
Formats the collected information from prior calls to print_* into
table format.
VARIABLES
new
function new()
UVM 1.2 Class Reference
496
Creates a new instance of uvm_table_printer.
METHODS
emit
virtual function string emit()
Formats the collected information from prior calls to print_* into table format.
uvm_tree_printer
By overriding various methods of the uvm_printer super class, the tree printer prints
output in a tree format.
The following shows sample output from the tree printer.
c1: (container@1013) {
d1: (mydata@1022) {
v1: 'hcb8f1c97
e1: THREE
str: hi
}
value: 'h2d
}
Summary
uvm_tree_printer
By overriding various methods of the uvm_printer super class, the tree printer
prints output in a tree format.
CLASS HIERARcHY
uvm_printer
uvm_tree_printer
CLASS DEcLARATION
class uvm_tree_printer extends uvm_printer
VARIABLES
new
METHODS
emit
Creates a new instance of uvm_tree_printer.
Formats the collected information from prior calls to print_* into
hierarchical tree format.
VARIABLES
UVM 1.2 Class Reference
497
new
function new()
Creates a new instance of uvm_tree_printer.
METHODS
emit
virtual function string emit()
Formats the collected information from prior calls to print_* into hierarchical tree format.
uvm_line_printer
The line printer prints output in a line format.
The following shows sample output from the line printer.
c1: (container@1013) { d1: (mydata@1022) { v1: 'hcb8f1c97 e1: THREE str: hi
} value: 'h2d }
Summary
uvm_line_printer
The line printer prints output in a line format.
CLASS HIERARcHY
uvm_printer
uvm_tree_printer
uvm_line_printer
CLASS DEcLARATION
class uvm_line_printer extends uvm_tree_printer
VARIABLES
new
Creates a new instance of uvm_line_printer.
VARIABLES
UVM 1.2 Class Reference
498
new
function new()
Creates a new instance of uvm_line_printer. It differs from the uvm_tree_printer only in
that the output contains no line-feeds and indentation.
uvm_printer_knobs
The uvm_printer_knobs class defines the printer settings available to all printer subtypes.
Summary
uvm_printer_knobs
The uvm_printer_knobs class defines the printer settings available to all printer
subtypes.
CLASS DEcLARATION
class uvm_printer_knobs
VARIABLES
header
footer
full_name
identifier
type_name
size
depth
reference
begin_elements
end_elements
prefix
indent
show_root
mcd
separator
show_radix
default_radix
dec_radix
bin_radix
UVM 1.2 Class Reference
Indicates whether the uvm_printer::format_header
function should be called when printing an object.
Indicates whether the uvm_printer::format_footer
function should be called when printing an object.
Indicates whether uvm_printer::adjust_name should print
the full name of an identifier or just the leaf name.
Indicates whether uvm_printer::adjust_name should print
the identifier.
Controls whether to print a field’s type name.
Controls whether to print a field’s size.
Indicates how deep to recurse when printing objects.
Controls whether to print a unique reference ID for object
handles.
Defines the number of elements at the head of a list to
print.
This defines the number of elements at the end of a list
that should be printed.
Specifies the string prepended to each output line
This knob specifies the number of spaces to use for level
indentation.
This setting indicates whether or not the initial object that
is printed (when current depth is 0) prints the full path
name.
This is a file descriptor, or multi-channel descriptor, that
specifies where the print output should be directed.
For tree printers only, determines the opening and closing
separators used for nested objects.
Indicates whether the radix string (‘h, and so on) should
be prepended to an integral value when one is printed.
This knob sets the default radix to use for integral values
when no radix enum is explicitly supplied to the
uvm_printer::print_field or uvm_printer::print_field_int
methods.
This string should be prepended to the value of an integral
type when a radix of UVM_DEC is used for the radix of the
integral object.
This string should be prepended to the value of an integral
type when a radix of UVM_BIN is used for the radix of the
499
oct_radix
unsigned_radix
hex_radix
METHODS
get_radix_str
integral object.
This string should be prepended to the value of an integral
type when a radix of UVM_OCT is used for the radix of the
integral object.
This is the string which should be prepended to the value
of an integral type when a radix of UVM_UNSIGNED is
used for the radix of the integral object.
This string should be prepended to the value of an integral
type when a radix of UVM_HEX is used for the radix of the
integral object.
Converts the radix from an enumerated to a printable
radix according to the radix printing knobs (bin_radix, and
so on).
VARIABLES
header
bit header = 1
Indicates whether the uvm_printer::format_header function should be called when
printing an object.
footer
bit footer = 1
Indicates whether the uvm_printer::format_footer function should be called when
printing an object.
full_name
bit full_name = 0
Indicates whether uvm_printer::adjust_name should print the full name of an identifier or
just the leaf name.
identifier
bit identifier = 1
Indicates whether uvm_printer::adjust_name should print the identifier. This is useful in
cases where you just want the values of an object, but no identifiers.
type_name
bit type_name = 1
Controls whether to print a field’s type name.
UVM 1.2 Class Reference
500
size
bit size = 1
Controls whether to print a field’s size.
depth
int depth = -1
Indicates how deep to recurse when printing objects. A depth of -1 means to print
everything.
reference
bit reference = 1
Controls whether to print a unique reference ID for object handles. The behavior of this
knob is simulator-dependent.
begin_elements
int begin_elements = 5
Defines the number of elements at the head of a list to print. Use -1 for no max.
end_elements
int end_elements = 5
This defines the number of elements at the end of a list that should be printed.
prefix
string prefix = ""
Specifies the string prepended to each output line
indent
int indent = 2
This knob specifies the number of spaces to use for level indentation. The default level
indentation is two spaces.
show_root
UVM 1.2 Class Reference
501
bit show_root = 0
This setting indicates whether or not the initial object that is printed (when current depth
is 0) prints the full path name. By default, the first object is treated like all other
objects and only the leaf name is printed.
mcd
int mcd = UVM_STDOUT
This is a file descriptor, or multi-channel descriptor, that specifies where the print output
should be directed.
By default, the output goes to the standard output of the simulator.
separator
string separator = "{}"
For tree printers only, determines the opening and closing separators used for nested
objects.
show_radix
bit show_radix = 1
Indicates whether the radix string (‘h, and so on) should be prepended to an integral
value when one is printed.
default_radix
uvm_radix_enum default_radix = UVM_HEX
This knob sets the default radix to use for integral values when no radix enum is
explicitly supplied to the uvm_printer::print_field or uvm_printer::print_field_int
methods.
dec_radix
string dec_radix = "'d"
This string should be prepended to the value of an integral type when a radix of
UVM_DEC is used for the radix of the integral object.
When a negative number is printed, the radix is not printed since only signed decimal
values can print as negative.
bin_radix
string bin_radix = "'b"
UVM 1.2 Class Reference
502
This string should be prepended to the value of an integral type when a radix of
UVM_BIN is used for the radix of the integral object.
oct_radix
string oct_radix = "'o"
This string should be prepended to the value of an integral type when a radix of
UVM_OCT is used for the radix of the integral object.
unsigned_radix
string unsigned_radix = "'d"
This is the string which should be prepended to the value of an integral type when a
radix of UVM_UNSIGNED is used for the radix of the integral object.
hex_radix
string hex_radix = "'h"
This string should be prepended to the value of an integral type when a radix of
UVM_HEX is used for the radix of the integral object.
METHODS
get_radix_str
function string get_radix_str(
uvm_radix_enum radix
)
Converts the radix from an enumerated to a printable radix according to the radix
printing knobs (bin_radix, and so on).
UVM 1.2 Class Reference
503
22.2 uvm_comparer
The uvm_comparer class provides a policy object for doing comparisons. The policies
determine how miscompares are treated and counted. Results of a comparison are
stored in the comparer object. The uvm_object::compare and uvm_object::do_compare
methods are passed a uvm_comparer policy object.
Summary
uvm_comparer
The uvm_comparer class provides a policy object for doing comparisons.
CLAss DEcLARATION
class uvm_comparer
VARIABLEs
policy
show_max
verbosity
sev
miscompares
physical
abstract
check_type
result
METHOds
compare_field
compare_field_int
compare_field_real
compare_object
compare_string
print_msg
Determines whether comparison is UVM_DEEP,
UVM_REFERENCE, or UVM_SHALLOW.
Sets the maximum number of messages to send to the
printer for miscompares of an object.
Sets the verbosity for printed messages.
Sets the severity for printed messages.
This string is reset to an empty string when a
comparison is started.
This bit provides a filtering mechanism for fields.
This bit provides a filtering mechanism for fields.
This bit determines whether the type, given by
uvm_object::get_type_name, is used to verify that the
types of two objects are the same.
This bit stores the number of miscompares for a given
compare operation.
Compares two integral values.
This method is the same as compare_field except that
the arguments are small integers, less than or equal to
64 bits.
This method is the same as compare_field except that
the arguments are real numbers.
Compares two class objects using the policy knob to
determine whether the comparison should be deep,
shallow, or reference.
Compares two string variables.
Causes the error count to be incremented and the
message, msg, to be appended to the miscompares
string (a newline is used to separate messages).
VARIABLEs
policy
uvm_recursion_policy_enum policy = UVM_DEFAULT_POLICY
Determines whether comparison is UVM_DEEP, UVM_REFERENCE, or UVM_SHALLOW.
UVM 1.2 Class Reference
504
show_max
int unsigned show_max = 1
Sets the maximum number of messages to send to the printer for miscompares of an
object.
verbosity
int unsigned verbosity = UVM_LOW
Sets the verbosity for printed messages.
The verbosity setting is used by the messaging mechanism to determine whether
messages should be suppressed or shown.
sev
uvm_severity sev = UVM_INFO
Sets the severity for printed messages.
The severity setting is used by the messaging mechanism for printing and filtering
messages.
miscompares
string miscompares = ""
This string is reset to an empty string when a comparison is started.
The string holds the last set of miscompares that occurred during a comparison.
physical
bit physical = 1
This bit provides a filtering mechanism for fields.
The abstract and physical settings allow an object to distinguish between two different
classes of fields.
It is up to you, in the uvm_object::do_compare method, to test the setting of this field if
you want to use the physical trait as a filter.
abstract
bit abstract = 1
This bit provides a filtering mechanism for fields.
The abstract and physical settings allow an object to distinguish between two different
UVM 1.2 Class Reference
505
classes of fields.
It is up to you, in the uvm_object::do_compare method, to test the setting of this field if
you want to use the abstract trait as a filter.
check_type
bit check_type = 1
This bit determines whether the type, given by uvm_object::get_type_name, is used to
verify that the types of two objects are the same.
This bit is used by the compare_object method. In some cases it is useful to set this to
0 when the two operands are related by inheritance but are different types.
result
int unsigned result = 0
This bit stores the number of miscompares for a given compare operation. You can use
the result to determine the number of miscompares that were found.
METHOds
compare_field
virtual function bit compare_field (
string name, uvm_bitstream_t lhs, uvm_bitstream_t rhs, size, int uvm_radix_enum radix = UVM_NORADIX
)
Compares two integral values.
The name input is used for purposes of storing and printing a miscompare.
The left-hand-side lhs and right-hand-side rhs objects are the two objects used for
comparison.
The size variable indicates the number of bits to compare; size must be less than or
equal to 4096.
The radix is used for reporting purposes, the default radix is hex.
compare_field_int
virtual function bit compare_field_int (
string name, uvm_integral_t lhs, uvm_integral_t rhs, int size, uvm_radix_enum radix = UVM_NORADIX
)
UVM 1.2 Class Reference
506
This method is the same as compare_field except that the arguments are small integers,
less than or equal to 64 bits. It is automatically called by compare_field if the operand
size is less than or equal to 64.
compare_field_real
virtual function bit compare_field_real (
string name,
real lhs,
real rhs
)
This method is the same as compare_field except that the arguments are real numbers.
compare_object
virtual function bit compare_object (
string name,
uvm_object lhs,
uvm_object rhs
)
Compares two class objects using the policy knob to determine whether the comparison
should be deep, shallow, or reference.
The name input is used for purposes of storing and printing a miscompare.
The lhs and rhs objects are the two objects used for comparison.
The check_type determines whether or not to verify the object types match (the return
from lhs.get_type_name() matches rhs.get_type_name()).
compare_string
virtual function bit compare_string (
string name,
string lhs,
string rhs
)
Compares two string variables.
The name input is used for purposes of storing and printing a miscompare.
The lhs and rhs objects are the two objects used for comparison.
print_msg
function void print_msg (
string msg
)
Causes the error count to be incremented and the message, msg, to be appended to the
miscompares string (a newline is used to separate messages).
If the message count is less than the show_max setting, then the message is printed to
standard-out using the current verbosity and severity settings. See the verbosity and
sev variables for more information.
UVM 1.2 Class Reference
507
22.3 UVM Recorders
The uvm_recorder class serves two purposes
Firstly, it is an abstract representation of a record within a uvm_tr_stream.
Secondly, it is a policy object for recording fields into that record within the
stream.
Contents
UVM Recorders
uvm_recorder
uvm_text_recorder
Abstract class which defines the recorder API.
The uvm_text_recorder is the default recorder
implementation for the uvm_text_tr_database.
uvm_recorder
Abstract class which defines the recorder API.
Summary
uvm_recorder
Abstract class which defines the recorder API.
CLAss HIErArchY
uvm_void
uvm_object
uvm_recorder
CLAss DEcLArAtION
virtual class uvm_recorder extends uvm_object
default_radix
physical
abstract
identifier
recursion_policy
CONFIGurAtION API
get_stream
TrANsActION REcOrdEr API
close
free
UVM 1.2 Class Reference
This is the default radix setting if record_field is
called without a radix.
This bit provides a filtering mechanism for
fields.
This bit provides a filtering mechanism for
fields.
This bit is used to specify whether or not an
object’s reference should be recorded when the
object is recorded.
Sets the recursion policy for recording objects.
Returns a reference to the stream which
created this record.
Once a recorder has been opened via
uvm_tr_stream::open_recorder, the user can
close the recorder.
Closes this recorder.
Frees this recorder
508
is_open
get_open_time
is_closed
get_close_time
HANdLEs
get_handle
get_recorder_from_handle
AttrIButE REcOrdING
record_field
record_field_int
record_field_real
record_object
record_string
record_time
record_generic
use_record_attribute
get_record_attribute_handle
ImpLEmENtAtION AGNOstIc API
do_open
do_close
do_free
do_record_field
do_record_field_int
do_record_field_real
do_record_object
do_record_string
do_record_time
do_record_generic
Returns true if this uvm_recorder was opened
on its stream, but has not yet been closed.
Returns the open_time
Returns true if this uvm_recorder was closed
on its stream, but has not yet been freed.
Returns the close_time
Returns a unique ID for this recorder.
Static accessor, returns a recorder reference
for a given unique id.
Records an integral field (less than or equal to
4096 bits).
Records an integral field (less than or equal to
64 bits).
Records a real field.
Records an object field.
Records a string field.
Records a time field.
Records a name/value pair, where value has
been converted to a string.
Indicates that this recorder does (or does
not) support usage of the
`uvm_record_attribute macro.
Provides a tool-specific handle which is
compatible with `uvm_record_attribute.
Callback triggered via
uvm_tr_stream::open_recorder.
Callback triggered via close.
Callback triggered via free.
Records an integral field (less than or equal to
4096 bits).
Records an integral field (less than or equal to
64 bits).
Records a real field.
Records an object field.
Records a string field.
Records a time field.
Records a name/value pair, where value has
been converted to a string.
default_radix
uvm_radix_enum default_radix = UVM_HEX
This is the default radix setting if record_field is called without a radix.
physical
bit physical = 1
This bit provides a filtering mechanism for fields.
The abstract and physical settings allow an object to distinguish between two different
classes of fields.
It is up to you, in the uvm_object::do_record method, to test the setting of this field if
you want to use the physical trait as a filter.
UVM 1.2 Class Reference
509
abstract
bit abstract = 1
This bit provides a filtering mechanism for fields.
The abstract and physical settings allow an object to distinguish between two different
classes of fields.
It is up to you, in the uvm_object::do_record method, to test the setting of this field if
you want to use the abstract trait as a filter.
identifier
bit identifier = 1
This bit is used to specify whether or not an object’s reference should be recorded when
the object is recorded.
recursion_policy
uvm_recursion_policy_enum policy = UVM_DEFAULT_POLICY
Sets the recursion policy for recording objects.
The default policy is deep (which means to recurse an object).
CONFIGurAtION API
get_stream
function uvm_tr_stream get_stream()
Returns a reference to the stream which created this record.
A warning will be asserted if get_stream is called prior to the record being initialized via
do_open.
TrANsActION REcOrdEr API
Once a recorder has been opened via uvm_tr_stream::open_recorder, the user can close
the recorder.
Due to the fact that many database implementations will require crossing a language
boundary, an additional step of freeing the recorder is required.
A link can be established within the database any time between open and free, however
it is illegal to establish a link after freeing the recorder.
UVM 1.2 Class Reference
510
close
function void close(
time close_time = 0
)
Closes this recorder.
Closing a recorder marks the end of the transaction in the stream.
Parameters
close_time
Optional time to record as the closing time of this transaction.
This method will trigger a do_close call.
free
function void free(
time close_time = 0
)
Frees this recorder
Freeing a recorder indicates that the stream and database can release any references to
the recorder.
Parameters
close_time
Optional time to record as the closing time of this transaction.
If a recorder has not yet been closed (via a call to close), then close will automatically be
called, and passed the close_time. If the recorder has already been closed, then the
close_time will be ignored.
This method will trigger a do_free call.
is_open
function bit is_open()
Returns true if this uvm_recorder was opened on its stream, but has not yet been closed.
get_open_time
function time get_open_time()
Returns the open_time
is_closed
function bit is_closed()
Returns true if this uvm_recorder was closed on its stream, but has not yet been freed.
UVM 1.2 Class Reference
511
get_close_time
function time get_close_time()
Returns the close_time
HANdLEs
get_handle
function integer get_handle()
Returns a unique ID for this recorder.
A value of 0 indicates that the recorder has been freed, and no longer has a valid ID.
get_recorder_from_handle
static function uvm_recorder get_recorder_from_handle(
integer id
)
Static accessor, returns a recorder reference for a given unique id.
If no recorder exists with the given id, or if the recorder with that id has been freed,
then null is returned.
This method can be used to access the recorder associated with a call to
uvm_transaction::begin_tr or uvm_component::begin_tr.
integer handle = tr.begin_tr();
uvm_recorder recorder = uvm_recorder::get_recorder_from_handle(handle);
if (recorder != null) begin
recorder.record_string("begin_msg", "Started recording transaction!");
end
AttrIButE REcOrdING
record_field
function void record_field(
string name, uvm_bitstream_t value, size, int uvm_radix_enum radix = UVM_NORADIX
)
Records an integral field (less than or equal to 4096 bits).
Parameters
UVM 1.2 Class Reference
512
name
Name of the field
value
Value of the field to record.
size
Number of bits of the field which apply (Usually obtained via $bits).
radix
The uvm_radix_enum to use.
This method will trigger a do_record_field call.
record_field_int
function void record_field_int(
string name, uvm_integral_t value, int size, uvm_radix_enum radix = UVM_NORADIX
)
Records an integral field (less than or equal to 64 bits).
This optimized version of record_field is useful for sizes up to 64 bits.
Parameters
name
Name of the field
value
Value of the field to record
size
Number of bits of the wfield which apply (Usually obtained via $bits).
radix
The uvm_radix_enum to use.
This method will trigger a do_record_field_int call.
record_field_real
function void record_field_real(
string name,
real value
)
Records a real field.
Parameters
name
Name of the field
value
Value of the field to record
This method will trigger a do_record_field_real call.
record_object
function void record_object(
string name,
uvm_object value
)
Records an object field.
Parameters
UVM 1.2 Class Reference
513
name
Name of the field
value
Object to record
The implementation must use the recursion_policy and identifier to determine exactly
what should be recorded.
record_string
function void record_string(
string name,
string value
)
Records a string field.
Parameters
name
Name of the field
value
Value of the field
record_time
function void record_time(
string name,
time value
)
Records a time field.
Parameters
name
Name of the field
value
Value of the field
record_generic
function void record_generic(
string name,
string value,
string type_name = ""
)
Records a name/value pair, where value has been converted to a string.
For example
recorder.record_generic("myvar","var_type", $sformatf("%0d",myvar), 32);
Parameters
name
Name of the field
value
Value of the field
UVM 1.2 Class Reference
514
type_name
optional Type name of the field
use_record_attribute
virtual function bit use_record_attribute()
Indicates that this recorder does (or does not) support usage of the
`uvm_record_attribute macro.
The default return value is 0 (not supported), developers can optionally extend
uvm_recorder and set the value to 1 if they support the `uvm_record_attribute macro.
get_record_attribute_handle
virtual function integer get_record_attribute_handle()
Provides a tool-specific handle which is compatible with `uvm_record_attribute.
By default, this method will return the same value as get_handle, however tool vendors
can override this method to provide tool-specific handles which will be passed to the
`uvm_record_attribute macro.
ImpLEmENtAtION AGNOstIc API
do_open
protected virtual function void do_open(
uvm_tr_stream stream,
time open_time,
string type_name
)
Callback triggered via uvm_tr_stream::open_recorder.
The do_open callback can be used to initialize any internal state within the recorder, as
well as providing a location to record any initial information.
do_close
protected virtual function void do_close(
time close_time
)
Callback triggered via close.
The do_close callback can be used to set internal state within the recorder, as well as
providing a location to record any closing information.
do_free
protected virtual function void do_free()
UVM 1.2 Class Reference
515
Callback triggered via free.
The do_free callback can be used to release the internal state within the recorder, as well
as providing a location to record any “freeing” information.
do_record_field
pure virtual protected function void do_record_field(
string name,
uvm_bitstream_t value,
int size,
uvm_radix_enum radix
)
Records an integral field (less than or equal to 4096 bits).
Mandatory Backend implementation of record_field
do_record_field_int
pure virtual protected function void do_record_field_int(
string name,
uvm_integral_t value,
int size,
uvm_radix_enum radix
)
Records an integral field (less than or equal to 64 bits).
Mandatory Backend implementation of record_field_int
do_record_field_real
pure virtual protected function void do_record_field_real(
string name,
real value
)
Records a real field.
Mandatory Backend implementation of record_field_real
do_record_object
pure virtual protected function void do_record_object(
string name,
uvm_object value
)
Records an object field.
Mandatory Backend implementation of record_object
do_record_string
pure virtual protected function void do_record_string(
string name,
UVM 1.2 Class Reference
516
string value
)
Records a string field.
Mandatory Backend implementation of record_string
do_record_time
pure virtual protected function void do_record_time(
string name,
time value
)
Records a time field.
Mandatory Backend implementation of record_time
do_record_generic
pure virtual protected function void do_record_generic(
string name,
string value,
string type_name
)
Records a name/value pair, where value has been converted to a string.
Mandatory Backend implementation of record_generic
uvm_text_recorder
The uvm_text_recorder is the default recorder implementation for the
uvm_text_tr_database.
Summary
uvm_text_recorder
The uvm_text_recorder is the default recorder implementation for the
uvm_text_tr_database.
CLAss HIErArchY
uvm_void
uvm_object
uvm_recorder
uvm_text_recorder
CLAss DEcLArAtION
class uvm_text_recorder extends uvm_recorder
new
Constructor
ImpLEmENtAtION
UVM 1.2 Class Reference
517
AGNOstIc API
do_open
do_close
do_free
do_record_field
do_record_field_int
do_record_field_real
do_record_object
do_record_string
do_record_time
do_record_generic
ImpLEmENtAtION
SpEcIFIc API
write_attribute
write_attribute_int
Callback triggered via
uvm_tr_stream::open_recorder.
Callback triggered via uvm_recorder::close.
Callback triggered via uvm_recorder::free.
Records an integral field (less than or equal to 4096
bits).
Records an integral field (less than or equal to 64
bits).
Record a real field.
Record an object field.
Records a string field.
Records a time field.
Records a name/value pair, where value has been
converted to a string.
Outputs an integral attribute to the textual log
Outputs an integral attribute to the textual log
new
function new(
string name = "unnamed-uvm_text_recorder"
)
Constructor
Parameters
name
Instance name
ImpLEmENtAtION AGNOstIc API
do_open
protected virtual function void do_open(
uvm_tr_stream stream,
time open_time,
string type_name
)
Callback triggered via uvm_tr_stream::open_recorder.
Text-backend specific implementation.
do_close
protected virtual function void do_close(
time close_time
)
Callback triggered via uvm_recorder::close.
Text-backend specific implementation.
UVM 1.2 Class Reference
518
do_free
protected virtual function void do_free()
Callback triggered via uvm_recorder::free.
Text-backend specific implementation.
do_record_field
protected virtual function void do_record_field(
string name,
uvm_bitstream_t value,
int size,
uvm_radix_enum radix
)
Records an integral field (less than or equal to 4096 bits).
Text-backend specific implementation.
do_record_field_int
protected virtual function void do_record_field_int(
string name,
uvm_integral_t value,
int size,
uvm_radix_enum radix
)
Records an integral field (less than or equal to 64 bits).
Text-backend specific implementation.
do_record_field_real
protected virtual function void do_record_field_real(
string name,
real value
)
Record a real field.
Text-backened specific implementation.
do_record_object
protected virtual function void do_record_object(
string name,
uvm_object value
)
Record an object field.
Text-backend specific implementation.
The method uses identifier to determine whether or not to record the object instance id,
UVM 1.2 Class Reference
519
and recursion_policy to determine whether or not to recurse into the object.
do_record_string
protected virtual function void do_record_string(
string name,
string value
)
Records a string field.
Text-backend specific implementation.
do_record_time
protected virtual function void do_record_time(
string name,
time value
)
Records a time field.
Text-backend specific implementation.
do_record_generic
protected virtual function void do_record_generic(
string name,
string value,
string type_name
)
Records a name/value pair, where value has been converted to a string.
Text-backend specific implementation.
ImpLEmENtAtION SpEcIFIc API
write_attribute
function void write_attribute(
string nm,
uvm_bitstream_t value, uvm_radix_enum radix, numbits = $bits(uvm_bitstream_t)
integer )
Outputs an integral attribute to the textual log
Parameters
nm
Name of the attribute
value
Value
radix
Radix of the output
numbits
number of valid bits
UVM 1.2 Class Reference
520
write_attribute_int
function void write_attribute_int(
string nm,
uvm_integral_t value, uvm_radix_enum radix, numbits = $bits(uvm_bitstream_t)
integer )
Outputs an integral attribute to the textual log
Parameters
nm
Name of the attribute
value
Value
radix
Radix of the output
numbits
number of valid bits
UVM 1.2 Class Reference
521
22.4 uvm_packer
The uvm_packer class provides a policy object for packing and unpacking uvm_objects. The policies determine how packing and unpacking should be done. Packing an object
causes the object to be placed into a bit (byte or int) array. If the `uvm_field_* macro
are used to implement pack and unpack, by default no metadata information is stored
for the packing of dynamic objects (strings, arrays, class objects).
Summary
uvm_packer
The uvm_packer class provides a policy object for packing and unpacking
uvm_objects.
PACKING
pack_field
pack_field_int
pack_bits
pack_bytes
pack_ints
pack_string
pack_time
pack_real
pack_object
UNpACKING
is_null
unpack_field
unpack_field_int
unpack_bits
unpack_bytes
unpack_ints
unpack_string
unpack_time
unpack_real
unpack_object
get_packed_size
VARIABLEs
physical
abstract
use_metadata
big_endian
UVM 1.2 Class Reference
Packs an integral value (less than or equal to 4096 bits)
into the packed array.
Packs the integral value (less than or equal to 64 bits)
into the pack array.
Packs bits from upacked array of bits into the pack array.
Packs bits from an upacked array of bytes into the pack
array.
Packs bits from an unpacked array of ints into the pack
array.
Packs a string value into the pack array.
Packs a time value as 64 bits into the pack array.
Packs a real value as 64 bits into the pack array.
Packs an object value into the pack array.
This method is used during unpack operations to peek at
the next 4-bit chunk of the pack data and determine if it
is 0.
Unpacks bits from the pack array and returns the bitstream that was unpacked.
Unpacks bits from the pack array and returns the bitstream that was unpacked.
Unpacks bits from the pack array into an unpacked array
of bits.
Unpacks bits from the pack array into an unpacked array
of bytes.
Unpacks bits from the pack array into an unpacked array
of ints.
Unpacks a string.
Unpacks the next 64 bits of the pack array and places
them into a time variable.
Unpacks the next 64 bits of the pack array and places
them into a real variable.
Unpacks an object and stores the result into value.
Returns the number of bits that were packed.
This bit provides a filtering mechanism for fields.
This bit provides a filtering mechanism for fields.
This flag indicates whether to encode metadata when
packing dynamic data, or to decode metadata when
unpacking.
This bit determines the order that integral data is packed
(using pack_field, pack_field_int, pack_time, or
pack_real) and how the data is unpacked from the pack
array (using unpack_field, unpack_field_int,
unpack_time, or unpack_real).
522
PACKING
pack_field
virtual function void pack_field (
uvm_bitstream_t value,
int size
)
Packs an integral value (less than or equal to 4096 bits) into the packed array. size is
the number of bits of value to pack.
pack_field_int
virtual function void pack_field_int (
uvm_integral_t value,
int size
)
Packs the integral value (less than or equal to 64 bits) into the pack array. The size is
the number of bits to pack, usually obtained by $bits. This optimized version of
pack_field is useful for sizes up to 64 bits.
pack_bits
virtual function void pack_bits(
ref bit value[], = -1
input int size
)
Packs bits from upacked array of bits into the pack array.
See pack_ints for additional information.
pack_bytes
virtual function void pack_bytes(
ref byte value[], = -1
input int size
)
Packs bits from an upacked array of bytes into the pack array.
See pack_ints for additional information.
pack_ints
virtual function void pack_ints(
ref int value[], = -1
input int size
)
UVM 1.2 Class Reference
523
Packs bits from an unpacked array of ints into the pack array.
The bits are appended to the internal pack array. This method allows for fields of
arbitrary length to be passed in, using the SystemVerilog stream operator.
For example
bit[511:0] my_field;
begin
int my_stream[];
{ << int {my_stream}} = my_field;
packer.pack_ints(my_stream);
end
When appending the stream to the internal pack array, the packer will obey the value of
big_endian (appending the array from MSB to LSB if set).
An optional size parameter is provided, which defaults to ‘-1’. If set to any value greater
than ‘-1’ (including 0), then the packer will use the size as the number of bits to pack,
otherwise the packer will simply pack the entire stream.
An error will be asserted if the size has been specified, and exceeds the size of the
source array.
pack_string
virtual function void pack_string (
string value
)
Packs a string value into the pack array.
When the metadata flag is set, the packed string is terminated by a null character to
mark the end of the string.
This is useful for mixed language communication where unpacking may occur outside of
SystemVerilog UVM.
pack_time
virtual function void pack_time (
time value
)
Packs a time value as 64 bits into the pack array.
pack_real
virtual function void pack_real (
real value
)
Packs a real value as 64 bits into the pack array.
The real value is converted to a 6-bit scalar value using the function $real2bits before it
is packed into the array.
UVM 1.2 Class Reference
524
pack_object
virtual function void pack_object (
uvm_object value
)
Packs an object value into the pack array.
A 4-bit header is inserted ahead of the string to indicate the number of bits that was
packed. If a null object was packed, then this header will be 0.
This is useful for mixed-language communication where unpacking may occur outside of
SystemVerilog UVM.
UNpACKING
is_null
virtual function bit is_null ()
This method is used during unpack operations to peek at the next 4-bit chunk of the
pack data and determine if it is 0.
If the next four bits are all 0, then the return value is a 1; otherwise it is 0.
This is useful when unpacking objects, to decide whether a new object needs to be
allocated or not.
unpack_field
virtual function uvm_bitstream_t unpack_field (
int size
)
Unpacks bits from the pack array and returns the bit-stream that was unpacked. size is
the number of bits to unpack; the maximum is 4096 bits.
unpack_field_int
virtual function uvm_integral_t unpack_field_int (
int size
)
Unpacks bits from the pack array and returns the bit-stream that was unpacked.
size is the number of bits to unpack; the maximum is 64 bits. This is a more efficient
variant than unpack_field when unpacking into smaller vectors.
unpack_bits
virtual function void unpack_bits(
ref bit value[], = -1
input int size
UVM 1.2 Class Reference
525
)
Unpacks bits from the pack array into an unpacked array of bits.
unpack_bytes
virtual function void unpack_bytes(
ref byte value[], input int size
= -1
)
Unpacks bits from the pack array into an unpacked array of bytes.
unpack_ints
virtual function void unpack_ints(
ref int value[], input int size
= -1
)
Unpacks bits from the pack array into an unpacked array of ints.
The unpacked array is unpacked from the internal pack array. This method allows for
fields of arbitrary length to be passed in without expanding into a pre-defined integral
type first.
For example
bit[511:0] my_field;
begin
int my_stream[] = new[16]; // 512/32 = 16
packer.unpack_ints(my_stream);
my_field = {<<{my_stream}};
end
When unpacking the stream from the internal pack array, the packer will obey the value
of big_endian (unpacking the array from MSB to LSB if set).
An optional size parameter is provided, which defaults to ‘-1’. If set to any value greater
than ‘-1’ (including 0), then the packer will use the size as the number of bits to unpack,
otherwise the packer will simply unpack the entire stream.
An error will be asserted if the size has been specified, and exceeds the size of the
target array.
unpack_string
virtual function string unpack_string (
int num_chars = -1
)
Unpacks a string.
num_chars bytes are unpacked into a string. If num_chars is -1 then unpacking stops
on at the first null character that is encountered.
UVM 1.2 Class Reference
526
unpack_time
virtual function time unpack_time ()
Unpacks the next 64 bits of the pack array and places them into a time variable.
unpack_real
virtual function real unpack_real ()
Unpacks the next 64 bits of the pack array and places them into a real variable.
The 64 bits of packed data are converted to a real using the $bits2real system function.
unpack_object
virtual function void unpack_object (
uvm_object value
)
Unpacks an object and stores the result into value.
value must be an allocated object that has enough space for the data being unpacked. The first four bits of packed data are used to determine if a null object was packed into
the array.
The is_null function can be used to peek at the next four bits in the pack array before
calling this method.
get_packed_size
virtual function int get_packed_size()
Returns the number of bits that were packed.
VARIABLEs
physical
bit physical = 1
This bit provides a filtering mechanism for fields.
The abstract and physical settings allow an object to distinguish between two different
classes of fields. It is up to you, in the uvm_object::do_pack and
uvm_object::do_unpack methods, to test the setting of this field if you want to use it as
a filter.
abstract
bit abstract
UVM 1.2 Class Reference
527
This bit provides a filtering mechanism for fields.
The abstract and physical settings allow an object to distinguish between two different
classes of fields. It is up to you, in the uvm_object::do_pack and
uvm_object::do_unpack routines, to test the setting of this field if you want to use it as
a filter.
use_metadata
bit use_metadata
This flag indicates whether to encode metadata when packing dynamic data, or to
decode metadata when unpacking. Implementations of uvm_object::do_pack and
uvm_object::do_unpack should regard this bit when performing their respective
operation. When set, metadata should be encoded as follows:
For strings, pack an additional null byte after the string is packed.
For objects, pack 4 bits prior to packing the object itself. Use 4’b0000 to indicate
the object being packed is null, otherwise pack 4’b0001 (the remaining 3 bits are
reserved).
For queues, dynamic arrays, and associative arrays, pack 32 bits indicating the
size of the array prior to packing individual elements.
big_endian
bit big_endian = 1
This bit determines the order that integral data is packed (using pack_field,
pack_field_int, pack_time, or pack_real) and how the data is unpacked from the pack
array (using unpack_field, unpack_field_int, unpack_time, or unpack_real). When the bit
is set, data is associated msb to lsb; otherwise, it is associated lsb to msb.
The following code illustrates how data can be associated msb to lsb and lsb to msb:
class mydata extends uvm_object;
logic[15:0] value = 'h1234;
function void do_pack (uvm_packer packer);
packer.pack_field_int(value, 16);
endfunction
function void do_unpack (uvm_packer packer);
value = packer.unpack_field_int(16);
endfunction
endclass
mydata d = new;
bit bits[];
initial begin
d.pack(bits); // 'b0001001000110100
uvm_default_packer.big_endian = 0;
d.pack(bits); // 'b0010110001001000
end
UVM 1.2 Class Reference
528
22.5 UVM Links
The uvm_link_base class, and its extensions, are provided as a mechanism to allow for
compile-time safety when trying to establish links between records within a
uvm_tr_database.
Contents
UVM Links
The uvm_link_base class, and its extensions, are
provided as a mechanism to allow for compile-time
safety when trying to establish links between records
within a uvm_tr_database.
uvm_link_base
The uvm_link_base class presents a simple API for
defining a link between any two objects.
The uvm_parent_child_link is used to represent a
Parent/Child relationship between two objects.
The uvm_cause_effect_link is used to represent a
Cause/Effect relationship between two objects.
The uvm_related_link is used to represent a generic “is
related” link between two objects.
uvm_parent_child_link
uvm_cause_effect_link
uvm_related_link
uvm_link_base
The uvm_link_base class presents a simple API for defining a link between any two
objects.
Using extensions of this class, a uvm_tr_database can determine the type of links being
passed, without relying on “magic” string names.
For example
virtual function void do_establish_link(uvm_link_base link);
uvm_parent_child_link pc_link;
uvm_cause_effect_link ce_link;
if ($cast(pc_link, link)) begin
// Record the parent-child relationship
end
else if ($cast(ce_link, link)) begin
// Record the cause-effect relationship
end
else begin
// Unsupported relationship!
end
endfunction : do_establish_link
Summary
uvm_link_base
The uvm_link_base class presents a simple API for defining a link between any
two objects.
ClAss HIERARchY
UVM 1.2 Class Reference
529
uvm_void
uvm_object
uvm_link_base
ClAss DEclARATION
virtual class uvm_link_base extends uvm_object
new
Constructor
AccEssORs
set_lhs
get_lhs
set_rhs
get_rhs
set
ImPlEmENTATION
CAllBAcKs
do_set_lhs
do_get_lhs
do_set_rhs
do_get_rhs
Sets the left-hand-side of the link
Gets the left-hand-side of the link
Sets the right-hand-side of the link
Gets the right-hand-side of the link
Convenience method for setting both sides in one
call.
Callback
Callback
Callback
Callback
for
for
for
for
setting the left-hand-side
retrieving the left-hand-side
setting the right-hand-side
retrieving the right-hand-side
new
function new(
string name = "unnamed-uvm_link_base"
)
Constructor
Parameters
name
Instance name
AccEssORs
set_lhs
function void set_lhs(
uvm_object lhs
)
Sets the left-hand-side of the link
Triggers the do_set_lhs callback.
get_lhs
function uvm_object get_lhs()
Gets the left-hand-side of the link
Triggers the do_get_lhs callback
UVM 1.2 Class Reference
530
set_rhs
function void set_rhs(
uvm_object rhs
)
Sets the right-hand-side of the link
Triggers the do_set_rhs callback.
get_rhs
function uvm_object get_rhs()
Gets the right-hand-side of the link
Triggers the do_get_rhs callback
set
function void set(
uvm_object lhs,
rhs
)
Convenience method for setting both sides in one call.
Triggers both the do_set_rhs and do_set_lhs callbacks.
ImPlEmENTATION CAllBAcKs
do_set_lhs
pure virtual function void do_set_lhs(
uvm_object lhs
)
Callback for setting the left-hand-side
do_get_lhs
pure virtual function uvm_object do_get_lhs()
Callback for retrieving the left-hand-side
do_set_rhs
pure virtual function void do_set_rhs(
uvm_object rhs
)
UVM 1.2 Class Reference
531
Callback for setting the right-hand-side
do_get_rhs
pure virtual function uvm_object do_get_rhs()
Callback for retrieving the right-hand-side
uvm_parent_child_link
The uvm_parent_child_link is used to represent a Parent/Child relationship between two
objects.
Summary
uvm_parent_child_link
The uvm_parent_child_link is used to represent a Parent/Child relationship
between two objects.
ClAss HIERARchY
uvm_void
uvm_object
uvm_link_base
uvm_parent_child_link
ClAss DEclARATION
class uvm_parent_child_link extends uvm_link_base
new
get_link
ImPlEmENTATION CAllBAcKs
do_set_lhs
do_get_lhs
do_set_rhs
do_get_rhs
Constructor
Constructs a pre-filled link
Sets the left-hand-side (Parent)
Retrieves the left-hand-side (Parent)
Sets the right-hand-side (Child)
Retrieves the right-hand-side (Child)
new
function new(
string name = "unnamed-uvm_parent_child_link"
)
Constructor
Parameters
name
Instance name
UVM 1.2 Class Reference
532
get_link
static function uvm_parent_child_link get_link(
uvm_object lhs, uvm_object rhs, string name = "pc_link"
)
Constructs a pre-filled link
This allows for simple one-line link creations.
my_db.establish_link(uvm_parent_child_link::get_link(record1, record2));
Parameters
lhs
Left hand side reference
rhs
Right hand side reference
name
Optional name for the link object
ImPlEmENTATION CAllBAcKs
do_set_lhs
virtual function void do_set_lhs(
uvm_object lhs
)
Sets the left-hand-side (Parent)
do_get_lhs
virtual function uvm_object do_get_lhs()
Retrieves the left-hand-side (Parent)
do_set_rhs
virtual function void do_set_rhs(
uvm_object rhs
)
Sets the right-hand-side (Child)
do_get_rhs
virtual function uvm_object do_get_rhs()
Retrieves the right-hand-side (Child)
UVM 1.2 Class Reference
533
uvm_cause_effect_link
The uvm_cause_effect_link is used to represent a Cause/Effect relationship between two
objects.
Summary
uvm_cause_effect_link
The uvm_cause_effect_link is used to represent a Cause/Effect relationship
between two objects.
ClAss HIERARchY
uvm_void
uvm_object
uvm_link_base
uvm_cause_effect_link
ClAss DEclARATION
class uvm_cause_effect_link extends uvm_link_base
new
get_link
ImPlEmENTATION CAllBAcKs
do_set_lhs
do_get_lhs
do_set_rhs
do_get_rhs
Constructor
Constructs a pre-filled link
Sets the left-hand-side (Cause)
Retrieves the left-hand-side (Cause)
Sets the right-hand-side (Effect)
Retrieves the right-hand-side (Effect)
new
function new(
string name = "unnamed-uvm_cause_effect_link"
)
Constructor
Parameters
name
Instance name
get_link
static function uvm_cause_effect_link get_link(
uvm_object lhs, uvm_object rhs, name = "ce_link"
string )
Constructs a pre-filled link
UVM 1.2 Class Reference
534
This allows for simple one-line link creations.
my_db.establish_link(uvm_cause_effect_link::get_link(record1, record2));
Parameters
lhs
Left hand side reference
rhs
Right hand side reference
name
Optional name for the link object
ImPlEmENTATION CAllBAcKs
do_set_lhs
virtual function void do_set_lhs(
uvm_object lhs
)
Sets the left-hand-side (Cause)
do_get_lhs
virtual function uvm_object do_get_lhs()
Retrieves the left-hand-side (Cause)
do_set_rhs
virtual function void do_set_rhs(
uvm_object rhs
)
Sets the right-hand-side (Effect)
do_get_rhs
virtual function uvm_object do_get_rhs()
Retrieves the right-hand-side (Effect)
uvm_related_link
The uvm_related_link is used to represent a generic “is related” link between two
objects.
UVM 1.2 Class Reference
535
Summary
uvm_related_link
The uvm_related_link is used to represent a generic “is related” link between two
objects.
ClAss HIERARchY
uvm_void
uvm_object
uvm_link_base
uvm_related_link
ClAss DEclARATION
class uvm_related_link extends uvm_link_base
new
get_link
ImPlEmENTATION CAllBAcKs
do_set_lhs
do_get_lhs
do_set_rhs
do_get_rhs
Constructor
Constructs a pre-filled link
Sets the left-hand-side
Retrieves the left-hand-side
Sets the right-hand-side
Retrieves the right-hand-side
new
function new(
string name = "unnamed-uvm_related_link"
)
Constructor
Parameters
name
Instance name
get_link
static function uvm_related_link get_link(
uvm_object lhs, uvm_object rhs, string name = "ce_link"
)
Constructs a pre-filled link
This allows for simple one-line link creations.
my_db.establish_link(uvm_related_link::get_link(record1, record2));
Parameters
lhs
Left hand side reference
UVM 1.2 Class Reference
536
rhs
Right hand side reference
name
Optional name for the link object
ImPlEmENTATION CAllBAcKs
do_set_lhs
virtual function void do_set_lhs(
uvm_object lhs
)
Sets the left-hand-side
do_get_lhs
virtual function uvm_object do_get_lhs()
Retrieves the left-hand-side
do_set_rhs
virtual function void do_set_rhs(
uvm_object rhs
)
Sets the right-hand-side
do_get_rhs
virtual function uvm_object do_get_rhs()
Retrieves the right-hand-side
UVM 1.2 Class Reference
537
23. Data Access Policies
The UVM provides special objects as utility classes for applying common policies to data
access (such as ‘locking’ data, or ensuring that it remains constant after being read).
This is not intended to be a comprehensive list of all Data Access policies, and the user is
encouraged to write their own, and potentially contribute them to the community.
Summary
Data Access Policies
The UVM provides special objects as utility classes for applying common policies
to data access (such as ‘locking’ data, or ensuring that it remains constant after
being read).
UVM 1.2 Class Reference
538
23.1 uvm_set_get_dap_base
Provides the ‘set’ and ‘get’ interface for Data Access Policies (DAPs)
The ‘Set/Get’ base class simply provides a common interface for the various DAPs to
implement. This provides a mechanism for consistent implementations of similar DAPs.
Summary
uvm_set_get_dap_base
Provides the ‘set’ and ‘get’ interface for Data Access Policies (DAPs)
CLAss HIERARchY
uvm_void
uvm_object
uvm_set_get_dap_base
CLAss DEcLARATION
virtual class uvm_set_get_dap_base#(
type T = int
) extends uvm_object
new
Constructor
SET/GET
INTERFAcE
All implementations of the uvm_set_get_dap_base class must
provide an implementation of the four basic “Set and Get”
accessors.
Sets the value contained within the resource.
Attempts to set the value contained within the resource.
Retrieves the value contained within the resource.
Attempts to retrieve the value contained within the resource.
set
try_set
get
try_get
new
function new(
string name = "unnamed-uvm_set_get_dap_base#(T)"
)
Constructor
SET/GET INTERFAcE
All implementations of the uvm_set_get_dap_base class must provide an implementation
of the four basic “Set and Get” accessors.
set
pure virtual function void set(
T value
)
Sets the value contained within the resource.
UVM 1.2 Class Reference
539
Depending on the DAP policies, an error may be reported if it is illegal to ‘set’ the value
at this time.
try_set
pure virtual function bit try_set(
T value
)
Attempts to set the value contained within the resource.
If the DAP policies forbid setting at this time, then the method will return 0, however no
errors will be reported. Otherwise, the method will return 1, and will be treated like a
standard set call.
get
pure virtual function T get()
Retrieves the value contained within the resource.
Depending on the DAP policies, an error may be reported if it is illegal to ‘get’ the value
at this time.
try_get
pure virtual function bit try_get(
output T value
)
Attempts to retrieve the value contained within the resource.
If the DAP policies forbid retrieving at this time, then the method will return 0, however
no errors will be reported. Otherwise, the method will return 1, and will be treated like a
standard get call.
UVM 1.2 Class Reference
540
23.2 uvm_simple_lock_dap
Provides a ‘Simple Lock’ Data Access Policy.
The ‘Simple Lock’ Data Access Policy allows for any number of ‘sets’, so long as the
value is not ‘locked’. The value can be retrieved using ‘get’ at any time.
The UVM uses this policy to protect the file name value in the uvm_text_tr_database.
Summary
uvm_simple_lock_dap
Provides a ‘Simple Lock’ Data Access Policy.
CLAss HIERARchY
uvm_set_get_dap_base#(T)
uvm_simple_lock_dap
CLAss DEcLARATION
class uvm_simple_lock_dap#(
type T = int
) extends uvm_set_get_dap_base#(T)
new
Constructor
SET/GET
INTERFAcE
set
try_set
get
try_get
Updates the value stored within the DAP.
Attempts to update the value stored within the DAP.
Returns the current value stored within the DAP
Retrieves the current value stored within the DAP
LOcKINg
lock
unlock
is_locked
Locks the data value
Unlocks the data value
Returns the state of the lock.
INTROsPEcTION
The uvm_simple_lock_dap cannot support the standard UVM
instrumentation methods (copy, clone, pack and unpack), due
to the fact that they would potentially violate the access policy.
new
function new(
string name = "unnamed-uvm_simple_lock_dap#(T)"
)
Constructor
SET/GET INTERFAcE
set
virtual function void set(
UVM 1.2 Class Reference
541
T value
)
Updates the value stored within the DAP.
set will result in an error if the DAP has been locked.
try_set
virtual function bit try_set(
T value
)
Attempts to update the value stored within the DAP.
try_set will return a 1 if the value was successfully updated, or a 0 if the value cannot
be updated due to the DAP being locked. No errors will be reported if try_set fails.
get
virtual function T get()
Returns the current value stored within the DAP
try_get
virtual function bit try_get(
output T value
)
Retrieves the current value stored within the DAP
try_get will always return 1.
LOcKINg
lock
function void lock()
Locks the data value
The data value cannot be updated via set or try_set while locked.
unlock
function void unlock()
Unlocks the data value
UVM 1.2 Class Reference
542
is_locked
function bit is_locked()
Returns the state of the lock.
Returns
1
The value is locked
0
The value is unlocked
INTROsPEcTION
The uvm_simple_lock_dap cannot support the standard UVM instrumentation methods
(copy, clone, pack and unpack), due to the fact that they would potentially violate the
access policy.
A call to any of these methods will result in an error.
UVM 1.2 Class Reference
543
23.3 uvm_get_to_lock_dap
Provides a ‘Get-To-Lock’ Data Access Policy.
The ‘Get-To-Lock’ Data Access Policy allows for any number of ‘sets’, until the value is
retrieved via a ‘get’. Once ‘get’ has been called, it is illegal to ‘set’ a new value.
The UVM uses this policy to protect the starting phase and automatic objection values in
uvm_sequence_base.
Summary
uvm_get_to_lock_dap
Provides a ‘Get-To-Lock’ Data Access Policy.
CLAss HIERARchY
uvm_set_get_dap_base#(T)
uvm_get_to_lock_dap
CLAss DEcLARATION
class uvm_get_to_lock_dap#(
type T = int
) extends uvm_set_get_dap_base#(T)
new
SET/GET
INTERFAcE
set
try_set
get
try_get
INTROsPEcTION
Constructor
Updates the value stored within the DAP.
Attempts to update the value stored within the DAP.
Returns the current value stored within the DAP, and ‘locks’
the DAP.
Retrieves the current value stored within the DAP, and ‘locks’
the DAP.
The uvm_get_to_lock_dap cannot support the standard UVM
instrumentation methods (copy, clone, pack and unpack), due
to the fact that they would potentially violate the access policy.
new
function new(
string name = "unnamed-uvm_get_to_lock_dap#(T)"
)
Constructor
SET/GET INTERFAcE
set
virtual function void set(
T value
UVM 1.2 Class Reference
544
)
Updates the value stored within the DAP.
set will result in an error if the value has already been retrieved via a call to get.
try_set
virtual function bit try_set(
T value
)
Attempts to update the value stored within the DAP.
try_set will return a 1 if the value was successfully updated, or a 0 if the value cannot
be updated due to get having been called. No errors will be reported if try_set fails.
get
virtual function T get()
Returns the current value stored within the DAP, and ‘locks’ the DAP.
After a ‘get’, the value contained within the DAP cannot be changed.
try_get
virtual function bit try_get(
output T value
)
Retrieves the current value stored within the DAP, and ‘locks’ the DAP.
try_get will always return 1.
INTROsPEcTION
The uvm_get_to_lock_dap cannot support the standard UVM instrumentation methods
(copy, clone, pack and unpack), due to the fact that they would potentially violate the
access policy.
A call to any of these methods will result in an error.
UVM 1.2 Class Reference
545
23.4 uvm_set_before_get_dap
Provides a ‘Set Before Get’ Data Access Policy.
The ‘Set Before Get’ Data Access Policy enforces that the value must be written at least
once before it is read. This DAP can be used to pass shared information to multiple
components during standard configuration, even if that information hasn’t yet been
determined.
Such DAP objects can be useful for passing a ‘placeholder’ reference, before the
information is actually available. A good example of this would be the virtual sequencer:
typedef uvm_set_before_get_dap#(uvm_sequencer_base) seqr_dap_t;
virtual_seqeuncer_type virtual_sequencer;
agent_type my_agent;
seqr_dap_t seqr_dap;
function void my_env::build_phase(uvm_phase phase);
seqr_dap = seqr_dap_t::type_id::create("seqr_dap");
// Pass the DAP, because we don't have a reference to the
// real sequencer yet...
uvm_config_db#(seqr_dap_t)::set(this, "virtual_sequencer", "seqr_dap",
seqr_dap);
// Create the virtual sequencer
virtual_sequencer =
virtual_sequencer_type::type_id::create("virtual_sequencer", this);
// Create the agent
agent = agent_type::type_id::create("agent", this);
endfunction
function void my_env::connect_phase(uvm_phase phase);
// Now that we know the value is good, we can set it
seqr_dap.set(agent.sequencer);
endfunction
In the example above, the environment didn’t have a reference to the agent’s sequencer
yet, because the agent hadn’t executed its build_phase. The environment needed to
give the virtual sequencer a “Set before get” DAP so that the virtual sequencer (and any
sequences one it), could eventually see the agent’s sequencer, when the reference was
finally available. If the virtual sequencer (or any sequences on it) attempted to ‘get’ the
reference to the agent’s sequencer prior to the environment assigning it, an error would
have been reported.
Summary
uvm_set_before_get_dap
Provides a ‘Set Before Get’ Data Access Policy.
CLAss HIERARchY
uvm_set_get_dap_base#(T)
uvm_set_before_get_dap
CLAss DEcLARATION
class uvm_set_before_get_dap#(
type T = int
) extends uvm_set_get_dap_base#(T)
new
Constructor
SET/GET
INTERFAcE
UVM 1.2 Class Reference
546
set
try_set
get
try_get
INTROsPEcTION
Updates the value stored within the DAP.
Attempts to update the value stored within the DAP.
Returns the current value stored within the DAP.
Attempts to retrieve the current value stored within the DAP
The uvm_set_before_get_dap cannot support the standard UVM
instrumentation methods (copy, clone, pack and unpack), due
to the fact that they would potentially violate the access policy.
new
function new(
string name = "unnamed-uvm_set_before_get_dap#(T)"
)
Constructor
SET/GET INTERFAcE
set
virtual function void set(
T value
)
Updates the value stored within the DAP.
try_set
virtual function bit try_set(
T value
)
Attempts to update the value stored within the DAP.
try_set will always return a 1.
get
virtual function T get()
Returns the current value stored within the DAP.
If ‘get’ is called before a call to set or try_set, then an error will be reported.
try_get
virtual function bit try_get(
output T value
)
Attempts to retrieve the current value stored within the DAP
UVM 1.2 Class Reference
547
If the value has not been ‘set’, then try_get will return a 0, otherwise it will return a 1,
and set value to the current value stored within the DAP.
INTROsPEcTION
The uvm_set_before_get_dap cannot support the standard UVM instrumentation methods
(copy, clone, pack and unpack), due to the fact that they would potentially violate the
access policy.
A call to any of these methods will result in an error.
UVM 1.2 Class Reference
548
24.1 Register Layer
The UVM register layer defines several base classes that, when properly extended,
abstract the read/write operations to registers and memories in a design-underverification.
A register model is typically composed of a hierarchy of blocks that usually map to the
design hierarchy. Blocks contain registers, register files and memories.
The UVM register layer classes are not usable as-is. They only provide generic and
introspection capabilities. They must be specialized via extensions to provide an abstract
view that corresponds to the actual registers and memories in a design. Due to the
large number of registers in a design and the numerous small details involved in properly
configuring the UVM register layer classes, this specialization is normally done by a model
generator. Model generators work from a specification of the registers and memories in
a design and are thus able to provide an up-to-date, correct-by-construction register
model. Model generators are outside the scope of the UVM library.
The class diagram of a register layer model is shown below.
Summary
Register Layer
The UVM register layer defines several base classes that, when properly
extended, abstract the read/write operations to registers and memories in a
UVM 1.2 Class Reference
549
design-under-verification.
UVM 1.2 Class Reference
550
24.2 Global Declarations for the Register Layer
This section defines globally available types, enums, and utility classes.
Summary
Global Declarations for the Register Layer
This section defines globally available types, enums, and utility classes.
TYPEs
uvm_reg_data_t
uvm_reg_data_logic_t
uvm_reg_addr_t
uvm_reg_addr_logic_t
uvm_reg_byte_en_t
uvm_reg_cvr_t
uvm_hdl_path_slice
ENUMErAtIONs
uvm_status_e
uvm_path_e
uvm_check_e
uvm_endianness_e
uvm_elem_kind_e
uvm_access_e
uvm_hier_e
uvm_predict_e
uvm_coverage_model_e
uvm_reg_mem_tests_e
2-state data value with `UVM_REG_DATA_WIDTH
bits
4-state data value with `UVM_REG_DATA_WIDTH
bits
2-state address value with
`UVM_REG_ADDR_WIDTH bits
4-state address value with
`UVM_REG_ADDR_WIDTH bits
2-state byte_enable value with
`UVM_REG_BYTENABLE_WIDTH bits
Coverage model value set with
`UVM_REG_CVR_WIDTH bits.
Slice of an HDL path
Return status for register operations
Path used for register operation
Read-only or read-and-check
Specifies byte ordering
Type of element being read or written
Type of operation begin performed
Whether to provide the requested information
from a hierarchical context.
How the mirror is to be updated
Coverage models available or desired.
Select which pre-defined test sequence to
execute.
UtIlItY ClAssEs
TYPEs
uvm_reg_data_t
2-state data value with `UVM_REG_DATA_WIDTH bits
uvm_reg_data_logic_t
4-state data value with `UVM_REG_DATA_WIDTH bits
uvm_reg_addr_t
2-state address value with `UVM_REG_ADDR_WIDTH bits
UVM 1.2 Class Reference
551
uvm_reg_addr_logic_t
4-state address value with `UVM_REG_ADDR_WIDTH bits
uvm_reg_byte_en_t
2-state byte_enable value with `UVM_REG_BYTENABLE_WIDTH bits
uvm_reg_cvr_t
Coverage model value set with `UVM_REG_CVR_WIDTH bits.
Symbolic values for individual coverage models are defined by the
uvm_coverage_model_e type.
The following bits in the set are assigned as follows
0-7
UVM pre-defined coverage models
8-15
Coverage models defined by EDA vendors, implemented in a register
model generator.
16-23
User-defined coverage models
24..
Reserved
uvm_hdl_path_slice
Slice of an HDL path
Struct that specifies the HDL variable that corresponds to all or a portion of a register.
path
Path to the HDL variable.
offset
Offset of the LSB in the register that this variable implements
size
Number of bits (toward the MSB) that this variable implements
If the HDL variable implements all of the register, offset and size are specified as -1. For
example:
r1.add_hdl_path('{ '{"r1", -1, -1} });
ENUMErAtIONs
uvm_status_e
Return status for register operations
UVM_IS_OK
UVM 1.2 Class Reference
Operation completed successfully
552
UVM_NOT_OK
Operation completed with error
UVM_HAS_X
Operation completed successfully bit had unknown bits.
uvm_path_e
Path used for register operation
UVM_FRONTDOOR
Use the front door
UVM_BACKDOOR
Use the back door
UVM_PREDICT
Operation derived from observations by a bus monitor
via the uvm_reg_predictor class.
UVM_DEFAULT_PATH
Operation specified by the context
uvm_check_e
Read-only or read-and-check
UVM_NO_CHECK
Read only
UVM_CHECK
Read and check
uvm_endianness_e
Specifies byte ordering
UVM_NO_ENDIAN
Byte ordering not applicable
UVM_LITTLE_ENDIAN
Least-significant bytes first in consecutive addresses
UVM_BIG_ENDIAN
Most-significant bytes first in consecutive addresses
UVM_LITTLE_FIFO
Least-significant bytes first at the same address
UVM_BIG_FIFO
Most-significant bytes first at the same address
uvm_elem_kind_e
Type of element being read or written
UVM_REG
Register
UVM_FIELD
Field
UVM_MEM
Memory location
uvm_access_e
Type of operation begin performed
UVM_READ
Read operation
UVM_WRITE
Write operation
uvm_hier_e
UVM 1.2 Class Reference
553
Whether to provide the requested information from a hierarchical context.
UVM_NO_HIER
Provide info from the local context
UVM_HIER
Provide info based on the hierarchical context
uvm_predict_e
How the mirror is to be updated
UVM_PREDICT_DIRECT
Predicted value is as-is
UVM_PREDICT_READ
Predict based on the specified value having been
read
UVM_PREDICT_WRITE
Predict based on the specified value having been
written
uvm_coverage_model_e
Coverage models available or desired. Multiple models may be specified by bitwise
OR’ing individual model identifiers.
UVM_NO_COVERAGE
None
UVM_CVR_REG_BITS
Individual register bits
UVM_CVR_ADDR_MAP
Individual register and memory addresses
UVM_CVR_FIELD_VALS
Field values
UVM_CVR_ALL
All coverage models
uvm_reg_mem_tests_e
Select which pre-defined test sequence to execute.
Multiple test sequences may be selected by bitwise OR’ing their respective symbolic
values.
UVM_DO_REG_HW_RESET
Run uvm_reg_hw_reset_seq
UVM_DO_REG_BIT_BASH
Run uvm_reg_bit_bash_seq
UVM_DO_REG_ACCESS
Run uvm_reg_access_seq
UVM_DO_MEM_ACCESS
Run uvm_mem_access_seq
UVM_DO_SHARED_ACCESS
Run uvm_reg_mem_shared_access_seq
UVM_DO_MEM_WALK
Run uvm_mem_walk_seq
UVM_DO_ALL_REG_MEM_TESTS
Run all of the above
Test sequences, when selected, are executed in the order in which they are specified
above.
UtIlItY ClAssEs
UVM 1.2 Class Reference
554
uvm_hdl_path_concat
Concatenation of HDL variables
A dArray of uvm_hdl_path_slice specifying a concatenation of HDL variables that
implement a register in the HDL.
Slices must be specified in most-to-least significant order. Slices must not overlap. Gaps may exist in the concatenation if portions of the registers are not implemented.
For example, the following register
Bits:
1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
+-+---+-------------+---+-------+
|A|xxx|
B
|xxx|
C
|
+-+---+-------------+---+-------+
If the register is implemented using a single HDL variable, The array should specify a
single slice with its offset and size specified as -1. For example:
concat.set('{ '{"r1", -1, -1} });
Summary
uvm_hdl_path_concat
Concatenation of HDL variables
ClAss DEclArAtION
class uvm_hdl_path_concat
VArIABlEs
slices
MEtHOds
set
add_slice
add_path
Array of individual slices, stored in most-to-least significant
order
Initialize the concatenation using an array literal
Append the specified slice literal to the path concatenation
Append the specified path to the path concatenation, for the
specified number of bits at the specified offset.
VArIABlEs
slices
uvm_hdl_path_slice slices[]
Array of individual slices, stored in most-to-least significant order
UVM 1.2 Class Reference
555
MEtHOds
set
function void set(
uvm_hdl_path_slice t[]
)
Initialize the concatenation using an array literal
add_slice
function void add_slice(
uvm_hdl_path_slice slice
)
Append the specified slice literal to the path concatenation
add_path
function void add_path(
string path, int unsigned offset = -1,
int unsigned size = -1
)
Append the specified path to the path concatenation, for the specified number of bits at
the specified offset.
UVM 1.2 Class Reference
556
25.1 uvm_reg_block
Block abstraction base class
A block represents a design hierarchy. It can contain registers, register files, memories
and sub-blocks.
A block has one or more address maps, each corresponding to a physical interface on the
block.
Summary
uvm_reg_block
Block abstraction base class
CLAss HIERARchY
uvm_void
uvm_object
uvm_reg_block
CLAss DEcLARATION
virtual class uvm_reg_block extends uvm_object
default_path
INITIALIZATION
new
configure
create_map
check_data_width
set_default_map
default_map
lock_model
is_locked
INTROsPEcTION
get_name
get_full_name
get_parent
get_root_blocks
find_blocks
find_block
get_blocks
get_maps
get_registers
get_fields
get_memories
get_virtual_registers
get_virtual_fields
get_block_by_name
get_map_by_name
get_reg_by_name
get_field_by_name
UVM 1.2 Class Reference
Default access path for the registers and memories in
this block.
Create a new instance and type-specific
configuration
Instance-specific configuration
Create an address map in this block
Check that the specified data width (in bits) is less
than or equal to the value of
`UVM_REG_DATA_WIDTH
Defines the default address map
Default address map
Lock a model and build the address map.
Return TRUE if the model is locked.
Get the simple name
Get the hierarchical name
Get the parent block
Get the all root blocks
Find the blocks whose hierarchical names match the
specified name glob.
Find the first block whose hierarchical names match
the specified name glob.
Get the sub-blocks
Get the address maps
Get the registers
Get the fields
Get the memories
Get the virtual registers
Get the virtual fields
Finds a sub-block with the specified simple name.
Finds an address map with the specified simple
name.
Finds a register with the specified simple name.
Finds a field with the specified simple name.
557
get_mem_by_name
get_vreg_by_name
get_vfield_by_name
COVERAGE
build_coverage
add_coverage
has_coverage
set_coverage
get_coverage
sample
sample_values
AccEss
get_default_path
reset
needs_update
update
mirror
write_reg_by_name
read_reg_by_name
write_mem_by_name
read_mem_by_name
BAcKdOOR
get_backdoor
set_backdoor
clear_hdl_path
add_hdl_path
has_hdl_path
get_hdl_path
get_full_hdl_path
set_default_hdl_path
get_default_hdl_path
set_hdl_path_root
is_hdl_path_root
Finds a memory with the specified simple name.
Finds a virtual register with the specified simple
name.
Finds a virtual field with the specified simple name.
Check if all of the specified coverage model must be
built.
Specify that additional coverage models are
available.
Check if block has coverage model(s)
Turns on coverage measurement.
Check if coverage measurement is on.
Functional coverage measurement method
Functional coverage measurement method for field
values
Default access path
Reset the mirror for this block.
Check if DUT registers need to be written
Batch update of register.
Update the mirrored values
Write the named register
Read the named register
Write the named memory
Read the named memory
Get the user-defined backdoor for all registers in
this block
Set the user-defined backdoor for all registers in this
block
Delete HDL paths
Add an HDL path
Check if a HDL path is specified
Get the incremental HDL path(s)
Get the full hierarchical HDL path(s)
Set the default design abstraction
Get the default design abstraction
Specify a root HDL path
Check if this block has an absolute path
default_path
uvm_path_e default_path = UVM_DEFAULT_PATH
Default access path for the registers and memories in this block.
INITIALIZATION
new
function new(
string name
= "",
int has_coverage = UVM_NO_COVERAGE
)
Create a new instance and type-specific configuration
UVM 1.2 Class Reference
558
Creates an instance of a block abstraction class with the specified name.
has_coverage specifies which functional coverage models are present in the extension of
the block abstraction class. Multiple functional coverage models may be specified by
adding their symbolic names, as defined by the uvm_coverage_model_e type.
configure
function void configure(
uvm_reg_block parent = null,
string hdl_path = ""
)
Instance-specific configuration
Specify the parent block of this block. A block without parent is a root block.
If the block file corresponds to a hierarchical RTL structure, its contribution to the HDL
path is specified as the hdl_path. Otherwise, the block does not correspond to a
hierarchical RTL structure (e.g. it is physically flattened) and does not contribute to the
hierarchical HDL path of any contained registers or memories.
create_map
virtual function uvm_reg_map create_map(
string name,
uvm_reg_addr_t base_addr,
int unsigned n_bytes,
uvm_endianness_e endian,
bit byte_addressing = 1
)
Create an address map in this block
Create an address map with the specified name, then configures it with the following
properties.
base_addr
the base address for the map. All registers, memories, and
sub-blocks within the map will be at offsets to this address
n_bytes
the byte-width of the bus on which this map is used
endian
the endian format. See uvm_endianness_e for possible
values
byte_addressing
specifies whether consecutive addresses refer are 1 byte
apart (TRUE) or n_bytes apart (FALSE). Default is TRUE.
APB = create_map("APB", 0, 1, UVM_LITTLE_ENDIAN, 1);
check_data_width
protected static function bit check_data_width(
int unsigned width
)
Check that the specified data width (in bits) is less than or equal to the value of
`UVM_REG_DATA_WIDTH
UVM 1.2 Class Reference
559
This method is designed to be called by a static initializer
class my_blk extends uvm_reg_block;
local static bit m_data_width = check_data_width(356);
...
endclass
set_default_map
function void set_default_map (
uvm_reg_map map
)
Defines the default address map
Set the specified address map as the default_map for this block. The address map must
be a map of this address block.
default_map
uvm_reg_map default_map
Default address map
Default address map for this block, to be used when no address map is specified for a
register operation and that register is accessible from more than one address map.
It is also the implicit address map for a block with a single, unnamed address map
because it has only one physical interface.
lock_model
virtual function void lock_model()
Lock a model and build the address map.
Recursively lock an entire register model and build the address maps to enable the
uvm_reg_map::get_reg_by_offset() and uvm_reg_map::get_mem_by_offset() methods.
Once locked, no further structural changes, such as adding registers or memories, can be
made.
It is not possible to unlock a model.
is_locked
function bit is_locked()
Return TRUE if the model is locked.
INTROsPEcTION
UVM 1.2 Class Reference
560
get_name
Get the simple name
Return the simple object name of this block.
get_full_name
virtual function string get_full_name()
Get the hierarchical name
Return the hierarchal name of this block. The base of the hierarchical name is the root
block.
get_parent
virtual function uvm_reg_block get_parent()
Get the parent block
If this a top-level block, returns null.
get_root_blocks
static function void get_root_blocks(
ref uvm_reg_block blks[$]
)
Get the all root blocks
Returns an array of all root blocks in the simulation.
find_blocks
static function int find_blocks(
input string name,
ref uvm_reg_block blks[$], input uvm_reg_block root
= null,
input uvm_object accessor = null
)
Find the blocks whose hierarchical names match the specified name glob. If a root block
is specified, the name of the blocks are relative to that block, otherwise they are
absolute.
Returns the number of blocks found.
find_block
static function uvm_reg_block find_block(
input string name,
input uvm reg block root
= null,
UVM 1.2 Class Reference
561
input uvm_object )
accessor = null
Find the first block whose hierarchical names match the specified name glob. If a root
block is specified, the name of the blocks are relative to that block, otherwise they are
absolute.
Returns the first block found or null otherwise. A warning is issued if more than one
block is found.
get_blocks
virtual function void get_blocks (
ref uvm_reg_block blks[$], input uvm_hier_e hier
= UVM_HIER
)
Get the sub-blocks
Get the blocks instantiated in this blocks. If hier is TRUE, recursively includes any subblocks.
get_maps
virtual function void get_maps (
ref uvm_reg_map maps[$]
)
Get the address maps
Get the address maps instantiated in this block.
get_registers
virtual function void get_registers (
ref uvm_reg regs[$], = UVM_HIER
input uvm_hier_e hier
)
Get the registers
Get the registers instantiated in this block. If hier is TRUE, recursively includes the
registers in the sub-blocks.
Note that registers may be located in different and/or multiple address maps. To get the
registers in a specific address map, use the uvm_reg_map::get_registers() method.
get_fields
virtual function void get_fields (
ref uvm_reg_field fields[$], hier
= UVM_HIER
input uvm_hier_e )
Get the fields
Get the fields in the registers instantiated in this block. If hier is TRUE, recursively
UVM 1.2 Class Reference
562
includes the fields of the registers in the sub-blocks.
get_memories
virtual function void get_memories (
ref uvm_mem mems[$], input uvm_hier_e hier
= UVM_HIER
)
Get the memories
Get the memories instantiated in this block. If hier is TRUE, recursively includes the
memories in the sub-blocks.
Note that memories may be located in different and/or multiple address maps. To get
the memories in a specific address map, use the uvm_reg_map::get_memories()
method.
get_virtual_registers
virtual function void get_virtual_registers(
ref uvm_vreg regs[$], = UVM_HIER
input uvm_hier_e hier
)
Get the virtual registers
Get the virtual registers instantiated in this block. If hier is TRUE, recursively includes
the virtual registers in the sub-blocks.
get_virtual_fields
virtual function void get_virtual_fields (
ref uvm_vreg_field fields[$], hier
= UVM_HIER
input uvm_hier_e )
Get the virtual fields
Get the virtual fields from the virtual registers instantiated in this block. If hier is TRUE,
recursively includes the virtual fields in the virtual registers in the sub-blocks.
get_block_by_name
virtual function uvm_reg_block get_block_by_name (
string name
)
Finds a sub-block with the specified simple name.
The name is the simple name of the block, not a hierarchical name. relative to this
block. If no block with that name is found in this block, the sub-blocks are searched for
a block of that name and the first one to be found is returned.
If no blocks are found, returns null.
UVM 1.2 Class Reference
563
get_map_by_name
virtual function uvm_reg_map get_map_by_name (
string name
)
Finds an address map with the specified simple name.
The name is the simple name of the address map, not a hierarchical name. relative to
this block. If no map with that name is found in this block, the sub-blocks are searched
for a map of that name and the first one to be found is returned.
If no address maps are found, returns null.
get_reg_by_name
virtual function uvm_reg get_reg_by_name (
string name
)
Finds a register with the specified simple name.
The name is the simple name of the register, not a hierarchical name. relative to this
block. If no register with that name is found in this block, the sub-blocks are searched
for a register of that name and the first one to be found is returned.
If no registers are found, returns null.
get_field_by_name
virtual function uvm_reg_field get_field_by_name (
string name
)
Finds a field with the specified simple name.
The name is the simple name of the field, not a hierarchical name. relative to this block. If no field with that name is found in this block, the sub-blocks are searched for a field
of that name and the first one to be found is returned.
If no fields are found, returns null.
get_mem_by_name
virtual function uvm_mem get_mem_by_name (
string name
)
Finds a memory with the specified simple name.
The name is the simple name of the memory, not a hierarchical name. relative to this
block. If no memory with that name is found in this block, the sub-blocks are searched
for a memory of that name and the first one to be found is returned.
If no memories are found, returns null.
get_vreg_by_name
UVM 1.2 Class Reference
564
virtual function uvm_vreg get_vreg_by_name (
string name
)
Finds a virtual register with the specified simple name.
The name is the simple name of the virtual register, not a hierarchical name. relative to
this block. If no virtual register with that name is found in this block, the sub-blocks are
searched for a virtual register of that name and the first one to be found is returned.
If no virtual registers are found, returns null.
get_vfield_by_name
virtual function uvm_vreg_field get_vfield_by_name (
string name
)
Finds a virtual field with the specified simple name.
The name is the simple name of the virtual field, not a hierarchical name. relative to this
block. If no virtual field with that name is found in this block, the sub-blocks are
searched for a virtual field of that name and the first one to be found is returned.
If no virtual fields are found, returns null.
COVERAGE
build_coverage
protected function uvm_reg_cvr_t build_coverage(
uvm_reg_cvr_t models
)
Check if all of the specified coverage model must be built.
Check which of the specified coverage model must be built in this instance of the block
abstraction class, as specified by calls to uvm_reg::include_coverage().
Models are specified by adding the symbolic value of individual coverage model as
defined in uvm_coverage_model_e. Returns the sum of all coverage models to be built
in the block model.
add_coverage
virtual protected function void add_coverage(
uvm_reg_cvr_t models
)
Specify that additional coverage models are available.
Add the specified coverage model to the coverage models available in this class. Models
are specified by adding the symbolic value of individual coverage model as defined in
uvm_coverage_model_e.
UVM 1.2 Class Reference
565
This method shall be called only in the constructor of subsequently derived classes.
has_coverage
virtual function bit has_coverage(
uvm_reg_cvr_t models
)
Check if block has coverage model(s)
Returns TRUE if the block abstraction class contains a coverage model for all of the
models specified. Models are specified by adding the symbolic value of individual
coverage model as defined in uvm_coverage_model_e.
set_coverage
virtual function uvm_reg_cvr_t set_coverage(
uvm_reg_cvr_t is_on
)
Turns on coverage measurement.
Turns the collection of functional coverage measurements on or off for this block and all
blocks, registers, fields and memories within it. The functional coverage measurement is
turned on for every coverage model specified using uvm_coverage_model_e symbolic
identifiers. Multiple functional coverage models can be specified by adding the functional
coverage model identifiers. All other functional coverage models are turned off. Returns
the sum of all functional coverage models whose measurements were previously on.
This method can only control the measurement of functional coverage models that are
present in the various abstraction classes, then enabled during construction. See the
uvm_reg_block::has_coverage() method to identify the available functional coverage
models.
get_coverage
virtual function bit get_coverage(
uvm_reg_cvr_t is_on = UVM_CVR_ALL
)
Check if coverage measurement is on.
Returns TRUE if measurement for all of the specified functional coverage models are
currently on. Multiple functional coverage models can be specified by adding the
functional coverage model identifiers.
See uvm_reg_block::set_coverage() for more details.
sample
protected virtual function void sample(
uvm_reg_addr_t offset,
bit is_read,
uvm_reg_map map
)
Functional coverage measurement method
UVM 1.2 Class Reference
566
This method is invoked by the block abstraction class whenever an address within one of
its address map is successfully read or written. The specified offset is the offset within
the block, not an absolute address.
Empty by default, this method may be extended by the abstraction class generator to
perform the required sampling in any provided functional coverage model.
sample_values
virtual function void sample_values()
Functional coverage measurement method for field values
This method is invoked by the user or by the uvm_reg_block::sample_values() method of
the parent block to trigger the sampling of the current field values in the block-level
functional coverage model. It recursively invokes the uvm_reg_block::sample_values()
and uvm_reg::sample_values() methods in the blocks and registers in this block.
This method may be extended by the abstraction class generator to perform the required
sampling in any provided field-value functional coverage model. If this method is
extended, it MUST call super.sample_values().
AccEss
get_default_path
virtual function uvm_path_e get_default_path()
Default access path
Returns the default access path for this block.
reset
virtual function void reset(
string kind = "HARD"
)
Reset the mirror for this block.
Sets the mirror value of all registers in the block and sub-blocks to the reset value
corresponding to the specified reset event. See uvm_reg_field::reset() for more details. Does not actually set the value of the registers in the design, only the values mirrored in
their corresponding mirror.
needs_update
virtual function bit needs_update()
Check if DUT registers need to be written
If a mirror value has been modified in the abstraction model without actually updating
UVM 1.2 Class Reference
567
the actual register (either through randomization or via the uvm_reg::set() method, the
mirror and state of the registers are outdated. The corresponding registers in the DUT
need to be updated.
This method returns TRUE if the state of at least one register in the block or sub-blocks
needs to be updated to match the mirrored values. The mirror values, or actual content
of registers, are not modified. For additional information, see uvm_reg_block::update()
method.
update
virtual task update(
output uvm_status_e status, input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Batch update of register.
Using the minimum number of write operations, updates the registers in the design to
match the mirrored values in this block and sub-blocks. The update can be performed
using the physical interfaces (front-door access) or back-door accesses. This method
performs the reverse operation of uvm_reg_block::mirror().
mirror
virtual task mirror(
output uvm_status_e status, check
= UVM_NO_CHECK,
input uvm_check_e input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Update the mirrored values
Read all of the registers in this block and sub-blocks and update their mirror values to
match their corresponding values in the design. The mirroring can be performed using
the physical interfaces (front-door access) or back-door accesses. If the check argument
is specified as UVM_CHECK, an error message is issued if the current mirrored value
does not match the actual value in the design. This method performs the reverse
operation of uvm_reg_block::update().
write_reg_by_name
virtual task write_reg_by_name(
output uvm_status_e status, name,
input string data,
input uvm_reg_data_t input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
UVM 1.2 Class Reference
568
input int )
lineno
= 0
Write the named register
Equivalent to get_reg_by_name() followed by uvm_reg::write()
read_reg_by_name
virtual task read_reg_by_name(
output uvm_status_e status, input string name,
output uvm_reg_data_t data,
path
= UVM_DEFAULT_PATH,
input uvm_path_e input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the named register
Equivalent to get_reg_by_name() followed by uvm_reg::read()
write_mem_by_name
virtual task write_mem_by_name(
output uvm_status_e status, name,
input string input uvm_reg_addr_t offset, data,
input uvm_reg_data_t input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Write the named memory
Equivalent to get_mem_by_name() followed by uvm_mem::write()
read_mem_by_name
virtual task read_mem_by_name(
output uvm_status_e status, name,
input string input uvm_reg_addr_t offset, data,
output uvm_reg_data_t input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the named memory
Equivalent to get_mem_by_name() followed by uvm_mem::read()
UVM 1.2 Class Reference
569
BAcKdOOR
get_backdoor
function uvm_reg_backdoor get_backdoor(
bit inherited = 1
)
Get the user-defined backdoor for all registers in this block
Return the user-defined backdoor for all register in this block and all sub-blocks -- unless
overridden by a backdoor set in a lower-level block or in the register itself.
If inherited is TRUE, returns the backdoor of the parent block if none have been specified
for this block.
set_backdoor
function void set_backdoor (
uvm_reg_backdoor bkdr, fname = "",
string int lineno = 0
)
Set the user-defined backdoor for all registers in this block
Defines the backdoor mechanism for all registers instantiated in this block and subblocks, unless overridden by a definition in a lower-level block or register.
clear_hdl_path
function void clear_hdl_path (
string kind = "RTL"
)
Delete HDL paths
Remove any previously specified HDL path to the block instance for the specified design
abstraction.
add_hdl_path
function void add_hdl_path (
string path, string kind = "RTL"
)
Add an HDL path
Add the specified HDL path to the block instance for the specified design abstraction. This method may be called more than once for the same design abstraction if the block
is physically duplicated in the design abstraction
UVM 1.2 Class Reference
570
has_hdl_path
function bit has_hdl_path (
string kind = ""
)
Check if a HDL path is specified
Returns TRUE if the block instance has a HDL path defined for the specified design
abstraction. If no design abstraction is specified, uses the default design abstraction
specified for this block or the nearest block ancestor with a specified default design
abstraction.
get_hdl_path
function void get_hdl_path (
ref string paths[$], input string kind
= ""
)
Get the incremental HDL path(s)
Returns the HDL path(s) defined for the specified design abstraction in the block
instance. Returns only the component of the HDL paths that corresponds to the block,
not a full hierarchical path
If no design abstraction is specified, the default design abstraction for this block is used.
get_full_hdl_path
function void get_full_hdl_path (
ref string paths[$], = "",
input string kind
string separator = "."
)
Get the full hierarchical HDL path(s)
Returns the full hierarchical HDL path(s) defined for the specified design abstraction in
the block instance. There may be more than one path returned even if only one path
was defined for the block instance, if any of the parent components have more than one
path defined for the same design abstraction
If no design abstraction is specified, the default design abstraction for each ancestor
block is used to get each incremental path.
set_default_hdl_path
function void set_default_hdl_path (
string kind
)
Set the default design abstraction
Set the default design abstraction for this block instance.
get_default_hdl_path
UVM 1.2 Class Reference
571
function string get_default_hdl_path ()
Get the default design abstraction
Returns the default design abstraction for this block instance. If a default design
abstraction has not been explicitly set for this block instance, returns the default design
abstraction for the nearest block ancestor. Returns “” if no default design abstraction
has been specified.
set_hdl_path_root
function void set_hdl_path_root (
string path, string kind = "RTL"
)
Specify a root HDL path
Set the specified path as the absolute HDL path to the block instance for the specified
design abstraction. This absolute root path is prepended to all hierarchical paths under
this block. The HDL path of any ancestor block is ignored. This method overrides any
incremental path for the same design abstraction specified using add_hdl_path.
is_hdl_path_root
function bit is_hdl_path_root (
string kind = ""
)
Check if this block has an absolute path
Returns TRUE if an absolute HDL path to the block instance for the specified design
abstraction has been defined. If no design abstraction is specified, the default design
abstraction for this block is used.
UVM 1.2 Class Reference
572
25.2 uvm_reg_transaction_order_policy
Contents
uvm_reg_transaction_order_policy
uvm_reg_map
METHODS
order
pure virtual function void order(
ref uvm_reg_bus_op q[$]
)
the order() function may reorder the sequence of bus transactions produced by a single
uvm_reg transaction (read/write). This can be used in scenarios when the register width
differs from the bus width and one register access results in a series of bus transactions.
the first item (0) of the queue will be the first bus transaction (the last($) will be the
final transaction
uvm_reg_map
Address map abstraction class
This class represents an address map. An address map is a collection of registers and
memories accessible via a specific physical interface. Address maps can be composed
into higher-level address maps.
Address maps are created using the uvm_reg_block::create_map() method.
Summary
uvm_reg_map
CLASS HIERARcHY
uvm_void
uvm_object
uvm_reg_map
CLASS DEcLARATION
class uvm_reg_map extends uvm_object
UVM 1.2 Class Reference
573
backdoor
INITIALIZATION
new
configure
add_reg
add_mem
add_submap
set_sequencer
set_submap_offset
get_submap_offset
set_base_addr
reset
INTROSPEcTION
get_name
get_full_name
get_root_map
get_parent
get_parent_map
get_base_addr
get_n_bytes
get_addr_unit_bytes
get_base_addr
get_sequencer
get_adapter
get_submaps
get_registers
get_fields
get_virtual_registers
get_virtual_fields
get_physical_addresses
get_reg_by_offset
get_mem_by_offset
BUS AccESS
set_auto_predict
get_auto_predict
set_check_on_read
get_check_on_read
do_bus_write
do_bus_read
do_write
do_read
set_transaction_order_policy
get_transaction_order_policy
Return the backdoor pseudo-map singleton
Create a new instance
Instance-specific configuration
Add a register
Add a memory
Add an address map
Set the sequencer and adapter associated
with this map.
Set the offset of the given submap to offset.
Return the offset of the given submap.
Set the base address of this map.
Reset the mirror for all registers in this
address map.
Get the simple name
Get the hierarchical name
Get the externally-visible address map
Get the parent block
Get the higher-level address map
Get the base offset address for this map.
Get the width in bytes of the bus associated
with this map.
Get the number of bytes in the smallest
addressable unit in the map.
Gets the endianness of the bus associated
with this map.
Gets the sequencer for the bus associated
with this map.
Gets the bus adapter for the bus associated
with this map.
Get the address sub-maps
Get the registers
Get the fields
Get the virtual registers
Get the virtual fields
Translate a local address into external
addresses
Get register mapped at offset
Get memory mapped at offset
Sets the auto-predict mode for his map.
Gets the auto-predict mode setting for this
map.
Sets the check-on-read mode for his map
and all of its submaps.
Gets the check-on-read mode setting for this
map.
Perform a bus write operation.
Perform a bus read operation.
Perform a write operation.
Perform a read operation.
set the transaction order policy
set the transaction order policy
backdoor
static function uvm_reg_map backdoor()
Return the backdoor pseudo-map singleton
This pseudo-map is used to specify or configure the backdoor instead of a real address
UVM 1.2 Class Reference
574
map.
INITIALIZATION
new
function new(
string name = "uvm_reg_map"
)
Create a new instance
configure
function void configure(
uvm_reg_block parent,
uvm_reg_addr_t base_addr,
int unsigned n_bytes,
uvm_endianness_e endian,
bit byte_addressing = 1
)
Instance-specific configuration
Configures this map with the following properties.
parent
the block in which this map is created and applied
base_addr
the base address for this map. All registers, memories, and
sub-blocks will be at offsets to this address
n_bytes
the byte-width of the bus on which this map is used
endian
the endian format. See uvm_endianness_e for possible
values
byte_addressing
specifies whether the address increment is on a per-byte
basis. For example, consecutive memory locations with
~n_bytes~=4 (32-bit bus) are 4 apart: 0, 4, 8, and so on. Default is TRUE.
add_reg
virtual function void add_reg (
uvm_reg rg,
offset, uvm_reg_addr_t string rights
= "RW",
bit unmapped = 0,
uvm_reg_frontdoor frontdoor = null
)
Add a register
Add the specified register instance rg to this address map.
The register is located at the specified address offset from this maps configured base
address.
The rights specify the register’s accessibility via this map. Valid values are “RW”, “RO”,
and “WO”. Whether a register field can be read or written depends on both the field’s
UVM 1.2 Class Reference
575
configured access policy (see uvm_reg_field::configure and the register’s rights in the
map being used to access the field.
The number of consecutive physical addresses occupied by the register depends on the
width of the register and the number of bytes in the physical interface corresponding to
this address map.
If unmapped is TRUE, the register does not occupy any physical addresses and the base
address is ignored. Unmapped registers require a user-defined frontdoor to be specified.
A register may be added to multiple address maps if it is accessible from multiple
physical interfaces. A register may only be added to an address map whose parent block
is the same as the register’s parent block.
add_mem
virtual function void add_mem (
uvm_mem mem,
uvm_reg_addr_t offset, string rights
= "RW",
bit unmapped = 0,
uvm_reg_frontdoor frontdoor = null
)
Add a memory
Add the specified memory instance to this address map. The memory is located at the
specified base address and has the specified access rights (“RW”, “RO” or “WO”). The
number of consecutive physical addresses occupied by the memory depends on the width
and size of the memory and the number of bytes in the physical interface corresponding
to this address map.
If unmapped is TRUE, the memory does not occupy any physical addresses and the base
address is ignored. Unmapped memories require a user-defined frontdoor to be
specified.
A memory may be added to multiple address maps if it is accessible from multiple
physical interfaces. A memory may only be added to an address map whose parent
block is the same as the memory’s parent block.
add_submap
virtual function void add_submap (
uvm_reg_map child_map,
uvm_reg_addr_t offset
)
Add an address map
Add the specified address map instance to this address map. The address map is located
at the specified base address. The number of consecutive physical addresses occupied by
the submap depends on the number of bytes in the physical interface that corresponds
to the submap, the number of addresses used in the submap and the number of bytes in
the physical interface corresponding to this address map.
An address map may be added to multiple address maps if it is accessible from multiple
physical interfaces. An address map may only be added to an address map in the grandparent block of the address submap.
UVM 1.2 Class Reference
576
set_sequencer
virtual function void set_sequencer (
uvm_sequencer_base sequencer, uvm_reg_adapter adapter
= null
)
Set the sequencer and adapter associated with this map. This method must be called
before starting any sequences based on uvm_reg_sequence.
set_submap_offset
virtual function void set_submap_offset (
uvm_reg_map submap,
uvm_reg_addr_t offset
)
Set the offset of the given submap to offset.
get_submap_offset
virtual function uvm_reg_addr_t get_submap_offset (
uvm_reg_map submap
)
Return the offset of the given submap.
set_base_addr
virtual function void set_base_addr (
uvm_reg_addr_t offset
)
Set the base address of this map.
reset
virtual function void reset(
string kind = "SOFT"
)
Reset the mirror for all registers in this address map.
Sets the mirror value of all registers in this address map and all of its submaps to the
reset value corresponding to the specified reset event. See uvm_reg_field::reset() for
more details. Does not actually set the value of the registers in the design, only the
values mirrored in their corresponding mirror.
Note that, unlike the other reset() method, the default reset event for this method is
“SOFT”.
INTROSPEcTION
UVM 1.2 Class Reference
577
get_name
Get the simple name
Return the simple object name of this address map.
get_full_name
virtual function string get_full_name()
Get the hierarchical name
Return the hierarchal name of this address map. The base of the hierarchical name is
the root block.
get_root_map
virtual function uvm_reg_map get_root_map()
Get the externally-visible address map
Get the top-most address map where this address map is instantiated. It corresponds to
the externally-visible address map that can be accessed by the verification environment.
get_parent
virtual function uvm_reg_block get_parent()
Get the parent block
Return the block that is the parent of this address map.
get_parent_map
virtual function uvm_reg_map get_parent_map()
Get the higher-level address map
Return the address map in which this address map is mapped. returns null if this is a
top-level address map.
get_base_addr
virtual function uvm_reg_addr_t get_base_addr (
uvm_hier_e hier = UVM_HIER
)
Get the base offset address for this map. If this map is the root map, the base address
is that set with the base_addr argument to uvm_reg_block::create_map(). If this map is
a submap of a higher-level map, the base address is offset given this submap by the
parent map. See set_submap_offset.
UVM 1.2 Class Reference
578
get_n_bytes
virtual function int unsigned get_n_bytes (
uvm_hier_e hier = UVM_HIER
)
Get the width in bytes of the bus associated with this map. If hier is UVM_HIER, then
gets the effective bus width relative to the system level. The effective bus width is the
narrowest bus width from this map to the top-level root map. Each bus access will be
limited to this bus width.
get_addr_unit_bytes
virtual function int unsigned get_addr_unit_bytes()
Get the number of bytes in the smallest addressable unit in the map. Returns 1 if the
address map was configured using byte-level addressing. Returns get_n_bytes()
otherwise.
get_base_addr
Gets the endianness of the bus associated with this map. If hier is set to UVM_HIER,
gets the system-level endianness.
get_sequencer
virtual function uvm_sequencer_base get_sequencer (
uvm_hier_e hier = UVM_HIER
)
Gets the sequencer for the bus associated with this map. If hier is set to UVM_HIER,
gets the sequencer for the bus at the system-level. See set_sequencer.
get_adapter
virtual function uvm_reg_adapter get_adapter (
uvm_hier_e hier = UVM_HIER
)
Gets the bus adapter for the bus associated with this map. If hier is set to UVM_HIER,
gets the adapter for the bus used at the system-level. See set_sequencer.
get_submaps
virtual function void get_submaps (
ref uvm_reg_map maps[$], = UVM_HIER
input uvm_hier_e hier
)
Get the address sub-maps
Get the address maps instantiated in this address map. If hier is UVM_HIER, recursively
includes the address maps, in the sub-maps.
UVM 1.2 Class Reference
579
get_registers
virtual function void get_registers (
ref uvm_reg regs[$], input uvm_hier_e hier
= UVM_HIER
)
Get the registers
Get the registers instantiated in this address map. If hier is UVM_HIER, recursively
includes the registers in the sub-maps.
get_fields
virtual function void get_fields (
ref uvm_reg_field fields[$], input uvm_hier_e hier
= UVM_HIER
)
Get the fields
Get the fields in the registers instantiated in this address map. If hier is UVM_HIER,
recursively includes the fields of the registers in the sub-maps.
get_virtual_registers
virtual function void get_virtual_registers (
ref uvm_vreg regs[$], = UVM_HIER
input uvm_hier_e hier
)
Get the virtual registers
Get the virtual registers instantiated in this address map. If hier is UVM_HIER,
recursively includes the virtual registers in the sub-maps.
get_virtual_fields
virtual function void get_virtual_fields (
ref uvm_vreg_field fields[$], hier
= UVM_HIER
input uvm_hier_e )
Get the virtual fields
Get the virtual fields from the virtual registers instantiated in this address map. If hier is
UVM_HIER, recursively includes the virtual fields in the virtual registers in the sub-maps.
get_physical_addresses
virtual function int get_physical_addresses(
uvm_reg_addr_t base_addr,
uvm_reg_addr_t mem_offset,
int unsigned n_bytes,
ref uvm_reg_addr_t addr[]
)
UVM 1.2 Class Reference
580
Translate a local address into external addresses
Identify the sequence of addresses that must be accessed physically to access the
specified number of bytes at the specified address within this address map. Returns the
number of bytes of valid data in each access.
Returns in addr a list of address in little endian order, with the granularity of the toplevel address map.
A register is specified using a base address with mem_offset as 0. A location within a
memory is specified using the base address of the memory and the index of the location
within that memory.
get_reg_by_offset
virtual function uvm_reg get_reg_by_offset(
uvm_reg_addr_t offset, bit read
= 1
)
Get register mapped at offset
Identify the register located at the specified offset within this address map for the
specified type of access. Returns null if no such register is found.
The model must be locked using uvm_reg_block::lock_model() to enable this
functionality.
get_mem_by_offset
virtual function uvm_mem get_mem_by_offset(
uvm_reg_addr_t offset
)
Get memory mapped at offset
Identify the memory located at the specified offset within this address map. The offset
may refer to any memory location in that memory. Returns null if no such memory is
found.
The model must be locked using uvm_reg_block::lock_model() to enable this
functionality.
BUS AccESS
set_auto_predict
function void set_auto_predict(
bit on = 1
)
Sets the auto-predict mode for his map.
When on is TRUE, the register model will automatically update its mirror (what it thinks
should be in the DUT) immediately after any bus read or write operation via this map. Before a uvm_reg::write or uvm_reg::read operation returns, the register’s
UVM 1.2 Class Reference
581
uvm_reg::predict method is called to update the mirrored value in the register.
When on is FALSE, bus reads and writes via this map do not automatically update the
mirror. For real-time updates to the mirror in this mode, you connect a
uvm_reg_predictor instance to the bus monitor. The predictor takes observed bus
transactions from the bus monitor, looks up the associated uvm_reg register given the
address, then calls that register’s uvm_reg::predict method. While more complex, this
mode will capture all register read/write activity, including that not directly descendant
from calls to uvm_reg::write and uvm_reg::read.
By default, auto-prediction is turned off.
get_auto_predict
function bit get_auto_predict()
Gets the auto-predict mode setting for this map.
set_check_on_read
function void set_check_on_read(
bit on = 1
)
Sets the check-on-read mode for his map and all of its submaps.
When on is TRUE, the register model will automatically check any value read back from a
register or field against the current value in its mirror and report any discrepancy. This
effectively combines the functionality of the uvm_reg::read() and
uvm_reg::mirror(UVM_CHECK) method. This mode is useful when the register model
is used passively.
When on is FALSE, no check is made against the mirrored value.
At the end of the read operation, the mirror value is updated based on the value that
was read regardless of this mode setting.
By default, auto-prediction is turned off.
get_check_on_read
function bit get_check_on_read()
Gets the check-on-read mode setting for this map.
do_bus_write
virtual task do_bus_write (
uvm_reg_item rw,
uvm_sequencer_base sequencer,
uvm_reg_adapter adapter
)
Perform a bus write operation.
UVM 1.2 Class Reference
582
do_bus_read
virtual task do_bus_read (
uvm_reg_item rw,
uvm_sequencer_base sequencer,
uvm_reg_adapter adapter
)
Perform a bus read operation.
do_write
virtual task do_write(
uvm_reg_item rw
)
Perform a write operation.
do_read
virtual task do_read(
uvm_reg_item rw
)
Perform a read operation.
set_transaction_order_policy
function void set_transaction_order_policy(
uvm_reg_transaction_order_policy pol
)
set the transaction order policy
get_transaction_order_policy
function uvm_reg_transaction_order_policy get_transaction_order_policy()
set the transaction order policy
UVM 1.2 Class Reference
583
25.3 uvm_reg_file
Register file abstraction base class
A register file is a collection of register files and registers used to create regular repeated
structures.
Register files are usually instantiated as arrays.
Summary
uvm_reg_file
Register file abstraction base class
CLAss HIERARchY
uvm_void
uvm_object
uvm_reg_file
CLAss DEcLARATION
virtual class uvm_reg_file extends uvm_object
INITIALIZATION
new
configure
Create a new instance
Configure a register file instance
INTROsPEcTION
get_name
get_full_name
get_parent
get_regfile
Get
Get
Get
Get
BAcKdOOR
clear_hdl_path
add_hdl_path
has_hdl_path
get_hdl_path
get_full_hdl_path
set_default_hdl_path
get_default_hdl_path
Delete HDL paths
Add an HDL path
Check if a HDL path is specified
Get the incremental HDL path(s)
Get the full hierarchical HDL path(s)
Set the default design abstraction
Get the default design abstraction
the
the
the
the
simple name
hierarchical name
parent block
parent register file
INITIALIZATION
new
function new (
string name = ""
)
Create a new instance
Creates an instance of a register file abstraction class with the specified name.
UVM 1.2 Class Reference
584
configure
function void configure (
uvm_reg_block blk_parent,
uvm_reg_file regfile_parent, string hdl_path
= ""
)
Configure a register file instance
Specify the parent block and register file of the register file instance. If the register file
is instantiated in a block, regfile_parent is specified as null. If the register file is
instantiated in a register file, blk_parent must be the block parent of that register file
and regfile_parent is specified as that register file.
If the register file corresponds to a hierarchical RTL structure, its contribution to the HDL
path is specified as the hdl_path. Otherwise, the register file does not correspond to a
hierarchical RTL structure (e.g. it is physically flattened) and does not contribute to the
hierarchical HDL path of any contained registers.
INTROsPEcTION
get_name
Get the simple name
Return the simple object name of this register file.
get_full_name
virtual function string get_full_name()
Get the hierarchical name
Return the hierarchal name of this register file. The base of the hierarchical name is the
root block.
get_parent
virtual function uvm_reg_block get_parent ()
Get the parent block
get_regfile
virtual function uvm_reg_file get_regfile ()
Get the parent register file
Returns null if this register file is instantiated in a block.
UVM 1.2 Class Reference
585
BAcKdOOR
clear_hdl_path
function void clear_hdl_path (
string kind = "RTL"
)
Delete HDL paths
Remove any previously specified HDL path to the register file instance for the specified
design abstraction.
add_hdl_path
function void add_hdl_path (
string path, string kind = "RTL"
)
Add an HDL path
Add the specified HDL path to the register file instance for the specified design
abstraction. This method may be called more than once for the same design abstraction
if the register file is physically duplicated in the design abstraction
has_hdl_path
function bit has_hdl_path (
string kind = ""
)
Check if a HDL path is specified
Returns TRUE if the register file instance has a HDL path defined for the specified design
abstraction. If no design abstraction is specified, uses the default design abstraction
specified for the nearest enclosing register file or block
If no design abstraction is specified, the default design abstraction for this register file is
used.
get_hdl_path
function void get_hdl_path (
ref string paths[$], = ""
input string kind
)
Get the incremental HDL path(s)
Returns the HDL path(s) defined for the specified design abstraction in the register file
instance. If no design abstraction is specified, uses the default design abstraction
specified for the nearest enclosing register file or block. Returns only the component of
the HDL paths that corresponds to the register file, not a full hierarchical path
If no design abstraction is specified, the default design abstraction for this register file is
UVM 1.2 Class Reference
586
used.
get_full_hdl_path
function void get_full_hdl_path (
ref string paths[$], input string kind
= "",
input string separator = "."
)
Get the full hierarchical HDL path(s)
Returns the full hierarchical HDL path(s) defined for the specified design abstraction in
the register file instance. If no design abstraction is specified, uses the default design
abstraction specified for the nearest enclosing register file or block. There may be more
than one path returned even if only one path was defined for the register file instance, if
any of the parent components have more than one path defined for the same design
abstraction
If no design abstraction is specified, the default design abstraction for each ancestor
register file or block is used to get each incremental path.
set_default_hdl_path
function void set_default_hdl_path (
string kind
)
Set the default design abstraction
Set the default design abstraction for this register file instance.
get_default_hdl_path
function string get_default_hdl_path ()
Get the default design abstraction
Returns the default design abstraction for this register file instance. If a default design
abstraction has not been explicitly set for this register file instance, returns the default
design abstraction for the nearest register file or block ancestor. Returns “” if no default
design abstraction has been specified.
UVM 1.2 Class Reference
587
25.4 uvm_reg
Register abstraction base class
A register represents a set of fields that are accessible as a single entity.
A register may be mapped to one or more address maps, each with different access
rights and policy.
Summary
uvm_reg
Register abstraction base class
CLAss HIERARchY
uvm_void
uvm_object
uvm_reg
CLAss DEcLARATION
virtual class uvm_reg extends uvm_object
INITIALIZATION
new
configure
set_offset
INTROsPEcTION
get_name
get_full_name
get_parent
get_regfile
get_n_maps
is_in_map
get_maps
get_rights
get_n_bits
get_n_bytes
get_max_size
get_fields
get_field_by_name
get_offset
get_address
get_addresses
AccEss
set
get
get_mirrored_value
needs_update
reset
get_reset
has_reset
UVM 1.2 Class Reference
Create a new instance and type-specific configuration
Instance-specific configuration
Modify the offset of the register
Get the simple name
Get the hierarchical name
Get the parent block
Get the parent register file
Returns the number of address maps this register is
mapped in
Returns 1 if this register is in the specified address
map
Returns all of the address maps where this register is
mapped
Returns the accessibility (“RW, “RO”, or “WO”) of this
register in the given map.
Returns the width, in bits, of this register.
Returns the width, in bytes, of this register.
Returns the maximum width, in bits, of all registers.
Return the fields in this register
Return the named field in this register
Returns the offset of this register
Returns the base external physical address of this
register
Identifies the external physical address(es) of this
register
Set the desired value for this register
Return the desired value of the fields in the register.
Return the mirrored value of the fields in the register.
Returns 1 if any of the fields need updating
Reset the desired/mirrored value for this register.
Get the specified reset value for this register
Check if any field in the register has a reset value
specified for the specified reset kind.
588
set_reset
write
read
poke
peek
update
mirror
predict
is_busy
FRONTdOOR
set_frontdoor
get_frontdoor
BAcKdOOR
set_backdoor
get_backdoor
clear_hdl_path
add_hdl_path
add_hdl_path_slice
has_hdl_path
get_hdl_path
get_hdl_path_kinds
get_full_hdl_path
backdoor_read
backdoor_write
backdoor_read_func
backdoor_watch
COVERAGE
include_coverage
build_coverage
add_coverage
has_coverage
set_coverage
get_coverage
sample
sample_values
CALLbAcKs
pre_write
post_write
pre_read
post_read
Specify or modify the reset value for this register
Write the specified value in this register
Read the current value from this register
Deposit the specified value in this register
Read the current value from this register
Updates the content of the register in the design to
match the desired value
Read the register and update/check its mirror value
Update the mirrored and desired value for this
register.
Returns 1 if register is currently being read or written.
Set a user-defined frontdoor for this register
Returns the user-defined frontdoor for this register
Set a user-defined backdoor for this register
Returns the user-defined backdoor for this register
Delete HDL paths
Add an HDL path
Append the specified HDL slice to the HDL path of the
register instance for the specified design abstraction.
Check if a HDL path is specified
Get the incremental HDL path(s)
Get design abstractions for which HDL paths have
been defined
Get the full hierarchical HDL path(s)
User-define backdoor read access
User-defined backdoor read access
User-defined backdoor read access
User-defined DUT register change monitor
Specify which coverage model that must be included
in various block, register or memory abstraction class
instances.
Check if all of the specified coverage models must be
built.
Specify that additional coverage models are available.
Check if register has coverage model(s)
Turns on coverage measurement.
Check if coverage measurement is on.
Functional coverage measurement method
Functional coverage measurement method for field
values
Called
Called
Called
Called
before register write.
after register write.
before register read.
after register read.
INITIALIZATION
new
function new (
string name
= "",
int unsigned n_bits,
int has_coverage )
Create a new instance and type-specific configuration
UVM 1.2 Class Reference
589
Creates an instance of a register abstraction class with the specified name.
n_bits specifies the total number of bits in the register. Not all bits need to be
implemented. This value is usually a multiple of 8.
has_coverage specifies which functional coverage models are present in the extension of
the register abstraction class. Multiple functional coverage models may be specified by
adding their symbolic names, as defined by the uvm_coverage_model_e type.
configure
function void configure (
uvm_reg_block blk_parent,
uvm_reg_file regfile_parent = null,
string hdl_path
= ""
)
Instance-specific configuration
Specify the parent block of this register. May also set a parent register file for this
register,
If the register is implemented in a single HDL variable, its name is specified as the
hdl_path. Otherwise, if the register is implemented as a concatenation of variables
(usually one per field), then the HDL path must be specified using the add_hdl_path() or
add_hdl_path_slice method.
set_offset
virtual function void set_offset (
uvm_reg_map map,
uvm_reg_addr_t offset, bit unmapped = 0
)
Modify the offset of the register
The offset of a register within an address map is set using the uvm_reg_map::add_reg()
method. This method is used to modify that offset dynamically.
Modifying the offset of a register will make the register model diverge from the
specification that was used to create it.
INTROsPEcTION
get_name
Get the simple name
Return the simple object name of this register.
get_full_name
virtual function string get_full_name()
UVM 1.2 Class Reference
590
Get the hierarchical name
Return the hierarchal name of this register. The base of the hierarchical name is the
root block.
get_parent
virtual function uvm_reg_block get_parent ()
Get the parent block
get_regfile
virtual function uvm_reg_file get_regfile ()
Get the parent register file
Returns null if this register is instantiated in a block.
get_n_maps
virtual function int get_n_maps ()
Returns the number of address maps this register is mapped in
is_in_map
function bit is_in_map (
uvm_reg_map map
)
Returns 1 if this register is in the specified address map
get_maps
virtual function void get_maps (
ref uvm_reg_map maps[$]
)
Returns all of the address maps where this register is mapped
get_rights
virtual function string get_rights (
uvm_reg_map map = null
)
Returns the accessibility (“RW, “RO”, or “WO”) of this register in the given map.
If no address map is specified and the register is mapped in only one address map, that
address map is used. If the register is mapped in more than one address map, the
UVM 1.2 Class Reference
591
default address map of the parent block is used.
Whether a register field can be read or written depends on both the field’s configured
access policy (refer to uvm_reg_field::configure) and the register’s accessibility rights in
the map being used to access the field.
If an address map is specified and the register is not mapped in the specified address
map, an error message is issued and “RW” is returned.
get_n_bits
virtual function int unsigned get_n_bits ()
Returns the width, in bits, of this register.
get_n_bytes
virtual function int unsigned get_n_bytes()
Returns the width, in bytes, of this register. Rounds up to next whole byte if register is
not a multiple of 8.
get_max_size
static function int unsigned get_max_size()
Returns the maximum width, in bits, of all registers.
get_fields
virtual function void get_fields (
ref uvm_reg_field fields[$]
)
Return the fields in this register
Fills the specified array with the abstraction class for all of the fields contained in this
register. Fields are ordered from least-significant position to most-significant position
within the register.
get_field_by_name
virtual function uvm_reg_field get_field_by_name(
string name
)
Return the named field in this register
Finds a field with the specified name in this register and returns its abstraction class. If
no fields are found, returns null.
get_offset
UVM 1.2 Class Reference
592
virtual function uvm_reg_addr_t get_offset (
uvm_reg_map map = null
)
Returns the offset of this register
Returns the offset of this register in an address map.
If no address map is specified and the register is mapped in only one address map, that
address map is used. If the register is mapped in more than one address map, the
default address map of the parent block is used.
If an address map is specified and the register is not mapped in the specified address
map, an error message is issued.
get_address
virtual function uvm_reg_addr_t get_address (
uvm_reg_map map = null
)
Returns the base external physical address of this register
Returns the base external physical address of this register if accessed through the
specified address map.
If no address map is specified and the register is mapped in only one address map, that
address map is used. If the register is mapped in more than one address map, the
default address map of the parent block is used.
If an address map is specified and the register is not mapped in the specified address
map, an error message is issued.
get_addresses
virtual function int get_addresses (
uvm_reg_map map
= null,
ref uvm_reg_addr_t addr[] )
Identifies the external physical address(es) of this register
Computes all of the external physical addresses that must be accessed to completely
read or write this register. The addressed are specified in little endian order. Returns
the number of bytes transferred on each access.
If no address map is specified and the register is mapped in only one address map, that
address map is used. If the register is mapped in more than one address map, the
default address map of the parent block is used.
If an address map is specified and the register is not mapped in the specified address
map, an error message is issued.
AccEss
UVM 1.2 Class Reference
593
set
virtual function void set (
uvm_reg_data_t value, string fname = "",
int lineno = 0
)
Set the desired value for this register
Sets the desired value of the fields in the register to the specified value. Does not
actually set the value of the register in the design, only the desired value in its
corresponding abstraction class in the RegModel model. Use the uvm_reg::update()
method to update the actual register with the mirrored value or the uvm_reg::write()
method to set the actual register and its mirrored value.
Unless this method is used, the desired value is equal to the mirrored value.
Refer uvm_reg_field::set() for more details on the effect of setting mirror values on
fields with different access policies.
To modify the mirrored field values to a specific value, and thus use the mirrored as a
scoreboard for the register values in the DUT, use the uvm_reg::predict() method.
get
virtual function uvm_reg_data_t get(
string fname = "",
int lineno = 0
)
Return the desired value of the fields in the register.
Does not actually read the value of the register in the design, only the desired value in
the abstraction class. Unless set to a different value using the uvm_reg::set(), the
desired value and the mirrored value are identical.
Use the uvm_reg::read() or uvm_reg::peek() method to get the actual register value.
If the register contains write-only fields, the desired/mirrored value for those fields are
the value last written and assumed to reside in the bits implementing these fields. Although a physical read operation would something different for these fields, the
returned value is the actual content.
get_mirrored_value
virtual function uvm_reg_data_t get_mirrored_value(
string fname = "",
int lineno = 0
)
Return the mirrored value of the fields in the register.
Does not actually read the value of the register in the design
If the register contains write-only fields, the desired/mirrored value for those fields are
the value last written and assumed to reside in the bits implementing these fields. Although a physical read operation would something different for these fields, the
returned value is the actual content.
UVM 1.2 Class Reference
594
needs_update
virtual function bit needs_update()
Returns 1 if any of the fields need updating
See uvm_reg_field::needs_update() for details. Use the uvm_reg::update() to actually
update the DUT register.
reset
virtual function void reset(
string kind = "HARD"
)
Reset the desired/mirrored value for this register.
Sets the desired and mirror value of the fields in this register to the reset value for the
specified reset kind. See uvm_reg_field.reset() for more details.
Also resets the semaphore that prevents concurrent access to the register. This
semaphore must be explicitly reset if a thread accessing this register array was killed in
before the access was completed
get_reset
virtual function uvm_reg_data_t get_reset(
string kind = "HARD"
)
Get the specified reset value for this register
Return the reset value for this register for the specified reset kind.
has_reset
virtual function bit has_reset(
string kind = "HARD",
bit delete = 0
)
Check if any field in the register has a reset value specified for the specified reset kind. If delete is TRUE, removes the reset value, if any.
set_reset
virtual function void set_reset(
uvm_reg_data_t value, kind = "HARD"
string )
Specify or modify the reset value for this register
Specify or modify the reset value for all the fields in the register corresponding to the
cause specified by kind.
UVM 1.2 Class Reference
595
write
virtual task write(
output uvm_status_e status, input uvm_reg_data_t value,
input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Write the specified value in this register
Write value in the DUT register that corresponds to this abstraction class instance using
the specified access path. If the register is mapped in more than one address map, an
address map must be specified if a physical access is used (front-door access). If a
back-door access path is used, the effect of writing the register through a physical
access is mimicked. For example, read-only bits in the registers will not be written.
The mirrored value will be updated using the uvm_reg::predict() method.
read
virtual task read(
output uvm_status_e status, value,
output uvm_reg_data_t input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the current value from this register
Read and return value from the DUT register that corresponds to this abstraction class
instance using the specified access path. If the register is mapped in more than one
address map, an address map must be specified if a physical access is used (front-door
access). If a back-door access path is used, the effect of reading the register through a
physical access is mimicked. For example, clear-on-read bits in the registers will be set
to zero.
The mirrored value will be updated using the uvm_reg::predict() method.
poke
virtual task poke(
output uvm_status_e status, value,
input uvm_reg_data_t input string kind
= "",
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Deposit the specified value in this register
UVM 1.2 Class Reference
596
Deposit the value in the DUT register corresponding to this abstraction class instance, asis, using a back-door access.
Uses the HDL path for the design abstraction specified by kind.
The mirrored value will be updated using the uvm_reg::predict() method.
peek
virtual task peek(
output uvm_status_e status, output uvm_reg_data_t value,
input string kind
= "",
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the current value from this register
Sample the value in the DUT register corresponding to this abstraction class instance
using a back-door access. The register value is sampled, not modified.
Uses the HDL path for the design abstraction specified by kind.
The mirrored value will be updated using the uvm_reg::predict() method.
update
virtual task update(
output uvm_status_e status, path
= UVM_DEFAULT_PATH,
input uvm_path_e input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Updates the content of the register in the design to match the desired value
This method performs the reverse operation of uvm_reg::mirror(). Write this register if
the DUT register is out-of-date with the desired/mirrored value in the abstraction class,
as determined by the uvm_reg::needs_update() method.
The update can be performed using the using the physical interfaces (frontdoor) or
uvm_reg::poke() (backdoor) access. If the register is mapped in multiple address maps
and physical access is used (front-door), an address map must be specified.
mirror
virtual task mirror(
output uvm_status_e status, check
= UVM_NO_CHECK,
input uvm_check_e input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
UVM 1.2 Class Reference
597
)
Read the register and update/check its mirror value
Read the register and optionally compared the readback value with the current mirrored
value if check is UVM_CHECK. The mirrored value will be updated using the
uvm_reg::predict() method based on the readback value.
The mirroring can be performed using the physical interfaces (frontdoor) or
uvm_reg::peek() (backdoor).
If check is specified as UVM_CHECK, an error message is issued if the current mirrored
value does not match the readback value. Any field whose check has been disabled with
uvm_reg_field::set_compare() will not be considered in the comparison.
If the register is mapped in multiple address maps and physical access is used (frontdoor access), an address map must be specified. If the register contains write-only
fields, their content is mirrored and optionally checked only if a UVM_BACKDOOR access
path is used to read the register.
predict
virtual function bit predict (
uvm_reg_data_t value, = -1,
uvm_reg_byte_en_t be
uvm_predict_e kind = UVM_PREDICT_DIRECT,
uvm_path_e path = UVM_FRONTDOOR,
uvm_reg_map map
= null,
string fname = "",
int lineno = 0
)
Update the mirrored and desired value for this register.
Predict the mirror (and desired) value of the fields in the register based on the specified
observed value on a specified address map, or based on a calculated value. See
uvm_reg_field::predict() for more details.
Returns TRUE if the prediction was successful for each field in the register.
is_busy
function bit is_busy()
Returns 1 if register is currently being read or written.
FRONTdOOR
set_frontdoor
function void set_frontdoor(
uvm_reg_frontdoor ftdr, map
= null,
uvm_reg_map string fname = "",
int lineno = 0
)
UVM 1.2 Class Reference
598
Set a user-defined frontdoor for this register
By default, registers are mapped linearly into the address space of the address maps that
instantiate them. If registers are accessed using a different mechanism, a user-defined
access mechanism must be defined and associated with the corresponding register
abstraction class
If the register is mapped in multiple address maps, an address map must be specified.
get_frontdoor
function uvm_reg_frontdoor get_frontdoor(
uvm_reg_map map = null
)
Returns the user-defined frontdoor for this register
If null, no user-defined frontdoor has been defined. A user-defined frontdoor is defined
by using the uvm_reg::set_frontdoor() method.
If the register is mapped in multiple address maps, an address map must be specified.
BAcKdOOR
set_backdoor
function void set_backdoor(
uvm_reg_backdoor bkdr, fname = "",
string int lineno = 0
)
Set a user-defined backdoor for this register
By default, registers are accessed via the built-in string-based DPI routines if an HDL
path has been specified using the uvm_reg::configure() or uvm_reg::add_hdl_path()
method.
If this default mechanism is not suitable (e.g. because the register is not implemented in
pure SystemVerilog) a user-defined access mechanism must be defined and associated
with the corresponding register abstraction class
A user-defined backdoor is required if active update of the mirror of this register
abstraction class, based on observed changes of the corresponding DUT register, is used.
get_backdoor
function uvm_reg_backdoor get_backdoor(
bit inherited = 1
)
Returns the user-defined backdoor for this register
If null, no user-defined backdoor has been defined. A user-defined backdoor is defined
by using the uvm_reg::set_backdoor() method.
UVM 1.2 Class Reference
599
If inherited is TRUE, returns the backdoor of the parent block if none have been specified
for this register.
clear_hdl_path
function void clear_hdl_path (
string kind = "RTL"
)
Delete HDL paths
Remove any previously specified HDL path to the register instance for the specified
design abstraction.
add_hdl_path
function void add_hdl_path (
uvm_hdl_path_slice slices[], string kind
= "RTL"
)
Add an HDL path
Add the specified HDL path to the register instance for the specified design abstraction. This method may be called more than once for the same design abstraction if the
register is physically duplicated in the design abstraction
For example, the following register
Bits:
1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
+-+---+-------------+---+-------+
|A|xxx|
B
|xxx|
C
|
+-+---+-------------+---+-------+
would be specified using the following literal value
add_hdl_path('{ '{"A_reg", 15, 1},
'{"B_reg", 6, 7},
'{'C_reg", 0, 4} } );
If the register is implemented using a single HDL variable, The array should specify a
single slice with its offset and size specified as -1. For example:
r1.add_hdl_path('{ '{"r1", -1, -1} });
add_hdl_path_slice
function void add_hdl_path_slice(
string name, offset, int int size, UVM 1.2 Class Reference
600
bit first
string kind
)
= 0,
= "RTL"
Append the specified HDL slice to the HDL path of the register instance for the specified
design abstraction. If first is TRUE, starts the specification of a duplicate HDL
implementation of the register.
has_hdl_path
function bit has_hdl_path (
string kind = ""
)
Check if a HDL path is specified
Returns TRUE if the register instance has a HDL path defined for the specified design
abstraction. If no design abstraction is specified, uses the default design abstraction
specified for the parent block.
get_hdl_path
function void get_hdl_path (
ref uvm_hdl_path_concat paths[$], kind
= ""
input string )
Get the incremental HDL path(s)
Returns the HDL path(s) defined for the specified design abstraction in the register
instance. Returns only the component of the HDL paths that corresponds to the register,
not a full hierarchical path
If no design abstraction is specified, the default design abstraction for the parent block is
used.
get_hdl_path_kinds
function void get_hdl_path_kinds (
ref string kinds[$]
)
Get design abstractions for which HDL paths have been defined
get_full_hdl_path
function void get_full_hdl_path (
ref uvm_hdl_path_concat paths[$], kind
= "",
input string input string separator = "."
)
Get the full hierarchical HDL path(s)
Returns the full hierarchical HDL path(s) defined for the specified design abstraction in
the register instance. There may be more than one path returned even if only one path
was defined for the register instance, if any of the parent components have more than
UVM 1.2 Class Reference
601
one path defined for the same design abstraction
If no design abstraction is specified, the default design abstraction for each ancestor
block is used to get each incremental path.
backdoor_read
virtual task backdoor_read(
uvm_reg_item rw
)
User-define backdoor read access
Override the default string-based DPI backdoor access read for this register type. By
default calls uvm_reg::backdoor_read_func().
backdoor_write
virtual task backdoor_write(
uvm_reg_item rw
)
User-defined backdoor read access
Override the default string-based DPI backdoor access write for this register type.
backdoor_read_func
virtual function uvm_status_e backdoor_read_func(
uvm_reg_item rw
)
User-defined backdoor read access
Override the default string-based DPI backdoor access read for this register type.
backdoor_watch
virtual task backdoor_watch()
User-defined DUT register change monitor
Watch the DUT register corresponding to this abstraction class instance for any change in
value and return when a value-change occurs. This may be implemented a string-based
DPI access if the simulation tool provide a value-change callback facility. Such a facility
does not exist in the standard SystemVerilog DPI and thus no default implementation
for this method can be provided.
COVERAGE
include_coverage
UVM 1.2 Class Reference
602
static function void include_coverage(
string scope, uvm_reg_cvr_t models, uvm_object accessor = null
)
Specify which coverage model that must be included in various block, register or memory
abstraction class instances.
The coverage models are specified by OR’ing or adding the uvm_coverage_model_e
coverage model identifiers corresponding to the coverage model to be included.
The scope specifies a hierarchical name or pattern identifying a block, memory or register
abstraction class instances. Any block, memory or register whose full hierarchical name
matches the specified scope will have the specified functional coverage models included
in them.
The scope can be specified as a POSIX regular expression or simple pattern. See
uvm_resource_base::Scope Interface for more details.
uvm_reg::include_coverage("*", UVM_CVR_ALL);
The specification of which coverage model to include in which abstraction class is stored
in a uvm_reg_cvr_t resource in the uvm_resource_db resource database, in the
“uvm_reg::” scope namespace.
build_coverage
protected function uvm_reg_cvr_t build_coverage(
uvm_reg_cvr_t models
)
Check if all of the specified coverage models must be built.
Check which of the specified coverage model must be built in this instance of the register
abstraction class, as specified by calls to uvm_reg::include_coverage().
Models are specified by adding the symbolic value of individual coverage model as
defined in uvm_coverage_model_e. Returns the sum of all coverage models to be built
in the register model.
add_coverage
virtual protected function void add_coverage(
uvm_reg_cvr_t models
)
Specify that additional coverage models are available.
Add the specified coverage model to the coverage models available in this class. Models
are specified by adding the symbolic value of individual coverage model as defined in
uvm_coverage_model_e.
This method shall be called only in the constructor of subsequently derived classes.
has_coverage
UVM 1.2 Class Reference
603
virtual function bit has_coverage(
uvm_reg_cvr_t models
)
Check if register has coverage model(s)
Returns TRUE if the register abstraction class contains a coverage model for all of the
models specified. Models are specified by adding the symbolic value of individual
coverage model as defined in uvm_coverage_model_e.
set_coverage
virtual function uvm_reg_cvr_t set_coverage(
uvm_reg_cvr_t is_on
)
Turns on coverage measurement.
Turns the collection of functional coverage measurements on or off for this register. The
functional coverage measurement is turned on for every coverage model specified using
uvm_coverage_model_e symbolic identifiers. Multiple functional coverage models can be
specified by adding the functional coverage model identifiers. All other functional
coverage models are turned off. Returns the sum of all functional coverage models
whose measurements were previously on.
This method can only control the measurement of functional coverage models that are
present in the register abstraction classes, then enabled during construction. See the
uvm_reg::has_coverage() method to identify the available functional coverage models.
get_coverage
virtual function bit get_coverage(
uvm_reg_cvr_t is_on
)
Check if coverage measurement is on.
Returns TRUE if measurement for all of the specified functional coverage models are
currently on. Multiple functional coverage models can be specified by adding the
functional coverage model identifiers.
See uvm_reg::set_coverage() for more details.
sample
protected virtual function void sample(
uvm_reg_data_t data,
uvm_reg_data_t byte_en,
bit is_read,
uvm_reg_map map
)
Functional coverage measurement method
This method is invoked by the register abstraction class whenever it is read or written
with the specified data via the specified address map. It is invoked after the read or
write operation has completed but before the mirror has been updated.
UVM 1.2 Class Reference
604
Empty by default, this method may be extended by the abstraction class generator to
perform the required sampling in any provided functional coverage model.
sample_values
virtual function void sample_values()
Functional coverage measurement method for field values
This method is invoked by the user or by the uvm_reg_block::sample_values() method of
the parent block to trigger the sampling of the current field values in the register-level
functional coverage model.
This method may be extended by the abstraction class generator to perform the required
sampling in any provided field-value functional coverage model.
CALLbAcKs
pre_write
virtual task pre_write(
uvm_reg_item rw
)
Called before register write.
If the specified data value, access path or address map are modified, the updated data
value, access path or address map will be used to perform the register operation. If the
status is modified to anything other than UVM_IS_OK, the operation is aborted.
The registered callback methods are invoked after the invocation of this method. All
register callbacks are executed before the corresponding field callbacks
post_write
virtual task post_write(
uvm_reg_item rw
)
Called after register write.
If the specified status is modified, the updated status will be returned by the register
operation.
The registered callback methods are invoked before the invocation of this method. All
register callbacks are executed before the corresponding field callbacks
pre_read
virtual task pre_read(
uvm_reg_item rw
)
Called before register read.
UVM 1.2 Class Reference
605
If the specified access path or address map are modified, the updated access path or
address map will be used to perform the register operation. If the status is modified to
anything other than UVM_IS_OK, the operation is aborted.
The registered callback methods are invoked after the invocation of this method. All
register callbacks are executed before the corresponding field callbacks
post_read
virtual task post_read(
uvm_reg_item rw
)
Called after register read.
If the specified readback data or status is modified, the updated readback data or status
will be returned by the register operation.
The registered callback methods are invoked before the invocation of this method. All
register callbacks are executed before the corresponding field callbacks
UVM 1.2 Class Reference
606
25.5 uvm_reg_field
Field abstraction class
A field represents a set of bits that behave consistently as a single entity.
A field is contained within a single register, but may have different access policies
depending on the address map use the access the register (thus the field).
Summary
uvm_reg_field
Field abstraction class
CLAss HIERARchY
uvm_void
uvm_object
uvm_reg_field
CLAss DEcLARATION
class uvm_reg_field extends uvm_object
value
INITIALIZATION
new
configure
INTROsPEcTION
get_name
get_full_name
get_parent
get_lsb_pos
get_n_bits
get_max_size
set_access
define_access
get_access
is_known_access
set_volatility
is_volatile
AccEss
set
get
get_mirrored_value
reset
get_reset
has_reset
set_reset
needs_update
write
read
poke
peek
mirror
set_compare
get_compare
is_indv_accessible
UVM 1.2 Class Reference
Mirrored field value.
Create a new field instance
Instance-specific configuration
Get the simple name
Get the hierarchical name
Get the parent register
Return the position of the field
Returns the width, in number of bits, of the field.
Returns the width, in number of bits, of the largest
field.
Modify the access policy of the field
Define a new access policy value
Get the access policy of the field
Check if access policy is a built-in one.
Modify the volatility of the field to the specified one.
Indicates if the field value is volatile
Set the desired value for this field
Return the desired value of the field
Return the mirrored value of the field
Reset the desired/mirrored value for this field.
Get the specified reset value for this field
Check if the field has a reset value specified
Specify or modify the reset value for this field
Check if the abstract model contains different desired
and mirrored values.
Write the specified value in this field
Read the current value from this field
Deposit the specified value in this field
Read the current value from this field
Read the field and update/check its mirror value
Sets the compare policy during a mirror update.
Returns the compare policy for this field.
Check if this field can be written individually
607
predict
CALLBAcKs
pre_write
post_write
pre_read
post_read
Update the mirrored and desired value for this field.
Called
Called
Called
Called
before field write.
after field write.
before field read.
after field read.
value
rand uvm_reg_data_t value
Mirrored field value. This value can be sampled in a functional coverage model or
constrained when randomized.
INITIALIZATION
new
function new(
string name = "uvm_reg_field"
)
Create a new field instance
This method should not be used directly. The uvm_reg_field::type_id::create()
factory method should be used instead.
configure
function void configure(
uvm_reg parent,
int unsigned size,
int unsigned lsb_pos,
string access,
bit volatile,
uvm_reg_data_t reset,
bit has_reset,
bit is_rand,
bit individually_accessible
)
Instance-specific configuration
Specify the parent register of this field, its size in bits, the position of its least-significant
bit within the register relative to the least-significant bit of the register, its access policy,
volatility, “HARD” reset value, whether the field value is actually reset (the reset value is
ignored if FALSE), whether the field value may be randomized and whether the field is
the only one to occupy a byte lane in the register.
See set_access for a specification of the pre-defined field access policies.
If the field access policy is a pre-defined policy and NOT one of “RW”, “WRC”, “WRS”,
“WO”, “W1”, or “WO1”, the value of is_rand is ignored and the rand_mode() for the field
instance is turned off since it cannot be written.
UVM 1.2 Class Reference
608
INTROsPEcTION
get_name
Get the simple name
Return the simple object name of this field
get_full_name
virtual function string get_full_name()
Get the hierarchical name
Return the hierarchal name of this field The base of the hierarchical name is the root
block.
get_parent
virtual function uvm_reg get_parent()
Get the parent register
get_lsb_pos
virtual function int unsigned get_lsb_pos()
Return the position of the field
Returns the index of the least significant bit of the field in the register that instantiates
it. An offset of 0 indicates a field that is aligned with the least-significant bit of the
register.
get_n_bits
virtual function int unsigned get_n_bits()
Returns the width, in number of bits, of the field.
get_max_size
static function int unsigned get_max_size()
Returns the width, in number of bits, of the largest field.
set_access
virtual function string set_access(
UVM 1.2 Class Reference
609
string mode
)
Modify the access policy of the field
Modify the access policy of the field to the specified one and return the previous access
policy.
The pre-defined access policies are as follows. The effect of a read operation are applied
after the current value of the field is sampled. The read operation will return the current
value, not the value affected by the read operation (if any).
”RO”
W: no effect, R: no effect
”RW”
W: as-is, R: no effect
”RC”
W: no effect, R: clears all bits
”RS”
W: no effect, R: sets all bits
”WRC”
W: as-is, R: clears all bits
”WRS”
W: as-is, R: sets all bits
”WC”
W: clears all bits, R: no effect
”WS”
W: sets all bits, R: no effect
”WSRC”
W: sets all bits, R: clears all bits
”WCRS”
W: clears all bits, R: sets all bits
”W1C”
W: 1/0 clears/no effect on matching bit, R: no effect
”W1S”
W: 1/0 sets/no effect on matching bit, R: no effect
”W1T”
W: 1/0 toggles/no effect on matching bit, R: no effect
”W0C”
W: 1/0 no effect on/clears matching bit, R: no effect
”W0S”
W: 1/0 no effect on/sets matching bit, R: no effect
”W0T”
W: 1/0 no effect on/toggles matching bit, R: no effect
”W1SRC”
W: 1/0 sets/no effect on matching bit, R: clears all bits
”W1CRS”
W: 1/0 clears/no effect on matching bit, R: sets all bits
”W0SRC”
W: 1/0 no effect on/sets matching bit, R: clears all bits
”W0CRS”
W: 1/0 no effect on/clears matching bit, R: sets all bits
”WO”
W: as-is, R: error
”WOC”
W: clears all bits, R: error
”WOS”
W: sets all bits, R: error
”W1”
W: first one after HARD reset is as-is, other W have no effects,
R: no effect
”WO1”
W: first one after HARD reset is as-is, other W have no effects,
R: error
”NOACCESS”
W: no effect, R: no effect
It is important to remember that modifying the access of a field will make the register
model diverge from the specification that was used to create it.
define_access
static function bit define_access(
string name
)
UVM 1.2 Class Reference
610
Define a new access policy value
Because field access policies are specified using string values, there is no way for
SystemVerilog to verify if a specific access value is valid or not. To help catch typing
errors, user-defined access values must be defined using this method to avoid begin
reported as an invalid access policy.
The name of field access policies are always converted to all uppercase.
Returns TRUE if the new access policy was not previously defined. Returns FALSE
otherwise but does not issue an error message.
get_access
virtual function string get_access(
uvm_reg_map map = null
)
Get the access policy of the field
Returns the current access policy of the field when written and read through the specified
address map. If the register containing the field is mapped in multiple address map, an
address map must be specified. The access policy of a field from a specific address map
may be restricted by the register’s access policy in that address map. For example, a
RW field may only be writable through one of the address maps and read-only through
all of the other maps. If the field access contradicts the map’s access value (field access
of WO, and map access value of RO, etc), the method’s return value is NOACCESS.
is_known_access
virtual function bit is_known_access(
uvm_reg_map map = null
)
Check if access policy is a built-in one.
Returns TRUE if the current access policy of the field, when written and read through the
specified address map, is a built-in access policy.
set_volatility
virtual function void set_volatility(
bit volatile
)
Modify the volatility of the field to the specified one.
It is important to remember that modifying the volatility of a field will make the register
model diverge from the specification that was used to create it.
is_volatile
virtual function bit is_volatile()
Indicates if the field value is volatile
UVM 1.2 Class Reference
611
UVM uses the IEEE 1685-2009 IP-XACT definition of “volatility”. If TRUE, the value of
the register is not predictable because it may change between consecutive accesses. This typically indicates a field whose value is updated by the DUT. The nature or cause
of the change is not specified. If FALSE, the value of the register is not modified
between consecutive accesses.
AccEss
set
virtual function void set(
uvm_reg_data_t value, string fname = "",
int lineno = 0
)
Set the desired value for this field
It sets the desired value of the field to the specified value modified by the field access
policy. It does not actually set the value of the field in the design, only the desired
value in the abstraction class. Use the uvm_reg::update() method to update the actual
register with the desired value or the uvm_reg_field::write() method to actually write the
field and update its mirrored value.
The final desired value in the mirror is a function of the field access policy and the set
value, just like a normal physical write operation to the corresponding bits in the
hardware. As such, this method (when eventually followed by a call to
uvm_reg::update()) is a zero-time functional replacement for the uvm_reg_field::write()
method. For example, the desired value of a read-only field is not modified by this
method and the desired value of a write-once field can only be set if the field has not yet
been written to using a physical (for example, front-door) write operation.
Use the uvm_reg_field::predict() to modify the mirrored value of the field.
get
virtual function uvm_reg_data_t get(
string fname = "",
int lineno = 0
)
Return the desired value of the field
It does not actually read the value of the field in the design, only the desired value in
the abstraction class. Unless set to a different value using the uvm_reg_field::set(), the
desired value and the mirrored value are identical.
Use the uvm_reg_field::read() or uvm_reg_field::peek() method to get the actual field
value.
If the field is write-only, the desired/mirrored value is the value last written and
assumed to reside in the bits implementing it. Although a physical read operation would
something different, the returned value is the actual content.
get_mirrored_value
UVM 1.2 Class Reference
612
virtual function uvm_reg_data_t get_mirrored_value(
string fname = "",
int lineno = 0
)
Return the mirrored value of the field
It does not actually read the value of the field in the design, only the mirrored value in
the abstraction class.
If the field is write-only, the desired/mirrored value is the value last written and
assumed to reside in the bits implementing it. Although a physical read operation would
something different, the returned value is the actual content.
reset
virtual function void reset(
string kind = "HARD"
)
Reset the desired/mirrored value for this field.
It sets the desired and mirror value of the field to the reset event specified by kind. If
the field does not have a reset value specified for the specified reset kind the field is
unchanged.
It does not actually reset the value of the field in the design, only the value mirrored in
the field abstraction class.
Write-once fields can be modified after a “HARD” reset operation.
get_reset
virtual function uvm_reg_data_t get_reset(
string kind = "HARD"
)
Get the specified reset value for this field
Return the reset value for this field for the specified reset kind. Returns the current field
value is no reset value has been specified for the specified reset event.
has_reset
virtual function bit has_reset(
string kind = "HARD",
bit delete = 0
)
Check if the field has a reset value specified
Return TRUE if this field has a reset value specified for the specified reset kind. If delete
is TRUE, removes the reset value, if any.
set_reset
virtual function void set_reset(
UVM 1.2 Class Reference
613
uvm_reg_data_t value, string kind = "HARD"
)
Specify or modify the reset value for this field
Specify or modify the reset value for this field corresponding to the cause specified by
kind.
needs_update
virtual function bit needs_update()
Check if the abstract model contains different desired and mirrored values.
If a desired field value has been modified in the abstraction class without actually
updating the field in the DUT, the state of the DUT (more specifically what the
abstraction class thinks the state of the DUT is) is outdated. This method returns TRUE
if the state of the field in the DUT needs to be updated to match the desired value. The
mirror values or actual content of DUT field are not modified. Use the
uvm_reg::update() to actually update the DUT field.
write
virtual task write (
output uvm_status_e status, value,
input uvm_reg_data_t input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Write the specified value in this field
Write value in the DUT field that corresponds to this abstraction class instance using the
specified access path. If the register containing this field is mapped in more than one
address map, an address map must be specified if a physical access is used (front-door
access). If a back-door access path is used, the effect of writing the field through a
physical access is mimicked. For example, read-only bits in the field will not be written.
The mirrored value will be updated using the uvm_reg_field::predict() method.
If a front-door access is used, and if the field is the only field in a byte lane and if the
physical interface corresponding to the address map used to access the field support
byte-enabling, then only the field is written. Otherwise, the entire register containing
the field is written, and the mirrored values of the other fields in the same register are
used in a best-effort not to modify their value.
If a backdoor access is used, a peek-modify-poke process is used. in a best-effort not to
modify the value of the other fields in the register.
read
virtual task read (
output uvm_status_e output uvm_reg_data_t UVM 1.2 Class Reference
status,
value,
614
)
input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
Read the current value from this field
Read and return value from the DUT field that corresponds to this abstraction class
instance using the specified access path. If the register containing this field is mapped in
more than one address map, an address map must be specified if a physical access is
used (front-door access). If a back-door access path is used, the effect of reading the
field through a physical access is mimicked. For example, clear-on-read bits in the field
will be set to zero.
The mirrored value will be updated using the uvm_reg_field::predict() method.
If a front-door access is used, and if the field is the only field in a byte lane and if the
physical interface corresponding to the address map used to access the field support
byte-enabling, then only the field is read. Otherwise, the entire register containing the
field is read, and the mirrored values of the other fields in the same register are
updated.
If a backdoor access is used, the entire containing register is peeked and the mirrored
value of the other fields in the register is updated.
poke
virtual task poke (
output uvm_status_e status, value,
input uvm_reg_data_t input string kind
= "",
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Deposit the specified value in this field
Deposit the value in the DUT field corresponding to this abstraction class instance, as-is,
using a back-door access. A peek-modify-poke process is used in a best-effort not to
modify the value of the other fields in the register.
The mirrored value will be updated using the uvm_reg_field::predict() method.
peek
virtual task peek (
output uvm_status_e status, value,
output uvm_reg_data_t input string kind
= "",
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the current value from this field
Sample the value in the DUT field corresponding to this abstraction class instance using a
UVM 1.2 Class Reference
615
back-door access. The field value is sampled, not modified.
Uses the HDL path for the design abstraction specified by kind.
The entire containing register is peeked and the mirrored value of the other fields in the
register are updated using the uvm_reg_field::predict() method.
mirror
virtual task mirror(
output uvm_status_e status, input uvm_check_e check
= UVM_NO_CHECK,
input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the field and update/check its mirror value
Read the field and optionally compared the readback value with the current mirrored
value if check is UVM_CHECK. The mirrored value will be updated using the predict()
method based on the readback value.
The path argument specifies whether to mirror using the UVM_FRONTDOOR (read) or
UVM_BACKDOOR (peek()).
If check is specified as UVM_CHECK, an error message is issued if the current mirrored
value does not match the readback value, unless set_compare was used disable the
check.
If the containing register is mapped in multiple address maps and physical access is used
(front-door access), an address map must be specified. For write-only fields, their
content is mirrored and optionally checked only if a UVM_BACKDOOR access path is used
to read the field.
set_compare
function void set_compare(
uvm_check_e check = UVM_CHECK
)
Sets the compare policy during a mirror update. The field value is checked against its
mirror only when both the check argument in uvm_reg_block::mirror, uvm_reg::mirror,
or uvm_reg_field::mirror and the compare policy for the field is UVM_CHECK.
get_compare
function uvm_check_e get_compare()
Returns the compare policy for this field.
is_indv_accessible
function bit is indv accessible (
UVM 1.2 Class Reference
616
uvm_path_e path,
uvm_reg_map local_map
)
Check if this field can be written individually, i.e. without affecting other fields in the
containing register.
predict
function bit predict (
uvm_reg_data_t value, uvm_reg_byte_en_t be
= -1,
uvm_predict_e kind = UVM_PREDICT_DIRECT,
uvm_path_e path = UVM_FRONTDOOR,
uvm_reg_map map
= null,
string fname = "",
int lineno = 0
)
Update the mirrored and desired value for this field.
Predict the mirror and desired value of the field based on the specified observed value
on a bus using the specified address map.
If kind is specified as UVM_PREDICT_READ, the value was observed in a read transaction
on the specified address map or backdoor (if path is UVM_BACKDOOR). If kind is
specified as UVM_PREDICT_WRITE, the value was observed in a write transaction on the
specified address map or backdoor (if path is UVM_BACKDOOR). If kind is specified as
UVM_PREDICT_DIRECT, the value was computed and is updated as-is, without regard to
any access policy. For example, the mirrored value of a read-only field is modified by
this method if kind is specified as UVM_PREDICT_DIRECT.
This method does not allow an update of the mirror (or desired) when the register
containing this field is busy executing a transaction because the results are unpredictable
and indicative of a race condition in the testbench.
Returns TRUE if the prediction was successful.
CALLBAcKs
pre_write
virtual task pre_write (
uvm_reg_item rw
)
Called before field write.
If the specified data value, access path or address map are modified, the updated data
value, access path or address map will be used to perform the register operation. If the
status is modified to anything other than UVM_IS_OK, the operation is aborted.
The field callback methods are invoked after the callback methods on the containing
register. The registered callback methods are invoked after the invocation of this
method.
post_write
UVM 1.2 Class Reference
617
virtual task post_write (
uvm_reg_item rw
)
Called after field write.
If the specified status is modified, the updated status will be returned by the register
operation.
The field callback methods are invoked after the callback methods on the containing
register. The registered callback methods are invoked before the invocation of this
method.
pre_read
virtual task pre_read (
uvm_reg_item rw
)
Called before field read.
If the access path or address map in the rw argument are modified, the updated access
path or address map will be used to perform the register operation. If the status is
modified to anything other than UVM_IS_OK, the operation is aborted.
The field callback methods are invoked after the callback methods on the containing
register. The registered callback methods are invoked after the invocation of this
method.
post_read
virtual task post_read (
uvm_reg_item rw
)
Called after field read.
If the specified readback data or~status~ in the rw argument is modified, the updated
readback data or status will be returned by the register operation.
The field callback methods are invoked after the callback methods on the containing
register. The registered callback methods are invoked before the invocation of this
method.
UVM 1.2 Class Reference
618
25.6 uvm_mem
Memory abstraction base class
A memory is a collection of contiguous locations. A memory may be accessible via more
than one address map.
Unlike registers, memories are not mirrored because of the potentially large data space:
tests that walk the entire memory space would negate any benefit from sparse memory
modelling techniques. Rather than relying on a mirror, it is recommended that backdoor
access be used instead.
Summary
uvm_mem
Memory abstraction base class
CLAss HIERARchY
uvm_void
uvm_object
uvm_mem
CLAss DEcLARATION
class uvm_mem extends uvm_object
INITIALIZATION
new
configure
set_offset
Modifying the offset of a
memory will make the abstract
model
mam
INTROsPEcTION
get_name
get_full_name
get_parent
get_n_maps
is_in_map
get_maps
get_rights
get_access
get_size
get_n_bytes
get_n_bits
get_max_size
get_virtual_registers
get_virtual_fields
UVM 1.2 Class Reference
Create a new instance and type-specific
configuration
Instance-specific configuration
Modify the offset of the memory
diverge from the specification that was
used to create it.
Memory allocation manager
Get the simple name
Get the hierarchical name
Get the parent block
Returns the number of address maps this
memory is mapped in
Return TRUE if this memory is in the
specified address map
Returns all of the address maps where this
memory is mapped
Returns the access rights of this memory.
Returns the access policy of the memory
when written and read via an address
map.
Returns the number of unique memory
locations in this memory.
Return the width, in number of bytes, of
each memory location
Returns the width, in number of bits, of
each memory location
Returns the maximum width, in number of
bits, of all memories
Return the virtual registers in this memory
Return the virtual fields in the memory
619
get_vreg_by_name
get_vfield_by_name
get_vreg_by_offset
get_offset
get_address
get_addresses
HDL AccEss
write
read
burst_write
burst_read
poke
peek
FRONTdOOR
set_frontdoor
get_frontdoor
BAcKdOOR
set_backdoor
get_backdoor
clear_hdl_path
add_hdl_path
add_hdl_path_slice
has_hdl_path
get_hdl_path
get_full_hdl_path
get_hdl_path_kinds
backdoor_read
backdoor_write
backdoor_read_func
CALLbAcKs
pre_write
post_write
pre_read
post_read
COVERAGE
build_coverage
add_coverage
has_coverage
set_coverage
get_coverage
sample
Find the named virtual register
Find the named virtual field
Find the virtual register implemented at
the specified offset
Returns the base offset of a memory
location
Returns the base external physical address
of a memory location
Identifies the external physical
address(es) of a memory location
Write the specified value in a memory
location
Read the current value from a memory
location
Write the specified values in memory
locations
Read values from memory locations
Deposit the specified value in a memory
location
Read the current value from a memory
location
Set a user-defined frontdoor for this
memory
Returns the user-defined frontdoor for this
memory
Set a user-defined backdoor for this
memory
Returns the user-defined backdoor for this
memory
Delete HDL paths
Add an HDL path
Add the specified HDL slice to the HDL
path for the specified design abstraction.
Check if a HDL path is specified
Get the incremental HDL path(s)
Get the full hierarchical HDL path(s)
Get design abstractions for which HDL
paths have been defined
User-define backdoor read access
User-defined backdoor read access
User-defined backdoor read access
Called
Called
Called
Called
before memory write.
after memory write.
before memory read.
after memory read.
Check if all of the specified coverage
model must be built.
Specify that additional coverage models
are available.
Check if memory has coverage model(s)
Turns on coverage measurement.
Check if coverage measurement is on.
Functional coverage measurement method
INITIALIZATION
UVM 1.2 Class Reference
620
new
function new (
string name,
longint unsigned size,
int unsigned n_bits,
string access
= "RW",
int has_coverage = UVM_NO_COVERAGE
)
Create a new instance and type-specific configuration
Creates an instance of a memory abstraction class with the specified name.
size specifies the total number of memory locations. n_bits specifies the total number of
bits in each memory location. access specifies the access policy of this memory and may
be one of “RW for RAMs and “RO” for ROMs.
has_coverage specifies which functional coverage models are present in the extension of
the register abstraction class. Multiple functional coverage models may be specified by
adding their symbolic names, as defined by the uvm_coverage_model_e type.
configure
function void configure (
uvm_reg_block parent, hdl_path = ""
string )
Instance-specific configuration
Specify the parent block of this memory.
If this memory is implemented in a single HDL variable, its name is specified as the
hdl_path. Otherwise, if the memory is implemented as a concatenation of variables
(usually one per bank), then the HDL path must be specified using the add_hdl_path() or
add_hdl_path_slice() method.
set_offset
Modify the offset of the memory
The offset of a memory within an address map is set using the
uvm_reg_map::add_mem() method. This method is used to modify that offset
dynamically.
Modifying the offset of a memory will make the abstract model
diverge from the specification that was used to create it.
mam
uvm_mem_mam mam
Memory allocation manager
UVM 1.2 Class Reference
621
Memory allocation manager for the memory corresponding to this abstraction class
instance. Can be used to allocate regions of consecutive addresses of specific sizes, such
as DMA buffers, or to locate virtual register array.
INTROsPEcTION
get_name
Get the simple name
Return the simple object name of this memory.
get_full_name
virtual function string get_full_name()
Get the hierarchical name
Return the hierarchal name of this memory. The base of the hierarchical name is the
root block.
get_parent
virtual function uvm_reg_block get_parent ()
Get the parent block
get_n_maps
virtual function int get_n_maps ()
Returns the number of address maps this memory is mapped in
is_in_map
function bit is_in_map (
uvm_reg_map map
)
Return TRUE if this memory is in the specified address map
get_maps
virtual function void get_maps (
ref uvm_reg_map maps[$]
)
Returns all of the address maps where this memory is mapped
UVM 1.2 Class Reference
622
get_rights
virtual function string get_rights (
uvm_reg_map map = null
)
Returns the access rights of this memory.
Returns “RW”, “RO” or “WO”. The access rights of a memory is always “RW”, unless it is
a shared memory with access restriction in a particular address map.
If no address map is specified and the memory is mapped in only one address map, that
address map is used. If the memory is mapped in more than one address map, the
default address map of the parent block is used.
If an address map is specified and the memory is not mapped in the specified address
map, an error message is issued and “RW” is returned.
get_access
virtual function string get_access(
uvm_reg_map map = null
)
Returns the access policy of the memory when written and read via an address map.
If the memory is mapped in more than one address map, an address map must be
specified. If access restrictions are present when accessing a memory through the
specified address map, the access mode returned takes the access restrictions into
account. For example, a read-write memory accessed through a domain with read-only
restrictions would return “RO”.
get_size
function longint unsigned get_size()
Returns the number of unique memory locations in this memory.
get_n_bytes
function int unsigned get_n_bytes()
Return the width, in number of bytes, of each memory location
get_n_bits
function int unsigned get_n_bits()
Returns the width, in number of bits, of each memory location
get_max_size
static function int unsigned get_max_size()
UVM 1.2 Class Reference
623
Returns the maximum width, in number of bits, of all memories
get_virtual_registers
virtual function void get_virtual_registers(
ref uvm_vreg regs[$]
)
Return the virtual registers in this memory
Fills the specified array with the abstraction class for all of the virtual registers
implemented in this memory. The order in which the virtual registers are located in the
array is not specified.
get_virtual_fields
virtual function void get_virtual_fields(
ref uvm_vreg_field fields[$]
)
Return the virtual fields in the memory
Fills the specified dynamic array with the abstraction class for all of the virtual fields
implemented in this memory. The order in which the virtual fields are located in the
array is not specified.
get_vreg_by_name
virtual function uvm_vreg get_vreg_by_name(
string name
)
Find the named virtual register
Finds a virtual register with the specified name implemented in this memory and returns
its abstraction class instance. If no virtual register with the specified name is found,
returns null.
get_vfield_by_name
virtual function uvm_vreg_field get_vfield_by_name(
string name
)
Find the named virtual field
Finds a virtual field with the specified name implemented in this memory and returns its
abstraction class instance. If no virtual field with the specified name is found, returns
null.
get_vreg_by_offset
virtual function uvm_vreg get_vreg_by_offset(
uvm_reg_addr_t offset, UVM 1.2 Class Reference
624
uvm_reg_map )
map
= null
Find the virtual register implemented at the specified offset
Finds the virtual register implemented in this memory at the specified offset in the
specified address map and returns its abstraction class instance. If no virtual register at
the offset is found, returns null.
get_offset
virtual function uvm_reg_addr_t get_offset (
uvm_reg_addr_t offset = 0,
uvm_reg_map map
= null
)
Returns the base offset of a memory location
Returns the base offset of the specified location in this memory in an address map.
If no address map is specified and the memory is mapped in only one address map, that
address map is used. If the memory is mapped in more than one address map, the
default address map of the parent block is used.
If an address map is specified and the memory is not mapped in the specified address
map, an error message is issued.
get_address
virtual function uvm_reg_addr_t get_address(
uvm_reg_addr_t offset = 0,
uvm_reg_map map
= null
)
Returns the base external physical address of a memory location
Returns the base external physical address of the specified location in this memory if
accessed through the specified address map.
If no address map is specified and the memory is mapped in only one address map, that
address map is used. If the memory is mapped in more than one address map, the
default address map of the parent block is used.
If an address map is specified and the memory is not mapped in the specified address
map, an error message is issued.
get_addresses
virtual function int get_addresses(
uvm_reg_addr_t offset = 0,
uvm_reg_map map
= null,
ref uvm_reg_addr_t addr[] )
Identifies the external physical address(es) of a memory location
Computes all of the external physical addresses that must be accessed to completely
read or write the specified location in this memory. The addressed are specified in little
endian order. Returns the number of bytes transferred on each access.
UVM 1.2 Class Reference
625
If no address map is specified and the memory is mapped in only one address map, that
address map is used. If the memory is mapped in more than one address map, the
default address map of the parent block is used.
If an address map is specified and the memory is not mapped in the specified address
map, an error message is issued.
HDL AccEss
write
virtual task write(
output uvm_status_e status, input uvm_reg_addr_t offset, input uvm_reg_data_t value,
path
= UVM_DEFAULT_PATH,
input uvm_path_e input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Write the specified value in a memory location
Write value in the memory location that corresponds to this abstraction class instance at
the specified offset using the specified access path. If the memory is mapped in more
than one address map, an address map must be specified if a physical access is used
(front-door access). If a back-door access path is used, the effect of writing the register
through a physical access is mimicked. For example, a read-only memory will not be
written.
read
virtual task read(
output uvm_status_e status, offset, input uvm_reg_addr_t output uvm_reg_data_t value,
path
= UVM_DEFAULT_PATH,
input uvm_path_e input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the current value from a memory location
Read and return value from the memory location that corresponds to this abstraction
class instance at the specified offset using the specified access path. If the register is
mapped in more than one address map, an address map must be specified if a physical
access is used (front-door access).
burst_write
virtual task burst_write(
output uvm_status_e UVM 1.2 Class Reference
status,
626
)
input uvm_reg_addr_t offset, input uvm_reg_data_t value[], input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
Write the specified values in memory locations
Burst-write the specified values in the memory locations beginning at the specified
offset. If the memory is mapped in more than one address map, an address map must
be specified if not using the backdoor. If a back-door access path is used, the effect of
writing the register through a physical access is mimicked. For example, a read-only
memory will not be written.
burst_read
virtual task burst_read(
output uvm_status_e status, offset, input uvm_reg_addr_t ref uvm_reg_data_t value[], path
= UVM_DEFAULT_PATH,
input uvm_path_e input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read values from memory locations
Burst-read into values the data the memory locations beginning at the specified offset. If the memory is mapped in more than one address map, an address map must be
specified if not using the backdoor. If a back-door access path is used, the effect of
writing the register through a physical access is mimicked. For example, a read-only
memory will not be written.
poke
virtual task poke(
output uvm_status_e status, offset, input uvm_reg_addr_t input uvm_reg_data_t value,
kind
= "",
input string input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Deposit the specified value in a memory location
Deposit the value in the DUT memory location corresponding to this abstraction class
instance at the specified offset, as-is, using a back-door access.
Uses the HDL path for the design abstraction specified by kind.
peek
UVM 1.2 Class Reference
627
virtual task peek(
output uvm_status_e status, input uvm_reg_addr_t offset, output uvm_reg_data_t value,
kind
= "",
input string input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the current value from a memory location
Sample the value in the DUT memory location corresponding to this abstraction class
instance at the specified offset using a back-door access. The memory location value is
sampled, not modified.
Uses the HDL path for the design abstraction specified by kind.
FRONTdOOR
set_frontdoor
function void set_frontdoor(
uvm_reg_frontdoor ftdr, map
= null,
uvm_reg_map string fname = "",
int lineno = 0
)
Set a user-defined frontdoor for this memory
By default, memories are mapped linearly into the address space of the address maps
that instantiate them. If memories are accessed using a different mechanism, a userdefined access mechanism must be defined and associated with the corresponding
memory abstraction class
If the memory is mapped in multiple address maps, an address map must be specified.
get_frontdoor
function uvm_reg_frontdoor get_frontdoor(
uvm_reg_map map = null
)
Returns the user-defined frontdoor for this memory
If null, no user-defined frontdoor has been defined. A user-defined frontdoor is defined
by using the uvm_mem::set_frontdoor() method.
If the memory is mapped in multiple address maps, an address map must be specified.
BAcKdOOR
set_backdoor
UVM 1.2 Class Reference
628
function void set_backdoor (
uvm_reg_backdoor bkdr, string fname = "",
int lineno = 0
)
Set a user-defined backdoor for this memory
By default, memories are accessed via the built-in string-based DPI routines if an HDL
path has been specified using the uvm_mem::configure() or uvm_mem::add_hdl_path()
method. If this default mechanism is not suitable (e.g. because the memory is not
implemented in pure SystemVerilog) a user-defined access mechanism must be defined
and associated with the corresponding memory abstraction class
get_backdoor
function uvm_reg_backdoor get_backdoor(
bit inherited = 1
)
Returns the user-defined backdoor for this memory
If null, no user-defined backdoor has been defined. A user-defined backdoor is defined
by using the uvm_reg::set_backdoor() method.
If inherit is TRUE, returns the backdoor of the parent block if none have been specified
for this memory.
clear_hdl_path
function void clear_hdl_path (
string kind = "RTL"
)
Delete HDL paths
Remove any previously specified HDL path to the memory instance for the specified
design abstraction.
add_hdl_path
function void add_hdl_path (
uvm_hdl_path_slice slices[], kind
= "RTL"
string )
Add an HDL path
Add the specified HDL path to the memory instance for the specified design abstraction. This method may be called more than once for the same design abstraction if the
memory is physically duplicated in the design abstraction
add_hdl_path_slice
function void add_hdl_path_slice(
string name, offset, int UVM 1.2 Class Reference
629
int size,
bit first
string kind
)
= 0,
= "RTL"
Add the specified HDL slice to the HDL path for the specified design abstraction. If first
is TRUE, starts the specification of a duplicate HDL implementation of the memory.
has_hdl_path
function bit has_hdl_path (
string kind = ""
)
Check if a HDL path is specified
Returns TRUE if the memory instance has a HDL path defined for the specified design
abstraction. If no design abstraction is specified, uses the default design abstraction
specified for the parent block.
get_hdl_path
function void get_hdl_path (
ref uvm_hdl_path_concat paths[$], kind
= ""
input string )
Get the incremental HDL path(s)
Returns the HDL path(s) defined for the specified design abstraction in the memory
instance. Returns only the component of the HDL paths that corresponds to the
memory, not a full hierarchical path
If no design abstraction is specified, the default design abstraction for the parent block is
used.
get_full_hdl_path
function void get_full_hdl_path (
ref uvm_hdl_path_concat paths[$], kind
= "",
input string input string separator = "."
)
Get the full hierarchical HDL path(s)
Returns the full hierarchical HDL path(s) defined for the specified design abstraction in
the memory instance. There may be more than one path returned even if only one path
was defined for the memory instance, if any of the parent components have more than
one path defined for the same design abstraction
If no design abstraction is specified, the default design abstraction for each ancestor
block is used to get each incremental path.
get_hdl_path_kinds
function void get_hdl_path_kinds (
ref string kinds[$]
UVM 1.2 Class Reference
630
)
Get design abstractions for which HDL paths have been defined
backdoor_read
virtual protected task backdoor_read(
uvm_reg_item rw
)
User-define backdoor read access
Override the default string-based DPI backdoor access read for this memory type. By
default calls uvm_mem::backdoor_read_func().
backdoor_write
virtual task backdoor_write(
uvm_reg_item rw
)
User-defined backdoor read access
Override the default string-based DPI backdoor access write for this memory type.
backdoor_read_func
virtual function uvm_status_e backdoor_read_func(
uvm_reg_item rw
)
User-defined backdoor read access
Override the default string-based DPI backdoor access read for this memory type.
CALLbAcKs
pre_write
virtual task pre_write(
uvm_reg_item rw
)
Called before memory write.
If the offset, value, access path, or address map are modified, the updated offset, data
value, access path or address map will be used to perform the memory operation. If the
status is modified to anything other than UVM_IS_OK, the operation is aborted.
The registered callback methods are invoked after the invocation of this method.
post_write
UVM 1.2 Class Reference
631
virtual task post_write(
uvm_reg_item rw
)
Called after memory write.
If the status is modified, the updated status will be returned by the memory operation.
The registered callback methods are invoked before the invocation of this method.
pre_read
virtual task pre_read(
uvm_reg_item rw
)
Called before memory read.
If the offset, access path or address map are modified, the updated offset, access path
or address map will be used to perform the memory operation. If the status is modified
to anything other than UVM_IS_OK, the operation is aborted.
The registered callback methods are invoked after the invocation of this method.
post_read
virtual task post_read(
uvm_reg_item rw
)
Called after memory read.
If the readback data or status is modified, the updated readback //data or status will be
returned by the memory operation.
The registered callback methods are invoked before the invocation of this method.
COVERAGE
build_coverage
protected function uvm_reg_cvr_t build_coverage(
uvm_reg_cvr_t models
)
Check if all of the specified coverage model must be built.
Check which of the specified coverage model must be built in this instance of the
memory abstraction class, as specified by calls to uvm_reg::include_coverage().
Models are specified by adding the symbolic value of individual coverage model as
defined in uvm_coverage_model_e. Returns the sum of all coverage models to be built
in the memory model.
UVM 1.2 Class Reference
632
add_coverage
virtual protected function void add_coverage(
uvm_reg_cvr_t models
)
Specify that additional coverage models are available.
Add the specified coverage model to the coverage models available in this class. Models
are specified by adding the symbolic value of individual coverage model as defined in
uvm_coverage_model_e.
This method shall be called only in the constructor of subsequently derived classes.
has_coverage
virtual function bit has_coverage(
uvm_reg_cvr_t models
)
Check if memory has coverage model(s)
Returns TRUE if the memory abstraction class contains a coverage model for all of the
models specified. Models are specified by adding the symbolic value of individual
coverage model as defined in uvm_coverage_model_e.
set_coverage
virtual function uvm_reg_cvr_t set_coverage(
uvm_reg_cvr_t is_on
)
Turns on coverage measurement.
Turns the collection of functional coverage measurements on or off for this memory. The
functional coverage measurement is turned on for every coverage model specified using
uvm_coverage_model_e symbolic identifiers. Multiple functional coverage models can be
specified by adding the functional coverage model identifiers. All other functional
coverage models are turned off. Returns the sum of all functional coverage models
whose measurements were previously on.
This method can only control the measurement of functional coverage models that are
present in the memory abstraction classes, then enabled during construction. See the
uvm_mem::has_coverage() method to identify the available functional coverage models.
get_coverage
virtual function bit get_coverage(
uvm_reg_cvr_t is_on
)
Check if coverage measurement is on.
Returns TRUE if measurement for all of the specified functional coverage models are
currently on. Multiple functional coverage models can be specified by adding the
functional coverage model identifiers.
See uvm_mem::set_coverage() for more details.
UVM 1.2 Class Reference
633
sample
protected virtual function void sample(
uvm_reg_addr_t offset,
bit is_read,
uvm_reg_map map
)
Functional coverage measurement method
This method is invoked by the memory abstraction class whenever an address within one
of its address map is successfully read or written. The specified offset is the offset within
the memory, not an absolute address.
Empty by default, this method may be extended by the abstraction class generator to
perform the required sampling in any provided functional coverage model.
UVM 1.2 Class Reference
634
25.7 uvm_reg_indirect_data
Indirect data access abstraction class
Models the behavior of a register used to indirectly access a register array, indexed by a
second address register.
This class should not be instantiated directly. A type-specific class extension should be
used to provide a factory-enabled constructor and specify the n_bits and coverage
models.
Summary
uvm_reg_indirect_data
Indirect data access abstraction class
CLAss HIERARchY
uvm_void
uvm_object
uvm_reg
uvm_reg_indirect_data
CLAss DEcLARATION
class uvm_reg_indirect_data extends uvm_reg
METhOds
new
configure
Create an instance of this class
Configure the indirect data register.
METhOds
new
function new(
string name
= "uvm_reg_indirect",
int unsigned n_bits, int has_cover )
Create an instance of this class
Should not be called directly, other than via super.new(). The value of n_bits must
match the number of bits in the indirect register array.
configure
function void configure (
uvm_reg idx,
reg_a[],
uvm_reg uvm_reg_block blk_parent,
UVM 1.2 Class Reference
635
uvm_reg_file regfile_parent = null
)
Configure the indirect data register.
The idx register specifies the index, in the reg_a register array, of the register to
access. The idx must be written to first. A read or write operation to this register will
subsequently read or write the indexed register in the register array.
The number of bits in each register in the register array must be equal to n_bits of this
register.
See uvm_reg::configure() for the remaining arguments.
UVM 1.2 Class Reference
636
25.8 uvm_reg_fifo
This special register models a DUT FIFO accessed via write/read, where writes push to
the FIFO and reads pop from it.
Backdoor access is not enabled, as it is not yet possible to force complete FIFO state, i.e.
the write and read indexes used to access the FIFO data.
Summary
uvm_reg_fifo
This special register models a DUT FIFO accessed via write/read, where writes
push to the FIFO and reads pop from it.
CLAss HIERARchY
uvm_void
uvm_object
uvm_reg
uvm_reg_fifo
CLAss DEcLARATION
class uvm_reg_fifo extends uvm_reg
fifo
INITIALIZATION
new
set_compare
INTROsPEcTION
size
capacity
AccEss
write
read
set
update
mirror
get
do_predict
SPEcIAL
OVERRIdEs
pre_write
pre_read
The abstract representation of the FIFO.
Creates an instance of a FIFO register having size elements
of n_bits each.
Sets the compare policy during a mirror (read) of the DUT
FIFO.
The number of entries currently in the FIFO.
The maximum number of entries, or depth, of the FIFO.
Pushes the given value to the DUT FIFO.
Reads the next value out of the DUT FIFO.
Pushes the given value to the abstract FIFO.
Pushes (writes) all values preloaded using set() to the DUT.
Reads the next value out of the DUT FIFO.
Returns the next value from the abstract FIFO, but does not
pop it.
Updates the abstract (mirror) FIFO based on write() and
read() operations.
Special pre-processing for a write() or update().
Special post-processing for a write() or update().
fifo
rand uvm_reg_data_t fifo[$]
The abstract representation of the FIFO. Constrained to be no larger than the size
UVM 1.2 Class Reference
637
parameter. It is public to enable subtypes to add constraints on it and randomize.
INITIALIZATION
new
function new(
string name
= "reg_fifo",
int unsigned size,
int unsigned n_bits, int has_cover )
Creates an instance of a FIFO register having size elements of n_bits each.
set_compare
function void set_compare(
uvm_check_e check = UVM_CHECK
)
Sets the compare policy during a mirror (read) of the DUT FIFO. The DUT read value is
checked against its mirror only when both the check argument in the mirror() call and
the compare policy for the field is UVM_CHECK.
INTROsPEcTION
size
function int unsigned size()
The number of entries currently in the FIFO.
capacity
function int unsigned capacity()
The maximum number of entries, or depth, of the FIFO.
AccEss
write
Pushes the given value to the DUT FIFO. If auto-prediction is enabled, the written value
is also pushed to the abstract FIFO before the call returns. If auto-prediction is not
enabled (via uvm_reg_map::set_auto_predict), the value is pushed to abstract FIFO only
when the write operation is observed on the target bus. This mode requires using the
UVM 1.2 Class Reference
638
uvm_reg_predictor class. If the write is via an update() operation, the abstract FIFO
already contains the written value and is thus not affected by either prediction mode.
read
Reads the next value out of the DUT FIFO. If auto-prediction is enabled, the frontmost
value in abstract FIFO is popped.
set
virtual function void set(
uvm_reg_data_t value, string fname = "",
int lineno = 0
)
Pushes the given value to the abstract FIFO. You may call this method several times
before an update() as a means of preloading the DUT FIFO. Calls to set() to a full FIFO
are ignored. You must call update() to update the DUT FIFO with your set values.
update
virtual task update(
output uvm_status_e status, path
= UVM_DEFAULT_PATH,
input uvm_path_e input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Pushes (writes) all values preloaded using set() to the DUT. You must update after set
before any blocking statements, else other reads/writes to the DUT FIFO may cause the
mirror to become out of sync with the DUT.
mirror
Reads the next value out of the DUT FIFO. If auto-prediction is enabled, the frontmost
value in abstract FIFO is popped. If the check argument is set and comparison is
enabled with set_compare().
get
virtual function uvm_reg_data_t get(
string fname = "",
int lineno = 0
)
Returns the next value from the abstract FIFO, but does not pop it. Used to get the
expected value in a mirror() operation.
do_predict
UVM 1.2 Class Reference
639
virtual function void do_predict(
uvm_reg_item rw, uvm_predict_e kind = UVM_PREDICT_DIRECT,
uvm_reg_byte_en_t be = -1
)
Updates the abstract (mirror) FIFO based on write() and read() operations. When autoprediction is on, this method is called before each read, write, peek, or poke operation
returns. When auto-prediction is off, this method is called by a uvm_reg_predictor upon
receipt and conversion of an observed bus operation to this register.
If a write prediction, the observed write value is pushed to the abstract FIFO as long as
it is not full and the operation did not originate from an update(). If a read prediction,
the observed read value is compared with the frontmost value in the abstract FIFO if
set_compare() enabled comparison and the FIFO is not empty.
SPEcIAL OVERRIdEs
pre_write
virtual task pre_write(
uvm_reg_item rw
)
Special pre-processing for a write() or update(). Called as a result of a write() or
update(). It is an error to attempt a write to a full FIFO or a write while an update is
still pending. An update is pending after one or more calls to set(). If in your
application the DUT allows writes to a full FIFO, you must override pre_write as
appropriate.
pre_read
virtual task pre_read(
uvm_reg_item rw
)
Special post-processing for a write() or update(). Aborts the operation if the internal
FIFO is empty. If in your application the DUT does not behave this way, you must
override pre_write as appropriate.
UVM 1.2 Class Reference
640
25.9 Virtual Registers
A virtual register is a collection of fields, overlaid on top of a memory, usually in an
array. The semantics and layout of virtual registers comes from an agreement between
the software and the hardware, not any physical structures in the DUT.
Contents
Virtual
Registers
A virtual register is a collection of fields, overlaid on top of a
memory, usually in an array.
uvm_vreg
uvm_vreg_cbs
Virtual register abstraction base class
Pre/post read/write callback facade class
uvm_vreg
Virtual register abstraction base class
A virtual register represents a set of fields that are logically implemented in consecutive
memory locations.
All virtual register accesses eventually turn into memory accesses.
A virtual register array may be implemented on top of any memory abstraction class and
possibly dynamically resized and/or relocated.
Summary
uvm_vreg
Virtual register abstraction base class
CLAss HIErArchY
uvm_void
uvm_object
uvm_vreg
CLAss DEcLArATION
class uvm_vreg extends uvm_object
INITIALIZATION
new
configure
implement
allocate
get_region
release_region
Create a new instance and type-specific
configuration
Instance-specific configuration
Dynamically implement, resize or relocate a virtual
register array
Randomly implement, resize or relocate a virtual
register array
Get the region where the virtual register array is
implemented
Dynamically un-implement a virtual register array
INTrOsPEcTION
UVM 1.2 Class Reference
641
get_name
get_full_name
get_parent
get_memory
get_n_maps
is_in_map
get_maps
get_rights
get_access
get_size
get_n_bytes
get_n_memlocs
get_incr
get_fields
get_field_by_name
get_offset_in_memory
get_address
Get the simple name
Get the hierarchical name
Get the parent block
Get the memory where the virtual register array is
implemented
Returns the number of address maps this virtual
register array is mapped in
Return TRUE if this virtual register array is in the
specified address map
Returns all of the address maps where this virtual
register array is mapped
Returns the access rights of this virtual register
array
Returns the access policy of the virtual register
array when written and read via an address map.
Returns the size of the virtual register array.
Returns the width, in bytes, of a virtual register.
Returns the number of memory locations used by a
single virtual register.
Returns the number of memory locations between
two individual virtual registers in the same array.
Return the virtual fields in this virtual register
Return the named virtual field in this virtual register
Returns the offset of a virtual register
Returns the base external physical address of a
virtual register
HDL AccEss
write
read
poke
peek
reset
Write the specified value in a virtual register
Read the current value from a virtual register
Deposit the specified value in a virtual register
Sample the current value in a virtual register
Reset the access semaphore
CALLBAcKs
pre_write
post_write
pre_read
post_read
Called
Called
Called
Called
before virtual register write.
after virtual register write.
before virtual register read.
after virtual register read.
INITIALIZATION
new
function new(
string name,
int unsigned n_bits
)
Create a new instance and type-specific configuration
Creates an instance of a virtual register abstraction class with the specified name.
n_bits specifies the total number of bits in a virtual register. Not all bits need to be
mapped to a virtual field. This value is usually a multiple of 8.
configure
function void configure(
uvm_reg_block parent, UVM 1.2 Class Reference
642
uvm_mem mem
longint unsigned size
uvm_reg_addr_t offset
int unsigned incr
)
= null,
= 0,
= 0,
= 0
Instance-specific configuration
Specify the parent block of this virtual register array. If one of the other parameters are
specified, the virtual register is assumed to be dynamic and can be later (re)implemented using the uvm_vreg::implement() method.
If mem is specified, then the virtual register array is assumed to be statically
implemented in the memory corresponding to the specified memory abstraction class and
size, offset and incr must also be specified. Static virtual register arrays cannot be reimplemented.
implement
virtual function bit implement(
longint unsigned n,
uvm_mem mem
= null,
uvm_reg_addr_t offset = 0,
int unsigned incr = 0
)
Dynamically implement, resize or relocate a virtual register array
Implement an array of virtual registers of the specified size, in the specified memory and
offset. If an offset increment is specified, each virtual register is implemented at the
specified offset increment from the previous one. If an offset increment of 0 is specified,
virtual registers are packed as closely as possible in the memory.
If no memory is specified, the virtual register array is in the same memory, at the same
base offset using the same offset increment as originally implemented. Only the number
of virtual registers in the virtual register array is modified.
The initial value of the newly-implemented or relocated set of virtual registers is
whatever values are currently stored in the memory now implementing them.
Returns TRUE if the memory can implement the number of virtual registers at the
specified base offset and offset increment. Returns FALSE otherwise.
The memory region used to implement a virtual register array is reserved in the memory
allocation manager associated with the memory to prevent it from being allocated for
another purpose.
allocate
virtual function uvm_mem_region allocate(
longint unsigned n,
uvm_mem_mam mam, uvm_mem_mam_policy alloc = null
)
Randomly implement, resize or relocate a virtual register array
Implement a virtual register array of the specified size in a randomly allocated region of
the appropriate size in the address space managed by the specified memory allocation
manager. If a memory allocation policy is specified, it is passed to the
uvm_mem_mam::request_region() method.
UVM 1.2 Class Reference
643
The initial value of the newly-implemented or relocated set of virtual registers is
whatever values are currently stored in the memory region now implementing them.
Returns a reference to a uvm_mem_region memory region descriptor if the memory
allocation manager was able to allocate a region that can implement the virtual register
array with the specified allocation policy. Returns null otherwise.
A region implementing a virtual register array must not be released using the
uvm_mem_mam::release_region() method. It must be released using the
uvm_vreg::release_region() method.
get_region
virtual function uvm_mem_region get_region()
Get the region where the virtual register array is implemented
Returns a reference to the uvm_mem_region memory region descriptor that implements
the virtual register array.
Returns null if the virtual registers array is not currently implemented. A region
implementing a virtual register array must not be released using the
uvm_mem_mam::release_region() method. It must be released using the
uvm_vreg::release_region() method.
release_region
virtual function void release_region()
Dynamically un-implement a virtual register array
Release the memory region used to implement a virtual register array and return it to
the pool of available memory that can be allocated by the memory’s default allocation
manager. The virtual register array is subsequently considered as unimplemented and
can no longer be accessed.
Statically-implemented virtual registers cannot be released.
INTrOsPEcTION
get_name
Get the simple name
Return the simple object name of this register.
get_full_name
virtual function string get_full_name()
Get the hierarchical name
UVM 1.2 Class Reference
644
Return the hierarchal name of this register. The base of the hierarchical name is the
root block.
get_parent
virtual function uvm_reg_block get_parent()
Get the parent block
get_memory
virtual function uvm_mem get_memory()
Get the memory where the virtual register array is implemented
get_n_maps
virtual function int get_n_maps ()
Returns the number of address maps this virtual register array is mapped in
is_in_map
function bit is_in_map (
uvm_reg_map map
)
Return TRUE if this virtual register array is in the specified address map
get_maps
virtual function void get_maps (
ref uvm_reg_map maps[$]
)
Returns all of the address maps where this virtual register array is mapped
get_rights
virtual function string get_rights(
uvm_reg_map map = null
)
Returns the access rights of this virtual register array
Returns “RW”, “RO” or “WO”. The access rights of a virtual register array is always
“RW”, unless it is implemented in a shared memory with access restriction in a particular
address map.
If no address map is specified and the memory is mapped in only one address map, that
address map is used. If the memory is mapped in more than one address map, the
default address map of the parent block is used.
UVM 1.2 Class Reference
645
If an address map is specified and the memory is not mapped in the specified address
map, an error message is issued and “RW” is returned.
get_access
virtual function string get_access(
uvm_reg_map map = null
)
Returns the access policy of the virtual register array when written and read via an
address map.
If the memory implementing the virtual register array is mapped in more than one
address map, an address map must be specified. If access restrictions are present when
accessing a memory through the specified address map, the access mode returned takes
the access restrictions into account. For example, a read-write memory accessed
through an address map with read-only restrictions would return “RO”.
get_size
virtual function int unsigned get_size()
Returns the size of the virtual register array.
get_n_bytes
virtual function int unsigned get_n_bytes()
Returns the width, in bytes, of a virtual register.
The width of a virtual register is always a multiple of the width of the memory locations
used to implement it. For example, a virtual register containing two 1-byte fields
implemented in a memory with 4-bytes memory locations is 4-byte wide.
get_n_memlocs
virtual function int unsigned get_n_memlocs()
Returns the number of memory locations used by a single virtual register.
get_incr
virtual function int unsigned get_incr()
Returns the number of memory locations between two individual virtual registers in the
same array.
get_fields
virtual function void get_fields(
ref uvm_vreg_field fields[$]
UVM 1.2 Class Reference
646
)
Return the virtual fields in this virtual register
Fills the specified array with the abstraction class for all of the virtual fields contained in
this virtual register. Fields are ordered from least-significant position to most-significant
position within the register.
get_field_by_name
virtual function uvm_vreg_field get_field_by_name(
string name
)
Return the named virtual field in this virtual register
Finds a virtual field with the specified name in this virtual register and returns its
abstraction class. If no fields are found, returns null.
get_offset_in_memory
virtual function uvm_reg_addr_t get_offset_in_memory(
longint unsigned idx
)
Returns the offset of a virtual register
Returns the base offset of the specified virtual register, in the overall address space of
the memory that implements the virtual register array.
get_address
virtual function uvm_reg_addr_t get_address(
longint unsigned idx, uvm_reg_map map = null
)
Returns the base external physical address of a virtual register
Returns the base external physical address of the specified virtual register if accessed
through the specified address map.
If no address map is specified and the memory implementing the virtual register array is
mapped in only one address map, that address map is used. If the memory is mapped
in more than one address map, the default address map of the parent block is used.
If an address map is specified and the memory is not mapped in the specified address
map, an error message is issued.
HDL AccEss
write
virtual task write(
UVM 1.2 Class Reference
647
input longint unsigned idx,
output uvm_status_e status, input uvm_reg_data_t value,
input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Write the specified value in a virtual register
Write value in the DUT memory location(s) that implements the virtual register array
that corresponds to this abstraction class instance using the specified access path.
If the memory implementing the virtual register array is mapped in more than one
address map, an address map must be specified if a physical access is used (front-door
access).
The operation is eventually mapped into set of memory-write operations at the location
where the virtual register specified by idx in the virtual register array is implemented.
read
virtual task read(
input longint unsigned idx,
output uvm_status_e status, output uvm_reg_data_t value,
input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the current value from a virtual register
Read from the DUT memory location(s) that implements the virtual register array that
corresponds to this abstraction class instance using the specified access path and return
the readback value.
If the memory implementing the virtual register array is mapped in more than one
address map, an address map must be specified if a physical access is used (front-door
access).
The operation is eventually mapped into set of memory-read operations at the location
where the virtual register specified by idx in the virtual register array is implemented.
poke
virtual task poke(
input longint unsigned idx,
output uvm_status_e status, input uvm_reg_data_t value,
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Deposit the specified value in a virtual register
Deposit value in the DUT memory location(s) that implements the virtual register array
UVM 1.2 Class Reference
648
that corresponds to this abstraction class instance using the memory backdoor access.
The operation is eventually mapped into set of memory-poke operations at the location
where the virtual register specified by idx in the virtual register array is implemented.
peek
virtual task peek(
input longint unsigned idx,
output uvm_status_e status, output uvm_reg_data_t value,
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Sample the current value in a virtual register
Sample the DUT memory location(s) that implements the virtual register array that
corresponds to this abstraction class instance using the memory backdoor access, and
return the sampled value.
The operation is eventually mapped into set of memory-peek operations at the location
where the virtual register specified by idx in the virtual register array is implemented.
reset
function void reset(
string kind = "HARD"
)
Reset the access semaphore
Reset the semaphore that prevents concurrent access to the virtual register. This
semaphore must be explicitly reset if a thread accessing this virtual register array was
killed in before the access was completed
CALLBAcKs
pre_write
virtual task pre_write(
longint unsigned idx,
ref uvm_reg_data_t wdat,
ref uvm_path_e path,
ref uvm_reg_map map
)
Called before virtual register write.
If the specified data value, access path or address map are modified, the updated data
value, access path or address map will be used to perform the virtual register operation.
The registered callback methods are invoked after the invocation of this method. All
register callbacks are executed after the corresponding field callbacks The pre-write
virtual register and field callbacks are executed before the corresponding pre-write
memory callbacks
UVM 1.2 Class Reference
649
post_write
virtual task post_write(
longint unsigned idx,
uvm_reg_data_t wdat,
uvm_path_e path,
uvm_reg_map map,
ref uvm_status_e status
)
Called after virtual register write.
If the specified status is modified, the updated status will be returned by the virtual
register operation.
The registered callback methods are invoked before the invocation of this method. All
register callbacks are executed before the corresponding field callbacks The post-write
virtual register and field callbacks are executed after the corresponding post-write
memory callbacks
pre_read
virtual task pre_read(
longint unsigned idx,
ref uvm_path_e path,
ref uvm_reg_map map
)
Called before virtual register read.
If the specified access path or address map are modified, the updated access path or
address map will be used to perform the register operation.
The registered callback methods are invoked after the invocation of this method. All
register callbacks are executed after the corresponding field callbacks The pre-read
virtual register and field callbacks are executed before the corresponding pre-read
memory callbacks
post_read
virtual task post_read(
longint unsigned idx,
ref uvm_reg_data_t rdat,
input uvm_path_e path,
input uvm_reg_map map,
ref uvm_status_e status
)
Called after virtual register read.
If the specified readback data or status is modified, the updated readback data or status
will be returned by the register operation.
The registered callback methods are invoked before the invocation of this method. All
register callbacks are executed before the corresponding field callbacks The post-read
virtual register and field callbacks are executed after the corresponding post-read
memory callbacks
UVM 1.2 Class Reference
650
uvm_vreg_cbs
Pre/post read/write callback facade class
Summary
uvm_vreg_cbs
Pre/post read/write callback facade class
CLAss HIErArchY
uvm_void
uvm_object
uvm_callback
uvm_vreg_cbs
CLAss DEcLArATION
class uvm_vreg_cbs extends uvm_callback
METhOds
pre_write
post_write
pre_read
post_read
Callback called before a write operation.
Called after register write.
Called before register read.
Called after register read.
TYPEs
uvm_vreg_cb
uvm_vreg_cb_iter
Convenience callback type declaration
Convenience callback iterator type declaration
METhOds
pre_write
virtual task pre_write(
uvm_vreg rg,
longint unsigned idx,
ref uvm_reg_data_t wdat,
ref uvm_path_e path,
ref uvm_reg_map map
)
Callback called before a write operation.
The registered callback methods are invoked after the invocation of the
uvm_vreg::pre_write() method. All virtual register callbacks are executed after the
corresponding virtual field callbacks The pre-write virtual register and field callbacks are
executed before the corresponding pre-write memory callbacks
The written value wdat, access path and address map, if modified, modifies the actual
value, access path or address map used in the virtual register operation.
UVM 1.2 Class Reference
651
post_write
virtual task post_write(
uvm_vreg rg,
longint unsigned idx,
uvm_reg_data_t wdat,
uvm_path_e path,
uvm_reg_map map,
ref uvm_status_e status
)
Called after register write.
The registered callback methods are invoked before the invocation of the
uvm_reg::post_write() method. All register callbacks are executed before the
corresponding virtual field callbacks The post-write virtual register and field callbacks are
executed after the corresponding post-write memory callbacks
The status of the operation, if modified, modifies the actual returned status.
pre_read
virtual task pre_read(
uvm_vreg rg,
longint unsigned idx,
ref uvm_path_e path,
ref uvm_reg_map map
)
Called before register read.
The registered callback methods are invoked after the invocation of the
uvm_reg::pre_read() method. All register callbacks are executed after the corresponding
virtual field callbacks The pre-read virtual register and field callbacks are executed before
the corresponding pre-read memory callbacks
The access path and address map, if modified, modifies the actual access path or address
map used in the register operation.
post_read
virtual task post_read(
uvm_vreg rg,
longint unsigned idx,
ref uvm_reg_data_t rdat,
input uvm_path_e path,
input uvm_reg_map map,
ref uvm_status_e status
)
Called after register read.
The registered callback methods are invoked before the invocation of the
uvm_reg::post_read() method. All register callbacks are executed before the
corresponding virtual field callbacks The post-read virtual register and field callbacks are
executed after the corresponding post-read memory callbacks
The readback value rdat and the status of the operation, if modified, modifies the actual
returned readback value and status.
UVM 1.2 Class Reference
652
TYPEs
uvm_vreg_cb
Convenience callback type declaration
Use this declaration to register virtual register callbacks rather than the more verbose
parameterized class
uvm_vreg_cb_iter
Convenience callback iterator type declaration
Use this declaration to iterate over registered virtual register callbacks rather than the
more verbose parameterized class
UVM 1.2 Class Reference
653
25.10 Virtual Register Field Classes
This section defines the virtual field and callback classes.
A virtual field is set of contiguous bits in one or more memory locations. The semantics
and layout of virtual fields comes from an agreement between the software and the
hardware, not any physical structures in the DUT.
Contents
Virtual Register Field
Classes
This section defines the virtual field and callback
classes.
uvm_vreg_field
uvm_vreg_field_cbs
Virtual field abstraction class
Pre/post read/write callback facade class
uvm_vreg_field
Virtual field abstraction class
A virtual field represents a set of adjacent bits that are logically implemented in
consecutive memory locations.
Summary
uvm_vreg_field
Virtual field abstraction class
CLAss HIErArchY
uvm_void
uvm_object
uvm_vreg_field
CLAss DEcLArATION
class uvm_vreg_field extends uvm_object
INITIALIZATION
new
configure
INTrOsPEcTION
get_name
get_full_name
get_parent
get_lsb_pos_in_register
get_n_bits
get_access
Create a new virtual field instance
Instance-specific configuration
Get the simple name
Get the hierarchical name
Get the parent virtual register
Return the position of the virtual field / Returns
the index of the least significant bit of the virtual
field in the virtual register that instantiates it.
Returns the width, in bits, of the virtual field.
Returns the access policy of the virtual field
register when written and read via an address
map.
HDL AccEss
UVM 1.2 Class Reference
654
write
read
poke
peek
CALLBAcKs
pre_write
post_write
pre_read
post_read
Write the specified value in a virtual field
Read the current value from a virtual field
Deposit the specified value in a virtual field
Sample the current value from a virtual field
Called
Called
Called
Called
before virtual field write.
after virtual field write
before virtual field read.
after virtual field read.
INITIALIZATION
new
function new(
string name = "uvm_vreg_field"
)
Create a new virtual field instance
This method should not be used directly. The uvm_vreg_field::type_id::create() method
should be used instead.
configure
function void configure(
uvm_vreg parent,
int unsigned size,
int unsigned lsb_pos
)
Instance-specific configuration
Specify the parent virtual register of this virtual field, its size in bits, and the position of
its least-significant bit within the virtual register relative to the least-significant bit of the
virtual register.
INTrOsPEcTION
get_name
Get the simple name
Return the simple object name of this virtual field
get_full_name
virtual function string get_full_name()
Get the hierarchical name
UVM 1.2 Class Reference
655
Return the hierarchal name of this virtual field The base of the hierarchical name is the
root block.
get_parent
virtual function uvm_vreg get_parent()
Get the parent virtual register
get_lsb_pos_in_register
virtual function int unsigned get_lsb_pos_in_register()
Return the position of the virtual field / Returns the index of the least significant bit of
the virtual field in the virtual register that instantiates it. An offset of 0 indicates a field
that is aligned with the least-significant bit of the register.
get_n_bits
virtual function int unsigned get_n_bits()
Returns the width, in bits, of the virtual field.
get_access
virtual function string get_access(
uvm_reg_map map = null
)
Returns the access policy of the virtual field register when written and read via an
address map.
If the memory implementing the virtual field is mapped in more than one address map,
an address map must be specified. If access restrictions are present when accessing a
memory through the specified address map, the access mode returned takes the access
restrictions into account. For example, a read-write memory accessed through an
address map with read-only restrictions would return “RO”.
HDL AccEss
write
virtual task write(
input longint unsigned idx,
output uvm_status_e status, input uvm_reg_data_t value,
input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
UVM 1.2 Class Reference
656
Write the specified value in a virtual field
Write value in the DUT memory location(s) that implements the virtual field that
corresponds to this abstraction class instance using the specified access path.
If the memory implementing the virtual register array containing this virtual field is
mapped in more than one address map, an address map must be specified if a physical
access is used (front-door access).
The operation is eventually mapped into memory read-modify-write operations at the
location where the virtual register specified by idx in the virtual register array is
implemented. If a backdoor is available for the memory implementing the virtual field, it
will be used for the memory-read operation.
read
virtual task read(
input longint unsigned idx,
output uvm_status_e status, output uvm_reg_data_t value,
input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read the current value from a virtual field
Read from the DUT memory location(s) that implements the virtual field that corresponds
to this abstraction class instance using the specified access path, and return the
readback value.
If the memory implementing the virtual register array containing this virtual field is
mapped in more than one address map, an address map must be specified if a physical
access is used (front-door access).
The operation is eventually mapped into memory read operations at the location(s) where
the virtual register specified by idx in the virtual register array is implemented.
poke
virtual task poke(
input longint unsigned idx,
output uvm_status_e status, input uvm_reg_data_t value,
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Deposit the specified value in a virtual field
Deposit value in the DUT memory location(s) that implements the virtual field that
corresponds to this abstraction class instance using the specified access path.
The operation is eventually mapped into memory peek-modify-poke operations at the
location where the virtual register specified by idx in the virtual register array is
implemented.
UVM 1.2 Class Reference
657
peek
virtual task peek(
input longint unsigned idx,
output uvm_status_e status, output uvm_reg_data_t value,
input uvm_sequence_base parent
= null,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Sample the current value from a virtual field
Sample from the DUT memory location(s) that implements the virtual field that
corresponds to this abstraction class instance using the specified access path, and return
the readback value.
If the memory implementing the virtual register array containing this virtual field is
mapped in more than one address map, an address map must be specified if a physical
access is used (front-door access).
The operation is eventually mapped into memory peek operations at the location(s)
where the virtual register specified by idx in the virtual register array is implemented.
CALLBAcKs
pre_write
virtual task pre_write(
longint unsigned idx,
ref uvm_reg_data_t wdat,
ref uvm_path_e path,
ref uvm_reg_map map
)
Called before virtual field write.
If the specified data value, access path or address map are modified, the updated data
value, access path or address map will be used to perform the virtual register operation.
The virtual field callback methods are invoked before the callback methods on the
containing virtual register. The registered callback methods are invoked after the
invocation of this method. The pre-write virtual register and field callbacks are executed
before the corresponding pre-write memory callbacks
post_write
virtual task post_write(
longint unsigned idx,
uvm_reg_data_t wdat,
uvm_path_e path,
uvm_reg_map map,
ref uvm_status_e status
)
Called after virtual field write
If the specified status is modified, the updated status will be returned by the virtual
UVM 1.2 Class Reference
658
register operation.
The virtual field callback methods are invoked after the callback methods on the
containing virtual register. The registered callback methods are invoked before the
invocation of this method. The post-write virtual register and field callbacks are executed
after the corresponding post-write memory callbacks
pre_read
virtual task pre_read(
longint unsigned idx,
ref uvm_path_e path,
ref uvm_reg_map map
)
Called before virtual field read.
If the specified access path or address map are modified, the updated access path or
address map will be used to perform the virtual register operation.
The virtual field callback methods are invoked after the callback methods on the
containing virtual register. The registered callback methods are invoked after the
invocation of this method. The pre-read virtual register and field callbacks are executed
before the corresponding pre-read memory callbacks
post_read
virtual task post_read(
longint unsigned idx,
ref uvm_reg_data_t rdat,
uvm_path_e path,
uvm_reg_map map,
ref uvm_status_e status
)
Called after virtual field read.
If the specified readback data rdat or status is modified, the updated readback data or
status will be returned by the virtual register operation.
The virtual field callback methods are invoked after the callback methods on the
containing virtual register. The registered callback methods are invoked before the
invocation of this method. The post-read virtual register and field callbacks are executed
after the corresponding post-read memory callbacks
uvm_vreg_field_cbs
Pre/post read/write callback facade class
Summary
uvm_vreg_field_cbs
Pre/post read/write callback facade class
CLAss HIErArchY
UVM 1.2 Class Reference
659
uvm_void
uvm_object
uvm_callback
uvm_vreg_field_cbs
CLAss DEcLArATION
class uvm_vreg_field_cbs extends uvm_callback
METhOds
pre_write
post_write
pre_read
post_read
Callback called before a write operation.
Called after a write operation
Called before a virtual field read.
Called after a virtual field read.
TYPEs
uvm_vreg_field_cb
uvm_vreg_field_cb_iter
Convenience callback type declaration
Convenience callback iterator type declaration
METhOds
pre_write
virtual task pre_write(
uvm_vreg_field field,
longint unsigned idx,
ref uvm_reg_data_t wdat,
ref uvm_path_e path,
ref uvm_reg_map map
)
Callback called before a write operation.
The registered callback methods are invoked before the invocation of the virtual register
pre-write callbacks and after the invocation of the uvm_vreg_field::pre_write() method.
The written value wdat, access path and address map, if modified, modifies the actual
value, access path or address map used in the register operation.
post_write
virtual task post_write(
uvm_vreg_field field,
longint unsigned idx,
uvm_reg_data_t wdat,
uvm_path_e path,
uvm_reg_map map,
ref uvm_status_e status
)
Called after a write operation
The registered callback methods are invoked after the invocation of the virtual register
post-write callbacks and before the invocation of the uvm_vreg_field::post_write()
method.
The status of the operation, if modified, modifies the actual returned status.
UVM 1.2 Class Reference
660
pre_read
virtual task pre_read(
uvm_vreg_field field,
longint unsigned idx,
ref uvm_path_e path,
ref uvm_reg_map map
)
Called before a virtual field read.
The registered callback methods are invoked after the invocation of the virtual register
pre-read callbacks and after the invocation of the uvm_vreg_field::pre_read() method.
The access path and address map, if modified, modifies the actual access path or address
map used in the register operation.
post_read
virtual task post_read(
uvm_vreg_field field,
longint unsigned idx,
ref uvm_reg_data_t rdat,
uvm_path_e path,
uvm_reg_map map,
ref uvm_status_e status
)
Called after a virtual field read.
The registered callback methods are invoked after the invocation of the virtual register
post-read callbacks and before the invocation of the uvm_vreg_field::post_read()
method.
The readback value rdat and the status of the operation, if modified, modifies the actual
returned readback value and status.
TYPEs
uvm_vreg_field_cb
Convenience callback type declaration
Use this declaration to register virtual field callbacks rather than the more verbose
parameterized class
uvm_vreg_field_cb_iter
Convenience callback iterator type declaration
Use this declaration to iterate over registered virtual field callbacks rather than the more
verbose parameterized class
UVM 1.2 Class Reference
661
25.11 Register Callbacks
This section defines the base class used for all register callback extensions. It also
includes pre-defined callback extensions for use on read-only and write-only registers.
Contents
Register Callbacks
This section defines the base class used for all
register callback extensions.
uvm_reg_cbs
Facade class for field, register, memory and backdoor
access callback methods.
Typedefs
uvm_reg_cb
uvm_reg_cb_iter
uvm_reg_bd_cb
uvm_reg_bd_cb_iter
uvm_mem_cb
uvm_mem_cb_iter
uvm_reg_field_cb
uvm_reg_field_cb_iter
PrEDEFINED EXtENSIONS
uvm_reg_read_only_cbs
uvm_reg_write_only_cbs
Convenience
Convenience
registers
Convenience
Convenience
backdoor
Convenience
Convenience
memories
Convenience
Convenience
fields
callback type declaration for registers
callback iterator type declaration for
callback type declaration for backdoor
callback iterator type declaration for
callback type declaration for memories
callback iterator type declaration for
callback type declaration for fields
callback iterator type declaration for
Pre-defined register callback method for read-only
registers that will issue an error if a write()
operation is attempted.
Pre-defined register callback method for write-only
registers that will issue an error if a read() operation
is attempted.
uvm_reg_cbs
Facade class for field, register, memory and backdoor access callback methods.
Summary
uvm_reg_cbs
Facade class for field, register, memory and backdoor access callback methods.
CLASS HIErArchY
uvm_void
uvm_object
uvm_callback
uvm_reg_cbs
CLASS DEcLArAtION
virtual class uvm_reg_cbs extends uvm_callback
UVM 1.2 Class Reference
662
MEthODS
pre_write
post_write
pre_read
post_read
post_predict
encode
decode
Called before a write operation.
Called after a write operation.
Callback called before a read operation.
Callback called after a read operation.
Called by the uvm_reg_field::predict() method after a
successful UVM_PREDICT_READ or UVM_PREDICT_WRITE
prediction.
Data encoder
Data decode
MEthODS
pre_write
virtual task pre_write(
uvm_reg_item rw
)
Called before a write operation.
All registered pre_write callback methods are invoked after the invocation of the
pre_write method of associated object (uvm_reg, uvm_reg_field, uvm_mem, or
uvm_reg_backdoor). If the element being written is a uvm_reg, all pre_write callback
methods are invoked before the contained uvm_reg_fields.
Backdoor
uvm_reg_backdoor::pre_write, uvm_reg_cbs::pre_write cbs for
backdoor.
Register
uvm_reg::pre_write, uvm_reg_cbs::pre_write cbs for reg, then
foreach field: uvm_reg_field::pre_write, uvm_reg_cbs::pre_write
cbs for field
RegField
uvm_reg_field::pre_write, uvm_reg_cbs::pre_write cbs for field
Memory
uvm_mem::pre_write, uvm_reg_cbs::pre_write cbs for mem
The rw argument holds information about the operation.
Modifying the value modifies the actual value written.
For memories, modifying the offset modifies the offset used in the operation.
For non-backdoor operations, modifying the access path or address map modifies
the actual path or map used in the operation.
If the rw.status is modified to anything other than UVM_IS_OK, the operation is aborted.
See uvm_reg_item for details on rw information.
post_write
virtual task post_write(
uvm_reg_item rw
)
Called after a write operation.
All registered post_write callback methods are invoked before the invocation of the
post_write method of the associated object (uvm_reg, uvm_reg_field, uvm_mem, or
UVM 1.2 Class Reference
663
uvm_reg_backdoor). If the element being written is a uvm_reg, all post_write callback
methods are invoked before the contained uvm_reg_fields.
Summary of callback order
Backdoor
uvm_reg_cbs::post_write cbs for backdoor,
uvm_reg_backdoor::post_write
Register
uvm_reg_cbs::post_write cbs for reg, uvm_reg::post_write, then
foreach field: uvm_reg_cbs::post_write cbs for field,
uvm_reg_field::post_read
RegField
uvm_reg_cbs::post_write cbs for field, uvm_reg_field::post_write
Memory
uvm_reg_cbs::post_write cbs for mem, uvm_mem::post_write
The rw argument holds information about the operation.
Modifying the status member modifies the returned status.
Modifying the value or offset members has no effect, as the operation has already
completed.
See uvm_reg_item for details on rw information.
pre_read
virtual task pre_read(
uvm_reg_item rw
)
Callback called before a read operation.
All registered pre_read callback methods are invoked after the invocation of the pre_read
method of associated object (uvm_reg, uvm_reg_field, uvm_mem, or
uvm_reg_backdoor). If the element being read is a uvm_reg, all pre_read callback
methods are invoked before the contained uvm_reg_fields.
Backdoor
uvm_reg_backdoor::pre_read, uvm_reg_cbs::pre_read cbs for
backdoor
Register
uvm_reg::pre_read, uvm_reg_cbs::pre_read cbs for reg, then
foreach field: uvm_reg_field::pre_read, uvm_reg_cbs::pre_read cbs
for field
RegField
uvm_reg_field::pre_read, uvm_reg_cbs::pre_read cbs for field
Memory
uvm_mem::pre_read, uvm_reg_cbs::pre_read cbs for mem
The rw argument holds information about the operation.
The value member of rw is not used has no effect if modified.
For memories, modifying the offset modifies the offset used in the operation.
For non-backdoor operations, modifying the access path or address map modifies
the actual path or map used in the operation.
If the rw.status is modified to anything other than UVM_IS_OK, the operation is aborted.
See uvm_reg_item for details on rw information.
post_read
virtual task post_read(
UVM 1.2 Class Reference
664
uvm_reg_item rw
)
Callback called after a read operation.
All registered post_read callback methods are invoked before the invocation of the
post_read method of the associated object (uvm_reg, uvm_reg_field, uvm_mem, or
uvm_reg_backdoor). If the element being read is a uvm_reg, all post_read callback
methods are invoked before the contained uvm_reg_fields.
Backdoor
uvm_reg_cbs::post_read cbs for backdoor,
uvm_reg_backdoor::post_read
Register
uvm_reg_cbs::post_read cbs for reg, uvm_reg::post_read, then
foreach field: uvm_reg_cbs::post_read cbs for field,
uvm_reg_field::post_read
RegField
uvm_reg_cbs::post_read cbs for field, uvm_reg_field::post_read
Memory
uvm_reg_cbs::post_read cbs for mem, uvm_mem::post_read
The rw argument holds information about the operation.
Modifying the readback value or status modifies the actual returned value and
status.
Modifying the value or offset members has no effect, as the operation has already
completed.
See uvm_reg_item for details on rw information.
post_predict
virtual function void post_predict(
input uvm_reg_field fld,
input uvm_reg_data_t previous,
inout uvm_reg_data_t value,
input uvm_predict_e kind,
input uvm_path_e path,
input uvm_reg_map map
)
Called by the uvm_reg_field::predict() method after a successful UVM_PREDICT_READ or
UVM_PREDICT_WRITE prediction.
previous is the previous value in the mirror and value is the latest predicted value. Any
change to value will modify the predicted mirror value.
encode
virtual function void encode(
ref uvm_reg_data_t data[]
)
Data encoder
The registered callback methods are invoked in order of registration after all the
pre_write methods have been called. The encoded data is passed through each
invocation in sequence. This allows the pre_write methods to deal with clear-text data.
By default, the data is not modified.
UVM 1.2 Class Reference
665
decode
virtual function void decode(
ref uvm_reg_data_t data[]
)
Data decode
The registered callback methods are invoked in reverse order of registration before all the
post_read methods are called. The decoded data is passed through each invocation in
sequence. This allows the post_read methods to deal with clear-text data.
The reversal of the invocation order is to allow the decoding of the data to be performed
in the opposite order of the encoding with both operations specified in the same callback
extension.
By default, the data is not modified.
Typedefs
Summary
Typedefs
uvm_reg_cb
uvm_reg_cb_iter
uvm_reg_bd_cb
uvm_reg_bd_cb_iter
uvm_mem_cb
uvm_mem_cb_iter
uvm_reg_field_cb
uvm_reg_field_cb_iter
Convenience
Convenience
registers
Convenience
Convenience
backdoor
Convenience
Convenience
memories
Convenience
Convenience
fields
callback type declaration for registers
callback iterator type declaration for
callback type declaration for backdoor
callback iterator type declaration for
callback type declaration for memories
callback iterator type declaration for
callback type declaration for fields
callback iterator type declaration for
PrEDEFINED EXtENSIONS
uvm_reg_cb
Convenience callback type declaration for registers
Use this declaration to register the register callbacks rather than the more verbose
parameterized class
uvm_reg_cb_iter
Convenience callback iterator type declaration for registers
Use this declaration to iterate over registered register callbacks rather than the more
verbose parameterized class
uvm_reg_bd_cb
UVM 1.2 Class Reference
666
Convenience callback type declaration for backdoor
Use this declaration to register register backdoor callbacks rather than the more verbose
parameterized class
uvm_reg_bd_cb_iter
Convenience callback iterator type declaration for backdoor
Use this declaration to iterate over registered register backdoor callbacks rather than the
more verbose parameterized class
uvm_mem_cb
Convenience callback type declaration for memories
Use this declaration to register memory callbacks rather than the more verbose
parameterized class
uvm_mem_cb_iter
Convenience callback iterator type declaration for memories
Use this declaration to iterate over registered memory callbacks rather than the more
verbose parameterized class
uvm_reg_field_cb
Convenience callback type declaration for fields
Use this declaration to register field callbacks rather than the more verbose
parameterized class
uvm_reg_field_cb_iter
Convenience callback iterator type declaration for fields
Use this declaration to iterate over registered field callbacks rather than the more
verbose parameterized class
PrEDEFINED EXtENSIONS
uvm_reg_read_only_cbs
Pre-defined register callback method for read-only registers that will issue an error if a
write() operation is attempted.
UVM 1.2 Class Reference
667
Summary
uvm_reg_read_only_cbs
Pre-defined register callback method for read-only registers that will issue an
error if a write() operation is attempted.
CLASS HIErArchY
uvm_void
uvm_object
uvm_callback
uvm_reg_cbs
uvm_reg_read_only_cbs
CLASS DEcLArAtION
class uvm_reg_read_only_cbs extends uvm_reg_cbs
MEthODS
pre_write
add
remove
Produces an error message and sets status to UVM_NOT_OK.
Add this callback to the specified register and its contained
fields.
Remove this callback from the specified register and its
contained fields.
MEthODS
pre_write
virtual task pre_write(
uvm_reg_item rw
)
Produces an error message and sets status to UVM_NOT_OK.
add
static function void add(
uvm_reg rg
)
Add this callback to the specified register and its contained fields.
remove
static function void remove(
uvm_reg rg
)
Remove this callback from the specified register and its contained fields.
UVM 1.2 Class Reference
668
uvm_reg_write_only_cbs
Pre-defined register callback method for write-only registers that will issue an error if a
read() operation is attempted.
Summary
uvm_reg_write_only_cbs
Pre-defined register callback method for write-only registers that will issue an
error if a read() operation is attempted.
CLASS HIErArchY
uvm_void
uvm_object
uvm_callback
uvm_reg_cbs
uvm_reg_write_only_cbs
CLASS DEcLArAtION
class uvm_reg_write_only_cbs extends uvm_reg_cbs
MEthODS
pre_read
add
remove
Produces an error message and sets status to UVM_NOT_OK.
Add this callback to the specified register and its contained
fields.
Remove this callback from the specified register and its
contained fields.
MEthODS
pre_read
virtual task pre_read(
uvm_reg_item rw
)
Produces an error message and sets status to UVM_NOT_OK.
add
static function void add(
uvm_reg rg
)
Add this callback to the specified register and its contained fields.
UVM 1.2 Class Reference
669
remove
static function void remove(
uvm_reg rg
)
Remove this callback from the specified register and its contained fields.
UVM 1.2 Class Reference
670
25.12 Memory Allocation Manager
Manages the exclusive allocation of consecutive memory locations called regions. The
regions can subsequently be accessed like little memories of their own, without knowing
in which memory or offset they are actually located.
The memory allocation manager should be used by any application-level process that
requires reserved space in the memory, such as DMA buffers.
A region will remain reserved until it is explicitly released.
Contents
Memory Allocation
Manager
Manages the exclusive allocation of consecutive memory
locations called regions.
uvm_mem_mam
Memory allocation manager
uvm_mem_region
Allocated memory region descriptor
uvm_mem_mam_policy An instance of this class is randomized to determine the
starting offset of a randomly allocated memory region.
uvm_mem_mam_cfg
Specifies the memory managed by an instance of a
uvm_mem_mam memory allocation manager class.
uvm_mem_mam
Memory allocation manager
Memory allocation management utility class similar to C’s malloc() and free(). A single
instance of this class is used to manage a single, contiguous address space.
Summary
uvm_mem_mam
Memory allocation manager
CLass DEcLaRaTION
class uvm_mem_mam
INITIaLIZaTION
alloc_mode_e
locality_e
default_alloc
new
reconfigure
Memory allocation mode
Location of memory regions
Region allocation policy
Create a new manager instance
Reconfigure the manager
MEmORY MaNaGEmENT
reserve_region
request_region
release_region
release_all_regions
Reserve a specific memory region
Request and reserve a memory region
Release the specified region
Forcibly release all allocated memory regions.
INTROsPEcTION
convert2string
for_each
get_memory
Image of the state of the manager
Iterate over all currently allocated regions
Get the managed memory implementation
UVM 1.2 Class Reference
671
INITIaLIZaTION
alloc_mode_e
Memory allocation mode
Specifies how to allocate a memory region
GREEDY
Consume new, previously unallocated memory
THRIFTY
Reused previously released memory as much as possible (not yet
implemented)
locality_e
Location of memory regions
Specifies where to locate new memory regions
BROAD
Locate new regions randomly throughout the address space
NEARBY
Locate new regions adjacent to existing regions
default_alloc
uvm_mem_mam_policy default_alloc
Region allocation policy
This object is repeatedly randomized when allocating new regions.
new
function new(
string name, uvm_mem_mam_cfg cfg, uvm_mem mem = null
)
Create a new manager instance
Create an instance of a memory allocation manager with the specified name and
configuration. This instance manages all memory region allocation within the address
range specified in the configuration descriptor.
If a reference to a memory abstraction class is provided, the memory locations within
the regions can be accessed through the region descriptor, using the
uvm_mem_region::read() and uvm_mem_region::write() methods.
reconfigure
function uvm_mem_mam_cfg reconfigure(
UVM 1.2 Class Reference
672
uvm_mem_mam_cfg cfg = null
)
Reconfigure the manager
Modify the maximum and minimum addresses of the address space managed by the
allocation manager, allocation mode, or locality. The number of bytes per memory
location cannot be modified once an allocation manager has been constructed. All
currently allocated regions must fall within the new address space.
Returns the previous configuration.
if no new configuration is specified, simply returns the current configuration.
MEmORY MaNaGEmENT
reserve_region
function uvm_mem_region reserve_region(
bit [63:0] start_offset, int unsigned n_bytes,
string fname
= "",
int lineno
= 0
)
Reserve a specific memory region
Reserve a memory region of the specified number of bytes starting at the specified
offset. A descriptor of the reserved region is returned. If the specified region cannot be
reserved, null is returned.
It may not be possible to reserve a region because it overlaps with an already-allocated
region or it lies outside the address range managed by the memory manager.
Regions can be reserved to create “holes” in the managed address space.
request_region
function uvm_mem_region request_region(
int unsigned n_bytes, uvm_mem_mam_policy alloc
= null,
string fname
= "",
int lineno = 0
)
Request and reserve a memory region
Request and reserve a memory region of the specified number of bytes starting at a
random location. If an policy is specified, it is randomized to determine the start offset
of the region. If no policy is specified, the policy found in the
uvm_mem_mam::default_alloc class property is randomized.
A descriptor of the allocated region is returned. If no region can be allocated, null is
returned.
It may not be possible to allocate a region because there is no area in the memory with
enough consecutive locations to meet the size requirements or because there is another
contradiction when randomizing the policy.
UVM 1.2 Class Reference
673
If the memory allocation is configured to THRIFTY or NEARBY, a suitable region is first
sought procedurally.
release_region
function void release_region(
uvm_mem_region region
)
Release the specified region
Release a previously allocated memory region. An error is issued if the specified region
has not been previously allocated or is no longer allocated.
release_all_regions
function void release_all_regions()
Forcibly release all allocated memory regions.
INTROsPEcTION
convert2string
function string convert2string()
Image of the state of the manager
Create a human-readable description of the state of the memory manager and the
currently allocated regions.
for_each
function uvm_mem_region for_each(
bit reset = 0
)
Iterate over all currently allocated regions
If reset is TRUE, reset the iterator and return the first allocated region. Returns null
when there are no additional allocated regions to iterate on.
get_memory
function uvm_mem get_memory()
Get the managed memory implementation
Return the reference to the memory abstraction class for the memory implementing the
locations managed by this instance of the allocation manager. Returns null if no memory
abstraction class was specified at construction time.
UVM 1.2 Class Reference
674
uvm_mem_region
Allocated memory region descriptor
Each instance of this class describes an allocated memory region. Instances of this class
are created only by the memory manager, and returned by the
uvm_mem_mam::reserve_region() and uvm_mem_mam::request_region() methods.
Summary
uvm_mem_region
Allocated memory region descriptor
CLass DEcLaRaTION
class uvm_mem_region
METHOds
get_start_offset
get_end_offset
get_len
get_n_bytes
release_region
get_memory
get_virtual_registers
write
read
burst_write
burst_read
poke
peek
Get the start offset of the region
Get the end offset of the region
Size of the memory region
Number of bytes in the region
Release this region
Get the memory where the region resides
Get the virtual register array in this region
Write to a memory location in the region.
Read from a memory location in the region.
Write to a set of memory location in the region.
Read from a set of memory location in the region.
Deposit in a memory location in the region.
Sample a memory location in the region.
METHOds
get_start_offset
function bit [63:0] get_start_offset()
Get the start offset of the region
Return the address offset, within the memory, where this memory region starts.
get_end_offset
function bit [63:0] get_end_offset()
Get the end offset of the region
Return the address offset, within the memory, where this memory region ends.
UVM 1.2 Class Reference
675
get_len
function int unsigned get_len()
Size of the memory region
Return the number of consecutive memory locations (not necessarily bytes) in the
allocated region.
get_n_bytes
function int unsigned get_n_bytes()
Number of bytes in the region
Return the number of consecutive bytes in the allocated region. If the managed memory
contains more than one byte per address, the number of bytes in an allocated region
may be greater than the number of requested or reserved bytes.
release_region
function void release_region()
Release this region
get_memory
function uvm_mem get_memory()
Get the memory where the region resides
Return a reference to the memory abstraction class for the memory implementing this
allocated memory region. Returns null if no memory abstraction class was specified for
the allocation manager that allocated this region.
get_virtual_registers
function uvm_vreg get_virtual_registers()
Get the virtual register array in this region
Return a reference to the virtual register array abstraction class implemented in this
region. Returns null if the memory region is not known to implement virtual registers.
write
task write(
output uvm_status_e status, offset, input uvm_reg_addr_t value,
input uvm_reg_data_t input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm object extension = null,
UVM 1.2 Class Reference
676
input string input int )
fname
lineno
= "",
= 0
Write to a memory location in the region.
Write to the memory location that corresponds to the specified offset within this region. Requires that the memory abstraction class be associated with the memory allocation
manager that allocated this region.
See uvm_mem::write() for more details.
read
task read(
output uvm_status_e status, input uvm_reg_addr_t offset, output uvm_reg_data_t value,
path
= UVM_DEFAULT_PATH,
input uvm_path_e input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read from a memory location in the region.
Read from the memory location that corresponds to the specified offset within this
region. Requires that the memory abstraction class be associated with the memory
allocation manager that allocated this region.
See uvm_mem::read() for more details.
burst_write
task burst_write(
output uvm_status_e status, offset, input uvm_reg_addr_t input uvm_reg_data_t value[], path
= UVM_DEFAULT_PATH,
input uvm_path_e input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Write to a set of memory location in the region.
Write to the memory locations that corresponds to the specified burst within this region. Requires that the memory abstraction class be associated with the memory allocation
manager that allocated this region.
See uvm_mem::burst_write() for more details.
burst_read
task burst_read(
output uvm_status_e input uvm_reg_addr_t UVM 1.2 Class Reference
status,
offset,
677
output uvm_reg_data_t value[], input uvm_path_e path
= UVM_DEFAULT_PATH,
input uvm_reg_map map
= null,
input uvm_sequence_base parent
= null,
input int prior
= -1,
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Read from a set of memory location in the region.
Read from the memory locations that corresponds to the specified burst within this
region. Requires that the memory abstraction class be associated with the memory
allocation manager that allocated this region.
See uvm_mem::burst_read() for more details.
poke
task poke(
output uvm_status_e status, offset, input uvm_reg_addr_t input uvm_reg_data_t value,
= null,
input uvm_sequence_base parent
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Deposit in a memory location in the region.
Deposit the specified value in the memory location that corresponds to the specified
offset within this region. Requires that the memory abstraction class be associated with
the memory allocation manager that allocated this region.
See uvm_mem::poke() for more details.
peek
task peek(
output uvm_status_e status, offset, input uvm_reg_addr_t output uvm_reg_data_t value,
= null,
input uvm_sequence_base parent
input uvm_object extension = null,
input string fname
= "",
input int lineno
= 0
)
Sample a memory location in the region.
Sample the memory location that corresponds to the specified offset within this region. Requires that the memory abstraction class be associated with the memory allocation
manager that allocated this region.
See uvm_mem::peek() for more details.
uvm_mem_mam_policy
UVM 1.2 Class Reference
678
An instance of this class is randomized to determine the starting offset of a randomly
allocated memory region. This class can be extended to provide additional constraints on
the starting offset, such as word alignment or location of the region within a memory
page. If a procedural region allocation policy is required, it can be implemented in the
pre/post_randomize() method.
Summary
uvm_mem_mam_policy
An instance of this class is randomized to determine the starting offset of a
randomly allocated memory region.
CLass DEcLaRaTION
class uvm_mem_mam_policy
VaRIaBLEs
len
start_offset
min_offset
max_offset
in_use
Number of addresses required
The starting offset of the region
Minimum address offset in the managed address space
Maximum address offset in the managed address space
Regions already allocated in the managed address space
VaRIaBLEs
len
int unsigned len
Number of addresses required
start_offset
rand bit [63:0] start_offset
The starting offset of the region
min_offset
bit [63:0] min_offset
Minimum address offset in the managed address space
max_offset
bit [63:0] max_offset
Maximum address offset in the managed address space
UVM 1.2 Class Reference
679
in_use
uvm_mem_region in_use[$]
Regions already allocated in the managed address space
uvm_mem_mam_cfg
Specifies the memory managed by an instance of a uvm_mem_mam memory allocation
manager class.
Summary
uvm_mem_mam_cfg
Specifies the memory managed by an instance of a uvm_mem_mam memory
allocation manager class.
CLass DEcLaRaTION
class uvm_mem_mam_cfg
VaRIaBLEs
n_bytes
end_offset
mode
locality
Number of bytes in each memory location
Last address of managed space
Region allocation mode
Region location mode
VaRIaBLEs
n_bytes
rand int unsigned n_bytes
Number of bytes in each memory location
end_offset
rand bit [63:0] end_offset
Last address of managed space
mode
rand uvm_mem_mam::alloc_mode_e mode
Region allocation mode
UVM 1.2 Class Reference
680
locality
rand uvm_mem_mam::locality_e locality
Region location mode
UVM 1.2 Class Reference
681
26.1 Generic Register Operation Descriptors
This section defines the abstract register transaction item. It also defines a descriptor
for a physical bus operation that is used by uvm_reg_adapter subtypes to convert from a
protocol-specific address/data/rw operation to a bus-independent, canonical r/w
operation.
Contents
Generic
Register
Operation
Descriptors
This section defines the abstract register transaction item.
uvm_reg_item
uvm_reg_bus_op
Defines an abstract register transaction item.
Struct that defines a generic bus transaction for register and
memory accesses, having kind (read or write), address, data,
and byte enable information.
uvm_reg_item
Defines an abstract register transaction item. No bus-specific information is present,
although a handle to a uvm_reg_map is provided in case a user wishes to implement a
custom address translation algorithm.
Summary
uvm_reg_item
Defines an abstract register transaction item.
CLAss HIErArchY
uvm_void
uvm_object
uvm_transaction
uvm_sequence_item
uvm_reg_item
CLAss DEcLArATIoN
class uvm_reg_item extends uvm_sequence_item
VArIABLEs
element_kind
element
kind
value
offset
status
local_map
UVM 1.2 Class Reference
Kind of element being accessed: REG, MEM, or FIELD.
A handle to the RegModel model element associated with
this transaction.
Kind of access: READ o