# 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 | The uvm_printer class provides an interface for printing uvm_objects in various formats.
uvm_table_printer | The table printer prints output in a tabular format.
uvm_tree_printer | By overriding various methods of the uvm_printer super class, the tree printer prints output in a tree format.
uvm_line_printer | The line printer prints output in a line format.
uvm_printer_knobs | 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

> 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_radix_enum | radix | = | UVM_NORADIX,
> | 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.

### 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.

### format_row

> virtual function string format_row (
> | uvm_printer_row_info | row
> )

Hook for producing custom output of a single field (row).

### format_header

> virtual function string format_header()

Hook to override base header with a custom header.

### format_footer

> virtual function string format_footer()

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, |  |
> | int | size, |  |
> | 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.

### 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 | Creates a new instance of uvm_table_printer.
Methods |
emit | Formats the collected information from prior calls to print_* into table format.

### Variables

### new

> function new()

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 | Creates a new instance of uvm_tree_printer.
Methods |
emit | Formats the collected information from prior calls to print_* into hierarchical tree format.

### Variables

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

### 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 | Indicates whether the uvm_printer::format_header function should be called when printing an object.
footer | Indicates whether the uvm_printer::format_footer function should be called when printing an object.
full_name | Indicates whether uvm_printer::adjust_name should print the full name of an identifier or just the leaf name.
identifier | Indicates whether uvm_printer::adjust_name should print the identifier.
type_name | Controls whether to print a field’s type name.
size | Controls whether to print a field’s size.
depth | Indicates how deep to recurse when printing objects.
reference | Controls whether to print a unique reference ID for object handles.
begin_elements | Defines the number of elements at the head of a list to print.
end_elements | This defines the number of elements at the end of a list that should be printed.
prefix | Specifies the string prepended to each output line
indent | This knob specifies the number of spaces to use for level indentation.
show_root | This setting indicates whether or not the initial object that is printed (when current depth is 0) prints the full path name.
mcd | This is a file descriptor, or multi-channel descriptor, that specifies where the print output should be directed.
separator | For tree printers only, determines the opening and closing separators used for nested objects.
show_radix | Indicates whether the radix string (‘h, and so on) should be prepended to an integral value when one is printed.
default_radix | 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 | 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.
bin_radix | 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 | 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 | 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 | 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 | 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.

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

> 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"

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).

> virtual class uvm_printer

The uvm_printer class provides an interface for printing uvm_objects in various formats.

> virtual class uvm_object extends uvm_void

The uvm_object class is the base class for all UVM data and hierarchical classes.

> class uvm_table_printer extends uvm_printer

The table printer prints output in a tabular format.

> class uvm_tree_printer extends uvm_printer

By overriding various methods of the uvm_printer super class, the tree printer prints output in a tree format.

> class uvm_line_printer extends uvm_tree_printer

The line printer prints output in a line format.

> class uvm_printer_knobs

The uvm_printer_knobs class defines the printer settings available to all printer subtypes.

> uvm_tree_printer uvm_default_tree_printer = new()

The tree printer is a global object that can be used with uvm_object::do_print to get multi-line tree style printing.

> uvm_line_printer uvm_default_line_printer = new()

The line printer is a global object that can be used with uvm_object::do_print to get single-line style printing.

> uvm_table_printer uvm_default_table_printer = new()

The table printer is a global object that can be used with uvm_object::do_print to get tabular style printing.

> uvm_printer uvm_default_printer = uvm_default_table_printer

The default printer policy.

> 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.

> 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.

> virtual class uvm_component extends uvm_report_object

The uvm_component class is the root base class for UVM components.

> bit print_enabled = 1

This bit determines if this component should automatically be printed as a child of its parent object.

> virtual function void print_array_footer (
> | int | size | = | 0
> )

Prints the header of a footer.

> int begin_elements = 5

Defines the number of elements at the head of a list to print.

> int end_elements = 5

This defines the number of elements at the end of a list that should be printed.

> function new()

Creates a new instance of uvm_table_printer.

> virtual function string emit()

Formats the collected information from prior calls to print_* into table format.

> function new()

Creates a new instance of uvm_tree_printer.

> virtual function string emit()

Formats the collected information from prior calls to print_* into hierarchical tree format.

> function new()

Creates a new instance of uvm_line_printer.

> bit header = 1

Indicates whether the uvm_printer::format_header function should be called when printing an object.

> virtual function string format_header()

Hook to override base header with a custom header.

> bit footer = 1

Indicates whether the uvm_printer::format_footer function should be called when printing an object.

> virtual function string format_footer()

Hook to override base footer with a custom footer.

> bit full_name = 0

Indicates whether uvm_printer::adjust_name should print the full name of an identifier or just the leaf 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.

> bit identifier = 1

Indicates whether uvm_printer::adjust_name should print the identifier.

> bit type_name = 1

Controls whether to print a field’s type name.

> bit size = 1

Controls whether to print a field’s size.

> int depth = -1

Indicates how deep to recurse when printing objects.

> bit reference = 1

Controls whether to print a unique reference ID for object handles.

> string prefix = ""

Specifies the string prepended to each output line

> int indent = 2

This knob specifies the number of spaces to use for level indentation.

> 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.

> int mcd = UVM_STDOUT

This is a file descriptor, or multi-channel descriptor, that specifies where the print output should be directed.

> string separator = "{}"

For tree printers only, determines the opening and closing separators used for nested objects.

> bit show_radix = 1

Indicates whether the radix string (‘h, and so on) should be prepended to an integral value when one is printed.

> 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.

> 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).

> virtual function void print_field_int (
> | string | name, |  |
> | uvm_integral_t | value, |  |
> | int | size, |  |
> | uvm_radix_enum | radix | = | UVM_NORADIX,
> | byte | scope_separator | = | ".",
> | string | type_name | = | ""
> )

Prints an integral field (up to 64 bits).

> 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.
Selects decimal (%d) format

> string bin_radix = "'b"

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.
Selects binary (%b) format

> 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.
Selects octal (%o) format

> 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.
Selects unsigned decimal (%u) format

> 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.
Selects hexadecimal (%h) format

> 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).