Utility Library

Methods

• All methods are defined in methods_pkg.vhd, unless otherwise noted.

• All parameters in brackets are optional.

• Legend: bool=boolean, sl=std_logic, slv=std_logic_vector, u=unsigned, s=signed, int=integer

Checks and awaits

Hint

Although all check and await methods have optional [alert_level], it is best practice to always evaluate and assign the most fitting alert_level for any given check or await.

check_value()

Hint

Checking that a value is not equal to another value is possible by using a boolean expression as the [value] parameter.

--Example:
check_value((value_1 /= value_2), ERROR, "Checking that value_1 is not equal value_2");

Checks if value equals exp, and alerts with severity alert_level if the values do not match. The result of the check is returned as a boolean if the method is called as a function.

[boolean :=] check_value(value(bool), [exp(bool)], [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
[boolean :=] check_value(value(sl), exp(sl), [match_strictness], [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
[boolean :=] check_value(value(slv), exp(slv), [match_strictness], [alert_level], msg, [scope, [radix, [format, [msg_id, [msg_id_panel]]]]])
[boolean :=] check_value(value(t_slv_array), exp(t_slv_array), [match_strictness], [alert_level], msg, [scope, [radix, [format, [msg_id, [msg_id_panel]]]]])
[boolean :=] check_value(value(t_unsigned_array), exp(t_unsigned_array), [match_strictness], alert_level, msg, [scope, [radix, [format, [msg_id, [msg_id_panel]]]]])
[boolean :=] check_value(value(t_signed_array), exp(t_signed_array), [match_strictness], alert_level, msg, [scope, [radix, [format, [msg_id, [msg_id_panel]]]]])
[boolean :=] check_value(value(u), exp(u), [alert_level], msg, [scope, [radix, [format, [msg_id, [msg_id_panel]]]]] )
[boolean :=] check_value(value(s), exp(s), [alert_level], msg, [scope, [radix, [format, [msg_id, [msg_id_panel]]]]])
[boolean :=] check_value(value(int), exp(int), [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
[boolean :=] check_value(value(real), exp(real), [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
[boolean :=] check_value(value(time), exp(time), [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])

Object	Name	Dir.	Type	Description
constant	value	in	see overloads	Value to be checked
constant	exp	in	see overloads	Expected value
constant	match_strictness	in	t_match_strictness	Specifies if match needs to be exact or std_match, e.g. ‘H’ = ‘1’. Default value is MATCH_STD.
constant	radix	in	t_radix	Controls how the vector is represented in the log. Default value is HEX_BIN_IF_INVALID.
constant	format	in	t_format_zeros	Controls how the vector is formatted in the log. Default value is KEEP_LEADING_0.
constant	alert_level	in	t_alert_level	Sets the severity for the alert. Default value is ERROR.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg. Default value is ID_POS_ACK.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
check_value(v_int_a, 42, WARNING, "Checking the integer");
v_check := check_value(v_slv5_a, "11100", MATCH_EXACT, "Checking the SLV", "My Scope", HEX, SKIP_LEADING_0, ID_SEQUENCER, shared_msg_id_panel);

Note

Vectors are checked with MSB as left most and that the range is converted from “0 to N” to “N downto 0”. A WARNING is given if arrays are of defined with opposite directions. Different ranges in any dimension will not match.

check_value_in_range()

Checks if min_value ≤ val ≤ max_value, and alerts with severity alert_level if val is outside the range. The result of the check is returned as a boolean if the method is called as a function.

[boolean :=] check_value_in_range(value(u), min_value(u), max_value(u), [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
[boolean :=] check_value_in_range(value(s), min_value(s), max_value(s), [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
[boolean :=] check_value_in_range(value(int), min_value(int), max_value(int), [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
[boolean :=] check_value_in_range(value(time), min_value(time), max_value(time), [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
[boolean :=] check_value_in_range(value(real), min_value(real), max_value(real), [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])

Object	Name	Dir.	Type	Description
constant	value	in	see overloads	Value to be checked
constant	min_value	in	see overloads	Minimum value in the expected range
constant	max_value	in	see overloads	Maximum value in the expected range
constant	alert_level	in	t_alert_level	Sets the severity for the alert. Default value is ERROR.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg. Default value is ID_POS_ACK.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
check_value_in_range(v_int_a, 10, 100, "Checking that integer is in range");

check_stable()

Checks if the target signal has been stable in stable_req time. If not, an alert is asserted.

check_stable(target(bool), stable_req, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
check_stable(target(sl), stable_req, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
check_stable(target(slv), stable_req, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
check_stable(target(u), stable_req, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
check_stable(target(s), stable_req, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
check_stable(target(int), stable_req, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
check_stable(target(real), stable_req, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])

Object	Name	Dir.	Type	Description
signal	target	in	see overloads	Signal to be checked
constant	stable_req	in	time	Period of time to check if the signal is stable
constant	alert_level	in	t_alert_level	Sets the severity for the alert. Default value is ERROR.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg. Default value is ID_POS_ACK.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
check_stable(slv8, 9 ns, "Checking if SLV is stable");

check_sb_completion()

This procedure checks that all the enabled scoreboards are empty, i.e. all expected values checked. The result of the check is returned as a boolean if the method is called as a function.

If an enabled scoreboard has expected values to be checked, an alert will be generated. Otherwise, a successful completion message and the optional reports will be printed in the log.

[boolean :=] check_sb_completion(VOID)
[boolean :=] check_sb_completion(alert_level, [print_alert_counters, [print_sbs, [scope, [msg_id_panel]]]])

Object	Name	Dir.	Type	Description
constant	VOID	in	t_void	A dummy parameter for easier reading syntax
constant	alert_level	in	t_alert_level	Sets the severity for the alert. Default value is TB_ERROR.
constant	print_alert_counters	in	t_report_alert_counters	Whether to print a report of alert counters. Default value is NO_REPORT.
constant	print_sbs	in	t_report_sb	Whether to print a report with all the scoreboards in the testbench. Default value is NO_REPORT.
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
v_check := check_sb_completion(VOID);
check_sb_completion(TB_WARNING, REPORT_ALERT_COUNTERS, REPORT_SCOREBOARDS, C_SCOPE);

await_change()

Waits until the target signal changes, or times out after max_time. An alert is asserted if the signal does not change between min_time and max_time. Note that if the value changes at exactly max_time, the timeout gets precedence.

await_change(target(bool), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change(target(sl), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change(target(slv), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change(target(u), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change(target(s), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change(target(int), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change(target(real), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])

Object	Name	Dir.	Type	Description
signal	target	in	see overloads	Signal to be checked
constant	min_time	in	time	Minimum time that must pass before the signal changes
constant	max_time	in	time	Maximum time for the signal to change
constant	alert_level	in	t_alert_level	Sets the severity for the alert. Default value is ERROR.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg. Default value is ID_POS_ACK.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
await_change(bool, 3 ns, 5 ns, "Awaiting change on bool signal");

await_value()

Waits until the target signal equals the exp signal, or times out after max_time. An alert is asserted if the signal does not equal the expected value between min_time and max_time, or if the target equals exp before min_time. Note that if the value changes to the expected value at exactly max_time, the timeout gets precedence. This procedure is a fall-through procedure when min_time = 0 ns, and will not require a change. For a change to be required. see await_change_to_value() under.

await_value(target(sl), exp(sl), [match_strictness], min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_value(target(slv), exp(slv), [match_strictness], min_time, max_time, [alert_level], msg, [scope, [radix, [format, [msg_id, [msg_id_panel]]]]])
await_value(target(bool), exp(bool), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_value(target(u), exp(u), min_time, max_time, [alert_level], msg, [scope, [radix, [format, [msg_id, [msg_id_panel]]]]])
await_value(target(s), exp(s), min_time, max_time, [alert_level], msg, [scope, [radix, [format, [msg_id, [msg_id_panel]]]]])
await_value(target(int), exp(int), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_value(target(real), exp(real), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])

Object	Name	Dir.	Type	Description
signal	target	in	see overloads	Signal to be checked
constant	exp	in	see overloads	Expected value
constant	match_strictness	in	t_match_strictness	Specifies if match needs to be exact or std_match, e.g. ‘H’ = ‘1’. Default value is MATCH_STD.
constant	min_time	in	time	Minimum time that must pass while target /= exp
constant	max_time	in	time	Maximum time for the signal to change
constant	alert_level	in	t_alert_level	Sets the severity for the alert. Default value is ERROR.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg. Default value is ID_POS_ACK.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
await_value(bool, true, 10 ns, 20 ns, "Waiting for bool to become true");
await_value(slv8, "10101010", MATCH_STD, 3 ns, 7 ns, WARNING, "Waiting for slv8 value");

await_change_to_value()

Waits until the target signal changes to the exp signal, or times out after max_time. If the signal changes to the expected value before min_time, or the signal does not change to the expected value between min_time and max_time, an alert is asserted.

Note

• If the target changes before min_time, but not to the expected value, nothing happens (check will continue until timeout or target changes to expected value)

• If the value changes to the expected value at exactly max_time, the timeout gets precedence.

await_change_to_value(target(sl), exp(sl), [match_strictness], min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change_to_value(target(slv), exp(slv), [match_strictness], min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change_to_value(target(bool), exp(bool), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change_to_value(target(u), exp(u), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change_to_value(target(s), exp(s), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change_to_value(target(int), exp(int), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_change_to_value(target(real), exp(real), min_time, max_time, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])

Object	Name	Dir.	Type	Description
signal	target	in	see overloads	Signal to be checked
constant	exp	in	see overloads	Expected value
constant	match_strictness	in	t_match_strictness	Specifies if match needs to be exact or std_match, e.g. ‘H’ = ‘1’. Default value is MATCH_STD. (only in sl, and slv versions)
constant	min_time	in	time	Minimum time that must pass before the target signal changes to exp
constant	max_time	in	time	Maximum time for the target signal to change to exp
constant	alert_level	in	t_alert_level	Sets the severity for the alert. Default value is ERROR.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg. Default value is ID_POS_ACK.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
await_change_to_value(bool, true, 10 ns, 20 ns, "Waiting for bool to change to true for min 10 ns and max 20 ns");
await_change_to_value(slv8, "10101010", MATCH_STD, 3 ns, 7 ns, WARNING, "Waiting for slv8 to change to value");

await_stable()

Wait until the target signal has been stable for at least stable_req. Report an error if this does not occur within the time specified by timeout. Note that stable refers to that the signal has not had an event (i.e. not changed value).

await_stable(target(bool), stable_req, stable_req_from, timeout, timeout_from, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_stable(target(sl), stable_req, stable_req_from, timeout, timeout_from, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_stable(target(slv), stable_req, stable_req_from, timeout, timeout_from, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_stable(target(u), stable_req, stable_req_from, timeout, timeout_from, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_stable(target(s), stable_req, stable_req_from, timeout, timeout_from, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_stable(target(int), stable_req, stable_req_from, timeout, timeout_from, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])
await_stable(target(real), stable_req, stable_req_from, timeout, timeout_from, [alert_level], msg, [scope, [msg_id, [msg_id_panel]]])

Object	Name	Dir.	Type	Description
signal	target	in	see overloads	Signal to be checked
constant	stable_req	in	time	Period of time to check if the signal is stable
constant	stable_req_from	in	t_from_point_in_time	Point in time to start checking stability of the signal
constant	timeout	in	time	Timeout for the signal to be stable during the required time
constant	timeout_from	in	t_from_point_in_time	Point in time when the timeout starts counting
constant	alert_level	in	t_alert_level	Sets the severity for the alert. Default value is ERROR.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg. Default value is ID_POS_ACK.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
await_stable(u8, 20 ns, FROM_LAST_EVENT, 100 ns, FROM_NOW, ERROR, "Waiting for u8 to stabilize");

await_sb_completion()

This procedure waits for all the enabled scoreboards to be empty, i.e. all expected values checked.

If an enabled scoreboard still has expected values to be checked when the timeout occurs, an alert will be generated. Otherwise, a successful completion message and the optional reports will be printed in the log.

await_sb_completion(timeout, [alert_level, [sb_poll_time, [print_alert_counters, [print_sbs, [scope, [msg_id_panel]]]]]])

Object	Name	Dir.	Type	Description
constant	timeout	in	time	Timeout for the VVCs to be inactive and the scoreboards to be empty. Must be greater than 0.
constant	alert_level	in	t_alert_level	Sets the severity for the alert. Default value is TB_ERROR.
constant	sb_poll_time	in	time	Time to wait until checking again whether the scoreboards have been emptied. Must be greater than 0. Default value is 100 us.
constant	print_alert_counters	in	t_report_alert_counters	Whether to print a report of alert counters. Default value is NO_REPORT.
constant	print_sbs	in	t_report_sb	Whether to print a report with all the scoreboards in the testbench. Default value is NO_REPORT.
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Example: Wait for all Scoreboards to be empty
await_sb_completion(1 ms);

-- Example: Wait for all Scoreboards to be empty and report the alert counters and scoreboards
await_sb_completion(1 ms, TB_WARNING, 1 us, REPORT_ALERT_COUNTERS, REPORT_SCOREBOARDS, C_SCOPE);

Note

This procedure is called within await_uvvm_completion(), which is recommended to use when there are VVCs in the testbench.

Logging and verbosity control

set_log_file_name()

Sets the log file name. To ensure that the entire log transcript is written to a single file, this should be called prior to any other procedures (except set_alert_file_name()). If file name is set after a log message has been written to the log file, a warning will be reported. This warning can be disabled by setting C_WARNING_ON_LOG_ALERT_FILE_RUNTIME_RENAME false in the adaptations_pkg.

set_log_file_name([file_name])

Object	Name	Dir.	Type	Description
constant	file_name	in	string	Name of the log file. Default value is C_LOG_FILE_NAME.

-- Examples:
set_log_file_name("new_log_file_name.txt");

log()

Writes a message to the log. Note that if the msg_id is disabled in the msg_id_panel, the message will not be shown. Some general string handling features are:

• All log messages will be given using the user defined layout in adaptations_pkg.vhd

• \n may be used to force line shifts. Line shift will occur after scope column, before message column

• \r may be used to force line shift at start of log message. The result will be a blank line apart from prefix (message ID, timestamp and scope will be omitted on the first line)

log([msg_id], msg, [scope, [msg_id_panel, [log_destination, [log_file_name, [open_mode]]]]])

Object	Name	Dir.	Type	Description
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg. Default value is C_TB_MSG_ID_DEFAULT.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.
constant	log_destination	in	t_log_destination	Defines where the message will be written to. Default value is shared_default_log_destination.
constant	log_file_name	in	string	Defines the log file where message shall be written to. Default value is C_LOG_FILE_NAME.
constant	open_mode	in	file_open_kind	Indicates how the log file shall be opened (write_mode, append_mode). Default value is append_mode.

-- Examples:
log(ID_SEQUENCER, "message to log");
log(ID_BFM, "Msg", "MyScope", local_msg_id_panel, LOG_ONLY, "new_log.txt", write_mode);

log_text_block()

Writes a text block from a VHDL line to the log.

log_text_block(msg_id, text_block, formatting, [msg_header, [scope, [msg_id_panel, [log_if_block_empty, [log_destination, [log_file_name, [open_mode]]]]]]])

Object	Name	Dir.	Type	Description
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg
variable	text_block	inout	line	Line where the text block is stored
constant	formatting	in	t_log_format	Whether the text is formatted or not
constant	msg_header	in	string	Header message for the text_block. Default value is “”.
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.
constant	log_if_block_empty	in	t_log_if_block_empty	Defines how an empty text block is handled. Default value is WRITE_HDR_IF_BLOCK_EMPTY.
constant	log_destination	in	t_log_destination	Defines where the text block will be written to. Default value is shared_default_log_destination.
constant	log_file_name	in	string	Defines the log file where text block shall be written to. Default value is C_LOG_FILE_NAME.
constant	open_mode	in	file_open_kind	Indicates how the log file shall be opened (write_mode, append_mode). Default value is append_mode.

-- Examples:
log_text_block(ID_SEQUENCER, v_line, UNFORMATTED);
log_text_block(ID_BFM, v_line, FORMATTED, "Header", "MyScope");

enable_log_msg()

Enables logging for the given msg_id. (See Message IDs for examples of different IDs).

enable_log_msg(msg_id, [quietness, [scope]])
enable_log_msg(msg_id, msg, [quietness, [scope]])
enable_log_msg(msg_id, msg_id_panel, [msg, [scope, [quietness]]])

Object	Name	Dir.	Type	Description
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg
constant	quietness	in	t_quietness	Logging of this procedure can be turned off by setting quietness=QUIET. Default value is NON_QUIET.
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg	in	string	A custom message to be appended in the log/alert. Default value is “”.
variable	msg_id_panel	inout	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
enable_log_msg(ID_SEQUENCER);

disable_log_msg()

Disables logging for the given msg_id. (See Message IDs for examples of different IDs).

disable_log_msg(msg_id, [quietness, [scope]])
disable_log_msg(msg_id, msg, [quietness, [scope]])
disable_log_msg(msg_id, msg_id_panel, [msg, [scope, [quietness]]])

Object	Name	Dir.	Type	Description
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg
constant	quietness	in	t_quietness	Logging of this procedure can be turned off by setting quietness=QUIET. Default value is NON_QUIET.
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg	in	string	A custom message to be appended in the log/alert. Default value is “”.
variable	msg_id_panel	inout	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
disable_log_msg(ID_LOG_HDR);

is_log_msg_enabled()

Returns true if the given message ID is enabled, otherwise false.

boolean := is_log_msg_enabled(msg_id, [msg_id_panel])

Object	Name	Dir.	Type	Description
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
v_is_enabled := is_log_msg_enabled(ID_SEQUENCER);

set_log_destination()

Sets the default log destination for all log procedures. The destination specified in this log_destination will be used unless the log_destination argument in the log procedure is specified. A log message is written to log ID ID_LOG_MSG_CTRL if quietness is set to NON_QUIET.

set_log_destination(log_destination, [quietness])

Object	Name	Dir.	Type	Description
constant	log_destination	in	t_log_destination	Defines where all the log procedures will be written to
constant	quietness	in	t_quietness	Logging of this procedure can be turned off by setting quietness=QUIET. Default value is NON_QUIET.

-- Examples:
set_log_destination(CONSOLE_ONLY);

Alert handling

set_alert_file_name()

Sets the alert file name. To ensure that the entire log transcript is written to a single file, this should be called prior to any other procedures (except set_alert_file_name()). If file name is set after a log message has been written to the log file, a warning will be reported. This warning can be disabled by setting C_WARNING_ON_LOG_ALERT_FILE_RUNTIME_RENAME false in the adaptations_pkg.

set_alert_file_name(file_name)

Object	Name	Dir.	Type	Description
constant	file_name	in	string	Name of the alert file. Default value is C_ALERT_FILE_NAME.

-- Examples:
set_alert_file_name("new_alert_log_file.txt");

alert()

• Asserts an alert with severity given by alert_level.

• Increment the counters for the given alert_level.

• If the stop_limit for the given alert_level is reached, stop the simulation.

alert(alert_level, msg, [scope])

Object	Name	Dir.	Type	Description
constant	alert_level	in	t_alert_level	Sets the severity for the alert
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.

-- Examples:
alert(TB_WARNING, "This is a TB warning");

alert() overloads

Overloads for alert(). Note that: warning(msg, [scope]) = alert(warning, msg, [scope]).

note(msg, [scope])          tb_note(msg, [scope])
warning(msg, [scope])       tb_warning(msg, [scope])
error(msg, [scope])         tb_error(msg, [scope])
failure(msg, [scope])       tb_failure(msg, [scope])
manual_check(msg, [scope])

Object	Name	Dir.	Type	Description
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.

-- Examples:
note("This is a note");
tb_failure("This is a TB failure", "tb_scope");

increment_expected_alerts()

Increments the expected alert counter for the given alert_level.

increment_expected_alerts(alert_level, [number, [msg, [scope]]])

Object	Name	Dir.	Type	Description
constant	alert_level	in	t_alert_level	Sets the severity for the alert
constant	number	in	natural	Number to increment the counter. Default value is 1.
constant	msg	in	string	A custom message to be appended in the log/alert. Default value is “”.
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.

-- Examples:
increment_expected_alerts_and_stop_limit(WARNING, 2, "Expecting two more warnings");

set_alert_stop_limit()

Simulator will stop when hitting a number of specified alert type (0 means never stop).

set_alert_stop_limit(alert_level, value)

Object	Name	Dir.	Type	Description
constant	alert_level	in	t_alert_level	Sets the severity for the alert
constant	value	in	natural	Number to set the stop limit

-- Examples:
set_alert_stop_limit(ERROR, 2);

increment_expected_alerts_and_stop_limit()

Increments the expected alert counter and stop limit for the given alert_level.

increment_expected_alerts_and_stop_limit(alert_level, [number, [msg, [scope]]])

Object	Name	Dir.	Type	Description
constant	alert_level	in	t_alert_level	Sets the severity for the alert
constant	number	in	natural	Number to set the stop limit. Default value is 1.
constant	msg	in	string	A custom message to be appended in the log/alert. Default value is “”.
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.

-- Examples:
increment_expected_alerts_and_stop_limit(WARNING, 2, "Expecting two more warnings");

get_alert_stop_limit()

Returns current stop limit for given alert type.

natural := get_alert_stop_limit(alert_level)

Object	Name	Dir.	Type	Description
constant	alert_level	in	t_alert_level	Sets the severity for the alert

-- Examples:
v_int := get_alert_stop_limit(FAILURE);

set_alert_attention()

Set given alert type to t_attention: IGNORE or REGARD.

set_alert_attention(alert_level, attention, [msg])

Object	Name	Dir.	Type	Description
constant	alert_level	in	t_alert_level	Sets the severity for the alert
constant	attention	in	t_attention	Sets the attention for the alert
constant	msg	in	string	A custom message to be appended in the log/alert. Default value is “”.

-- Examples:
set_alert_attention(NOTE, IGNORE, "Ignoring all note-alerts");

get_alert_attention()

Returns current attention (IGNORE or REGARD) for given alert type.

t_attention := get_alert_attention(alert_level)

Object	Name	Dir.	Type	Description
constant	alert_level	in	t_alert_level	Sets the severity for the alert

-- Examples:
v_attention := get_alert_attention(WARNING)

Reporting

report_global_ctrl()

Logs the values in the global_ctrl signal, which is described in Using Hierarchical Alert Reporting.

report_global_ctrl(VOID)

Object	Name	Dir.	Type	Description
constant	VOID	in	t_void	A dummy parameter for easier reading syntax

report_msg_id_panel()

Logs the values in the msg_id_panel, which is described in Using Hierarchical Alert Reporting.

report_msg_id_panel(VOID)

Object	Name	Dir.	Type	Description
constant	VOID	in	t_void	A dummy parameter for easier reading syntax

report_alert_counters()

Logs the status of all alert counters, typically at the end of simulation. For each alert_level, the alert counter is compared with the expected counter. If parameter is FINAL, an additional summary concluding success or failure is logged. VOID parameter gives same result as FINAL.

report_alert_counters(order)
report_alert_counters(VOID)

Object	Name	Dir.	Type	Description
constant	order	in	t_order	Whether the report is to be printed during simulation or at the end
constant	VOID	in	t_void	A dummy parameter for easier reading syntax

-- Examples:
report_alert_counters(VOID);
report_alert_counters(FINAL);
report_alert_counters(INTERMEDIATE);

report_check_counters()

Logs the number of all check counters in the testbench, typically to be used at the end of simulation. Note that this functionality is disabled by default to avoid possible decreased performance, set C_ENABLE_CHECK_COUNTER to true in adaptations_pkg to enable it. The VOID parameter gives same result as FINAL.

report_check_counters(order)
report_check_counters(VOID)

Object	Name	Dir.	Type	Description
constant	order	in	t_order	Whether the report is to be printed during simulation or at the end
constant	VOID	in	t_void	A dummy parameter for easier reading syntax

-- Examples:
report_check_counters(VOID);
report_check_counters(FINAL);
report_check_counters(INTERMEDIATE);

Shared variables

These shared variables are natural, read only types.

• shared_uvvm_status.found_unexpected_simulation_warnings_or_worse

  Status is ‘0’ on success and ‘1’ on failure.

  The variable is set when actual > expected for WARNING, ERROR or FAILURE alerts.

• shared_uvvm_status.found_unexpected_simulation_errors_or_worse

  Status is ‘0’ on success and ‘1’ on failure.

  The variable is set when actual > expected for ERROR or FAILURE alerts.

• shared_uvvm_status.mismatch_on_expected_simulation_warnings_or_worse

  Status is ‘0’ on success and ‘1’ on failure.

  The variable is set when there is a mismatch between the expected and the actual WARNING, ERROR or FAILURE alerts.

• shared_uvvm_status.mismatch_on_expected_simulation_errors_or_worse

  Status is ‘0’ on success and ‘1’ on failure.

  The variable is set when there is a mismatch between the expected and the actual ERROR or FAILURE alerts.

Basic Randomization

random() - function

Returns a random value. The function uses and updates a global seed.

std_logic        := random(VOID)
std_logic_vector := random(length)
integer          := random(min_value(int), max_value(int))
real             := random(min_value(real), max_value(real))
time             := random(min_value(time), max_value(time), [time_resolution(time)])

Object	Name	Dir.	Type	Description
constant	VOID	in	t_void	A dummy parameter for easier reading syntax
constant	length	in	integer	Length of the random vector to return
constant	min_value	in	see overloads	Minimum value in the range to generate the random number
constant	max_value	in	see overloads	Maximum value in the range to generate the random number
constant	time_resolution	in	time	Defines how many values can be generated between min_value and max_value. If the given resolution is too small for the range, a TB_WARNING will be printed once. Default value is the simulator time resolution.

-- Examples:
v_sl   := random(VOID);
v_slv  := random(v_slv'length);
v_int  := random(1, 10);
v_real := random(0.01, 0.03);
v_time := random(25 us, 50 us);     -- Generates random values with the default resolution of the simulator
v_time := random(25 us, 50 us, us); -- Generates random values with a resolution of 1 us

random() - procedure

Sets v_target to a random value. The procedure uses and updates v_seed1 and v_seed2.

random(v_seed1, v_seed2, v_target(sl))
random(v_seed1, v_seed2, v_target(slv))
random(min_value(int), max_value(int), v_seed1, v_seed2, v_target(int))
random(min_value(real), max_value(real), v_seed1, v_seed2, v_target(real))
random(min_value(time), max_value(time), [time_resolution(time)], v_seed1, v_seed2, v_target(time))

Object	Name	Dir.	Type	Description
constant	min_value	in	see overloads	Minimum value in the range to generate the random number
constant	max_value	in	see overloads	Maximum value in the range to generate the random number
constant	time_resolution	in	time	Defines how many values can be generated between min_value and max_value. If the given resolution is too small for the range, a TB_WARNING will be printed once. Default value is the simulator time resolution.
variable	v_seed1	inout	positive	Randomization seed 1
variable	v_seed2	inout	positive	Randomization seed 2
variable	v_target	inout	see overloads	Variable where the random value is placed

-- Examples:
random(v_seed1, v_seed2, v_sl);
random(v_seed1, v_seed2, v_slv);
random(1, 10, v_seed1, v_seed2, v_int);
random(0.01, 0.03, v_seed1, v_seed2, v_real);
random(25 us, 50 us, v_seed1, v_seed2, v_time);     -- Generates random values with the default resolution of the simulator
random(25 us, 50 us, us, v_seed1, v_seed2, v_time); -- Generates random values with a resolution of 1 us

randomize()

Sets the global seeds to seed1 and seed2.

randomize(seed1, seed2, [msg, [scope])

Object	Name	Dir.	Type	Description
constant	seed1	in	positive	Randomization seed 1
constant	seed2	in	positive	Randomization seed 2
constant	msg	in	string	A custom message to be appended in the log/alert. Default value is “randomizing seeds”.
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.

-- Examples:
randomize(12, 14, "Setting global seeds");

String handling

Methods are defined in string_methods_pkg.vhd

to_string() - IEEE [1]

IEEE defined to_string functions. Return a string with the value of the argument ‘value’.

string := to_string(value(ANY_SCALAR_TYPE))
string := to_string(value(slv))
string := to_string(value(time), unit(time))
string := to_string(value(real), digits(natural))
string := to_string(value(real), format(string)) -- C-style formatting

to_string()

Additions to the IEEE defined to_string functions. Return a string with the value of the argument ‘val’.

string := to_string(val(bool), width, justified, format_spaces, [truncate])
string := to_string(val(int), width, justified, format_spaces, [truncate, [radix, [prefix, [format]]]])
string := to_string(val(int), radix, prefix, [format])
string := to_string(val(slv), radix, [format, [prefix]])
string := to_string(val(u), radix, [format, [prefix]])
string := to_string(val(s), radix, [format, [prefix]])
string := to_string(val(t_slv_array), [radix, [format, [prefix]]])
string := to_string(val(t_signed_array), [radix, [format, [prefix]]])
string := to_string(val(t_unsigned_array), [radix, [format, [prefix]]])
string := to_string(val(integer_vector), [radix, [format, [prefix]]])
string := to_string(val(t_natural_vector), [radix, [format, [prefix]]])
string := to_string(val(real_vector))
string := to_string(val(time_vector))
string := to_string(val(string)) -- Removes non printable ASCII characters

Object	Name	Dir.	Type	Description
constant	val	in	see overloads	Value to be converted into string
constant	width	in	natural	Width of the returned string
constant	justified	in	side	Which side to justify the text (RIGHT, LEFT)
constant	format_spaces	in	t_format_spaces	Whether to keep or skip the leading spaces
constant	truncate	in	t_truncate_string	Whether to truncate the string or not. Default value is DISALLOW_TRUNCATE.
constant	radix	in	t_radix	Radix of the string value. Default value is different depending on the overload.
constant	prefix	in	t_radix_prefix	Whether to include the radix or not. Default value is EXCL_RADIX.
constant	format	in	t_format_zeros	Whether to keep or skip the leading zeros. Default value is different depending on the overload.

-- Examples:
v_string := to_string(v_u8, DEC);
v_string := to_string(v_slv8, HEX, AS_IS, INCL_RADIX);

ascii_to_char()

Returns the character for the ASCII value.

character := ascii_to_char(ascii_pos, [ascii_allow])

Object	Name	Dir.	Type	Description
constant	ascii_pos	in	integer	ASCII number input
constant	ascii_allow	in	t_ascii_allow	Decide what to do with invisible control characters. If ALLOW_ALL: return the character for any ascii_pos. If ALLOW_PRINTABLE_ONLY: return the character only if it is printable. Default value is ALLOW_ALL.

-- Examples:
v_char := ascii_to_char(65); -- ASCII 'A'

char_to_ascii()

Returns the ASCII value for the character.

integer := char_to_ascii(char)

Object	Name	Dir.	Type	Description
constant	char	in	character	Character to be converted to ASCII

-- Examples:
v_int := char_to_ascii('A'); -- Returns 65

to_upper()

Returns a string containing an uppercase version of the argument ‘val’.

string := to_upper(val)

Object	Name	Dir.	Type	Description
constant	val	in	string	Value to be converted into uppercase

-- Examples:
v_string := to_upper("lowercase string");

justify() - IEEE [1]

IEEE implementation of justify. Returns a string where ‘value’ is justified to the side given by ‘justified’.

string := justify(value, [justified], [field])

Object	Name	Dir.	Type	Description
constant	value	in	string	Value to be converted into uppercase
constant	justified	in	side	Which side to justify the text (RIGHT, LEFT). Default value is RIGHT.
constant	field	in	width	Default value is 0

justify()

Addition to the IEEE implementation of justify(). Returns a string where ‘val’ is justified to the side given by ‘justified’. In addition to right and left, center is also an option. The string can be truncated with the ‘truncate’ parameter or leading spaces can be removed with ‘format_spaces’.

string := justify(val, justified, width, format_spaces, truncate)

Object	Name	Dir.	Type	Description
constant	val	in	string	Value to be justified
constant	justified	in	side	Which side to justify the text (RIGHT, LEFT, CENTER)
constant	width	in	natural	Width of the returned string
constant	format_spaces	in	t_format_spaces	Whether to keep or skip the leading spaces
constant	truncate	in	t_truncate_string	Whether to truncate the string or not

-- Examples:
v_string := justify("string", RIGHT, C_STRING_LENGTH, ALLOW_TRUNCATE, KEEP_LEADING_SPACE);

fill_string()

Returns a string filled with the given character.

string := fill_string(val, width)

Object	Name	Dir.	Type	Description
constant	val	in	character	Character to fill the string with
constant	width	in	natural	Width of the returned string

-- Examples:
v_string := fill_string('X', 10);

pad_string()

Returns a string of a certain width with the string ‘val’ on the side of the string given in ‘side’. The remaining width is padded with ‘char’.

string := pad_string(val, char, width, [side])

Object	Name	Dir.	Type	Description
constant	val	in	string	Input string
constant	char	in	character	Character to use as padding
constant	width	in	natural	Width of the returned string
constant	side	in	side	Which side to justify the text (RIGHT, LEFT). Default value is LEFT.

-- Examples:
v_string := pad_string("abcde", '-', 10, LEFT); -- Returns "abcde-----"

remove_initial_chars()

Returns the input string minus the ‘num’ first characters.

string := remove_initial_chars(source, num)

Object	Name	Dir.	Type	Description
constant	source	in	string	Input string
constant	num	in	natural	Number of characters to remove

-- Examples:
v_string := remove_initial_chars("abcde", 1); -- Returns "bcde"

replace() - function

Returns a string where the target character has been replaced by the exchange character.

string := replace(val, target_char, exchange_char)

Object	Name	Dir.	Type	Description
constant	val	in	string	Input string
constant	target_char	in	character	Character to be replaced
constant	exchange_char	in	character	Replacement character

-- Examples:
v_string := replace("string_x", 'x', 'y'); -- Returns "string_y"

replace() - procedure

Similar to function version of replace(). Line procedure replaces the input with a line where the target character has been replaced by the exchange character.

replace(text_line, target_char, exchange_char)

Object	Name	Dir.	Type	Description
variable	text_line	inout	line	Text line
constant	target_char	in	character	Character to be replaced
constant	exchange_char	in	character	Replacement character

-- Examples:
replace(str, 'a', 'b');

pos_of_leftmost()

Returns the position of the leftmost character in the string. If not found, returns ‘result_if_not_found’.

natural := pos_of_leftmost(target, vector, [result_if_not_found])

Object	Name	Dir.	Type	Description
constant	target	in	character	Character to search for
constant	vector	in	string	String where to look for the character
constant	result_if_not_found	in	natural	Return value if character not found. Default value is 1.

-- Examples:
v_natural := pos_of_leftmost('x', v_string);

pos_of_leftmost_non_zero()

Returns the position of the leftmost character, which is not zero or white-space, in the string. If not found, returns ‘result_if_not_found’.

natural := pos_of_leftmost_non_zero(vector, [result_if_not_found])

Object	Name	Dir.	Type	Description
constant	vector	in	string	String where to look for the character
constant	result_if_not_found	in	natural	Return value if character not found. Default value is 1.

-- Examples:
v_natural := pos_of_leftmost_non_zero(v_string);

pos_of_rightmost()

Returns the position of the rightmost character in the string. If not found, returns ‘result_if_not_found’.

natural := pos_of_rightmost(target, vector, [result_if_not_found])

Object	Name	Dir.	Type	Description
constant	target	in	character	Character to search for
constant	vector	in	string	String where to look for the character
constant	result_if_not_found	in	natural	Return value if character not found. Default value is 1.

-- Examples:
v_natural := pos_of_rightmost('A', v_string);

pos_of_rightmost_non_whitespace()

Returns the position of the rightmost character, which is not white-space, in the string. If not found, returns ‘result_if_not_found’.

natural := pos_of_rightmost_non_whitespace(vector, [result_if_not_found])

Object	Name	Dir.	Type	Description
constant	vector	in	string	String where to look for the character
constant	result_if_not_found	in	natural	Return value if character not found. Default value is 1.

-- Examples:
v_natural := pos_of_rightmost_non_whitespace(v_string);

get_[procedure|process|entity]_name from_instance_name()

Returns the procedure, process or entity name from the given instance name as a string. The instance name must be <object>’instance_name, where object is a signal, variable or constant defined in the procedure, process or entity respectively.

string := get_procedure_name_from_instance_name(val)
string := get_process_name_from_instance_name(val)
string := get_entity_name_from_instance_name(val)

Object	Name	Dir.	Type	Description
constant	val	in	string	Instance name

-- Examples:
v_string := get_procedure_name_from_instance_name(C_INT'instance_name);
v_string := get_process_name_from_instance_name(C_INT'instance_name);
v_string := get_entity_name_from_instance_name(C_INT'instance_name);

return_string_if_true()

Returns the val string if the condition is true, otherwise it returns an empty string.

string := return_string_if_true(val, return_val)

Object	Name	Dir.	Type	Description
constant	val	in	string	String to return if condition is true
constant	return_val	in	boolean	Condition to decide which string to return

-- Examples:
v_string := return_string_if_true("abcde", v_print_txt);

return_string1_if_true_otherwise_string2()

Returns the val1 string if the condition is true, otherwise it returns the val2 string.

string := return_string1_if_true_otherwise_string2(val1, val2, return_val)

Object	Name	Dir.	Type	Description
constant	val1	in	string	String to return if condition is true
constant	val2	in	string	String to return if condition is false
constant	return_val	in	boolean	Condition to decide which string to return

-- Examples:
v_string := return_string1_if_true_otherwise_string2("abcde", "fghij", v_print_first);

Signal generators

clock_generator()

Generates a clock signal. Usage: Include the clock_generator as a concurrent procedure from your testbench.

clock_generator(clock_signal, [clock_count], clock_period, [clock_high_percentage])
clock_generator(clock_signal, [clock_count], clock_period, clock_high_time)
clock_generator(clock_signal, clock_ena, [clock_count], clock_period, clock_name, [clock_high_percentage])
clock_generator(clock_signal, clock_ena, [clock_count], clock_period, clock_name, clock_high_time)

Object	Name	Dir.	Type	Description
signal	clock_signal	inout	std_logic	Clock signal
signal	clock_ena	in	boolean	Start or stop the clock during simulation. Each start / stop is logged (if msg_id ID_CLOCK_GEN is enabled).
signal	clock_count	out	natural	Counts the number of clock cycles. Starts at 0 and wraps when reaching max value of natural type.
constant	clock_period	in	time	Clock period
constant	clock_high_percentage	in	natural	Duty cycle in percentage (1 to 99). Default value is 50.
constant	clock_high_time	in	time	Duty cycle in time
constant	clock_name	in	string	Name of the clock

-- Examples:
clock_generator(clk50M, 20 ns);
clock_generator(clk100M, clk100M_ena, 10 ns, "100 MHz with 60% duty cycle", 60);
clock_generator(clk100M, clk100M_ena, clk100M_cnt, 10 ns, "100 MHz with 60% duty cycle", 6 ns);

adjustable_clock_generator()

Generates a clock with adjustable duty cycle. Usage: Include the adjustable_clock_generator as a concurrent procedure from your testbench.

adjustable_clock_generator(clock_signal, clock_ena, clock_period, [clock_name], clock_high_percentage)
adjustable_clock_generator(clock_signal, clock_ena, clock_count, clock_period, clock_name, clock_high_percentage)

Object	Name	Dir.	Type	Description
signal	clock_signal	inout	std_logic	Clock signal
signal	clock_ena	in	boolean	Start or stop the clock during simulation. Each start / stop is logged (if msg_id ID_CLOCK_GEN is enabled).
signal	clock_count	out	natural	Counts the number of clock cycles. Starts at 0 and wraps when reaching max value of natural type.
constant	clock_period	in	time	Clock period
signal	clock_high_percentage	in	natural	Duty cycle in percentage (1 to 99).
constant	clock_name	in	string	Name of the clock

-- Examples:
adjustable_clock_generator(clk50M, clk50M_ena, 20 ns, 50);
adjustable_clock_generator(clk50M, clk50M_ena, 20 ns, "100MHz clock with 50% duty cycle", 50);
adjustable_clock_generator(clk50M, clk50M_ena, clk50M_cnt, 20 ns, "100MHz clock with 60% duty cycle", 60);

gen_pulse()

Generates a pulse on the target signal for a certain amount of time or a number of clock cycles. Note that the clock_signal version will synchronize the pulse to clock_signal and begin the pulse on the falling edge and end the pulse on a succeeding falling edge.

gen_pulse(target(sl), [pulse_value(sl)], pulse_duration, [blocking_mode], msg, [scope, [msg_id, [msg_id_panel]]])
gen_pulse(target(sl), [pulse_value(sl)], clock_signal, num_periods, msg, [scope, [msg_id, [msg_id_panel]]])
gen_pulse(target(bool), [pulse_value(bool)], pulse_duration, [blocking_mode], msg, [scope, [msg_id, [msg_id_panel]]])
gen_pulse(target(bool), [pulse_value(bool)], clock_signal, num_periods, msg, [scope, [msg_id, [msg_id_panel]]])
gen_pulse(target(slv), [pulse_value(slv)], pulse_duration, [blocking_mode], msg, [scope, [msg_id, [msg_id_panel]]])
gen_pulse(target(slv), [pulse_value(slv)], clock_signal, num_periods, msg, [scope, [msg_id, [msg_id_panel]]])

Object	Name	Dir.	Type	Description
signal	target	inout	see overloads	Signal where to generate the pulse
constant	pulse_value	in	see overloads	Pulse value. Default is ‘1’ | true | (others=>’1’)
signal	clock_signal	in	std_logic	Clock signal to synchronize the pulse with
constant	num_periods	in	integer	Duration of the pulse in clock periods
constant	pulse_duration	in	time	Duration of the pulse in time
constant	blocking_mode	in	t_blocking_mode	When BLOCKING, the procedure blocks the caller until the pulse is done. When NON_BLOCKING, the procedure starts the pulse and schedules the end of the pulse so that the caller can continue immediately.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.
constant	msg_id	in	t_msg_id	Message ID used in the log, defined in adaptations_pkg. Default value is ID_GEN_PULSE.
constant	msg_id_panel	in	t_msg_id_panel	Controls verbosity within a specified scope. Default value is shared_msg_id_panel.

-- Examples:
gen_pulse(sl_1, 50 ns, BLOCKING, "Pulsing for 50 ns");
gen_pulse(sl_1, '1', 50 ns, BLOCKING, "Pulsing for 50 ns");
gen_pulse(slv8, 50 ns, "Pulsing SLV for 50 ns", ALLOW_PULSE_CONTINUATION);
gen_pulse(slv8, x"AB", clk100M, 2, "Pulsing SLV for 2 clock periods");

Synchronization

Note

It is recommended to use a constant for flag_name to avoid typing errors in methods block_flag(), unblock_flag() and await_unblock_flag().

block_flag()

Blocks a flag to allow synchronization between processes. Adds a new blocked flag if it does not already exist. Maximum number of flags can be modified in adaptations_pkg. Generates an alert with already_blocked_severity if the flag is already blocked.

block_flag(flag_name, msg, [already_blocked_severity, [scope]])

Object	Name	Dir.	Type	Description
constant	flag_name	in	string	Name of the flag. Recommended to use a constant.
constant	already_blocked_severity	in	t_alert_level	Sets the severity for the alert when a flag is already blocked. Default value is WARNING.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.

-- Examples:
block_flag("my_flag", "blocking my flag");
block_flag(C_MY_FLAG_1, "blocking " & C_MY_FLAG_1, WARNING, "My Scope");

unblock_flag()

Unblocks a flag to allow a process that is waiting on that flag to continue. Adds a new unblocked flag if it does not already exist.

unblock_flag(flag_name, msg, trigger, [scope])

Object	Name	Dir.	Type	Description
constant	flag_name	in	string	Name of the flag. Recommended to use a constant.
signal	trigger	inout	std_logic	Must use the global signal global_trigger which allows await_unblock_flag() to detect unblocking
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.

-- Examples:
unblock_flag("my_flag", "unblocking my flag", global_trigger);
unblock_flag(C_MY_FLAG_1, "unblocking " & C_MY_FLAG_1, global_trigger, "My Scope");

await_unblock_flag()

Waits for a flag to be unblocked. Continues immediately if the flag already is unblocked. Adds a new blocked flag if it does not already exist and waits for the flag to be unblocked. Generates an alert with timeout_severity if the flag is not unblocked within the timeout. The flag can be re-blocked when leaving the process by setting flag_returning=RETURN_TO_BLOCK.

await_unblock_flag(flag_name, timeout, msg, [flag_returning, [timeout_severity, [scope]]])

Object	Name	Dir.	Type	Description
constant	flag_name	in	string	Name of the flag. Recommended to use a constant.
constant	timeout	in	time	Timeout for the flag to be unblocked. A value of 0 ns means wait forever.
constant	timeout_severity	in	t_alert_level	Sets the severity for the alert when a flag is not unblocked within the timeout. Default value is ERROR.
constant	flag_returning	in	t_flag_returning	Status of the flag after exiting the procedure. Default value is KEEP_UNBLOCKED.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.

-- Examples:
await_unblock_flag("my_flag", 0 ns, "waiting for my_flag to be unblocked");
await_unblock_flag("my_flag", 10 us, "waiting for my_flag to be unblocked", RETURN_TO_BLOCK, WARNING);
await_unblock_flag(C_MY_FLAG_1, 10 us, "waiting for " & C_MY_FLAG_1 & " to be unblocked", RETURN_TO_BLOCK, WARNING, "My Scope");

await_barrier()

The procedure can be used to synchronize between several sequencers. When the procedure is called, it waits for all sequencers using the same barrier_signal to reach their call of await_barrier().

await_barrier(barrier_signal, timeout, msg, [timeout_severity, [scope]])

Object	Name	Dir.	Type	Description
signal	barrier_signal	inout	std_logic	Name of the barrier signal. You may use the predefined global_barrier or define your own barrier_signal of type std_logic.
constant	timeout	in	time	Timeout for all the sequencers to reach the same barrier signal. A value of 0 ns means wait forever.
constant	timeout_severity	in	t_alert_level	Sets the severity for the alert when the barrier is not reached within the timeout. Default value is ERROR.
constant	msg	in	string	A custom message to be appended in the log/alert
constant	scope	in	string	Describes the scope from which the log/alert originates. Default value is C_TB_SCOPE_DEFAULT.

-- Examples:
await_barrier(global_barrier, 100 us, "waiting for global barrier", ERROR, "My Scope");

BFM Common package

Methods are defined in bfm_common_pkg.vhd

normalize_and_check()

Normalize ‘value’ to the width given by ‘target’.

• If value’length > target’length, remove leading zeros (or sign bits) from value.

• If value’length < target’length, add padding (leading zeros, or sign bits) to value.

std_logic_vector := normalize_and_check(value(slv), target(slv), mode, value_name, target_name, msg)
unsigned         := normalize_and_check(value(u), target (u), mode, value_name, target_name, msg)
signed           := normalize_and_check(value(s), target (s), mode, value_name, target_name, msg)
t_slv_array      := normalize_and_check(value(t_slv_array), target(t_slv_array), mode, value_name, target_name, msg)
t_unsigned_array := normalize_and_check(value(t_unsigned_array), target(t_unsigned_array), mode, value_name, target_name, msg)
t_signed_array   := normalize_and_check(value(t_signed_array), target(t_signed_array), mode, value_name, target_name, msg)

Object	Name	Dir.	Type	Description
constant	value	in	see overloads	Value to be normalized
constant	target	in	see overloads	Parameter used to normalize the value
constant	mode	in	t_normalization_mode	Used for sanity checks, it can be one of: ALLOW_WIDER : Allow only value’length >= target’length ALLOW_NARROWER : Allow only value’length <= target’legth ALLOW_WIDER_NARROWER : Allow both of the above ALLOW_EXACT_ONLY: Allow only value’length = target’legth
constant	value_name	in	string	Name of the value for logging purposes
constant	target_name	in	string	Name of the target for logging purposes
constant	msg	in	string	A custom message to be appended in the log/alert

-- Examples:
v_slv8 := normalize_and_check(v_slv5, v_slv8, ALLOW_NARROWER, "8bit slv", "5bit slv", "Normalizing and checking slv");

wait_until_given_time_after_rising_edge()

Wait until a certain time has passed after the rising edge of the clock. If the time passed since the previous rising_edge is less than wait_time, don’t wait until the next rising_edge, just wait_time after the previous rising_edge.

wait_until_given_time_after_rising_edge(clk, wait_time)

Object	Name	Dir.	Type	Description
signal	clk	in	std_logic	Clock signal
constant	wait_time	in	time	Time to wait after the rising edge of the clock

-- Examples:
wait_until_given_time_after_rising_edge(clk50M, 5 ns);

wait_until_given_time_before_rising_edge()

Wait until a certain time before the rising edge of the clock. If the time until rising_edge is less than time_to_edge, wait until the next rising_edge and afterwards until time_to_edge before rising_edge.

wait_until_given_time_before_rising_edge(clk, time_to_edge, clk_period)

Object	Name	Dir.	Type	Description
signal	clk	in	std_logic	Clock signal
constant	time_to_edge	in	time	Time to wait before the rising edge of the clock
constant	clk_period	in	time	Clock period

-- Examples:
wait_until_given_time_before_rising_edge(clk50M, 2 ns, 10 ns);

wait_num_rising_edge()

Waits for a number of rising edges of the clk signal.

wait_num_rising_edge(clk, num_rising_edge)

Object	Name	Dir.	Type	Description
signal	clk	in	std_logic	Clock signal
constant	num_rising_edge	in	natural	Number of rising edges of the clock to wait for

-- Examples:
wait_num_rising_edge(clk50M, 5);

wait_num_rising_edge_plus_margin()

Waits for a number of rising edges of the clk signal, and then waits for a margin.

wait_num_rising_edge_plus_margin(clk, num_rising_edge, margin)

Object	Name	Dir.	Type	Description
signal	clk	in	std_logic	Clock signal
constant	num_rising_edge	in	natural	Number of rising edges of the clock to wait for
constant	margin	in	time	Time to wait after the rising edges of the clock

-- Examples:
wait_num_rising_edge_plus_margin(clk50M, 3, 4 ns);

wait_on_bfm_sync_start()

Synchronizes the start of a BFM procedure depending on the clock and bfm_sync.

wait_on_bfm_sync_start(clk, bfm_sync, setup_time, config_clock_period, time_of_falling_edge, time_of_rising_edge)

Object	Name	Dir.	Type	Description
signal	clk	in	std_logic	Clock signal
constant	bfm_sync	in	t_bfm_sync	SYNC_ON_CLOCK_ONLY: waits until the falling edge of the clk signal. SYNC_WITH_SETUP_AND_HOLD: waits until the setup time before the clock’s rising_edge
constant	setup_time	in	time	Setup time before the rising edge
constant	config_clock_period	in	time	Clock period
variable	time_of_falling_edge	out	time	Time of last the falling edge
variable	time_of_rising_edge	out	time	Time of last the rising edge. When not found, returns -1 ns.

-- Examples:
wait_on_bfm_sync_start(clk, config.bfm_sync, 2.5 ns, 10 ns, v_time_of_falling_edge, v_time_of_rising_edge);

wait_on_bfm_exit()

Synchronizes the exit of a BFM procedure depending on the clock and bfm_sync. The times of falling and rising edges must be consecutive to be able to calculate the correct clock period.

wait_on_bfm_exit(clk, bfm_sync, hold_time, time_of_falling_edge, time_of_rising_edge)

Object	Name	Dir.	Type	Description
signal	clk	in	std_logic	Clock signal
constant	bfm_sync	in	t_bfm_sync	SYNC_ON_CLOCK_ONLY: waits until one quarter of the clock period (measured with the falling and rising edges) after the clock’s rising_edge. SYNC_WITH_SETUP_AND_HOLD: waits until the hold time after the clock’s rising_edge.
constant	hold_time	in	time	Hold time after the rising edge
constant	time_of_falling_edge	in	time	Time of the last falling edge
constant	time_of_rising_edge	in	time	Time of the last rising edge

-- Examples:
wait_on_bfm_exit(clk, config.bfm_sync, 2.5 ns, v_time_of_falling_edge, v_time_of_rising_edge);

check_clock_period_margin()

Checks that the clock signal behaves according to configured specifications. Only when bfm_sync = SYNC_WITH_SETUP_AND_HOLD. The procedure must be called after the clock’s rising_edge.

check_clock_period_margin(clock, bfm_sync, time_of_falling_edge, time_of_rising_edge, config_clock_period, config_clock_period_margin, config_clock_margin_severity)

Object	Name	Dir.	Type	Description
signal	clock	in	std_logic	Clock signal
constant	bfm_sync	in	t_bfm_sync	Only SYNC_WITH_SETUP_AND_HOLD supported
constant	time_of_falling_edge	in	time	Time of the last falling edge
constant	time_of_rising_edge	in	time	Time of the last rising edge
constant	config_clock_period	in	time	Expected clock period
constant	config_clock_period_margin	in	time	Expected clock period margin
constant	config_clock_margin_severity	in	t_alert_level	Sets the severity for the alert when the clock period plus the margin is not followed. Default value is TB_ERROR.

-- Examples:
check_clock_period_margin(clk, config.bfm_sync, v_time_of_falling_edge, v_time_of_rising_edge, 10 ns, 2 ns, TB_ERROR);

General Watchdog

• The general watchdog will terminate with the alert_level when timeout expires.

• The VVCs support an activity watchdog. See Essential Mechanisms - Activity Watchdog for more details.

watchdog_timer()

Initializes the watchdog timer as a concurrent procedure that will run until the timeout expires. A signal of the type t_watchdog_ctrl must be defined in the testbench, this is needed to call the other procedures on the watchdog.

Note

This procedure has to be instantiated as a concurrent procedure in the testbench or test harness.

watchdog_timer(watchdog_ctrl, timeout, [alert_level, [msg]])

Object	Name	Dir.	Type	Description
signal	watchdog_ctrl	in	t_watchdog_ctrl	Signal controlling the watchdog timer
constant	timeout	in	time	Watchdog timeout
constant	alert_level	in	t_alert_level	Sets the severity for the alert when the watchdog timer expires. Default value is ERROR.
constant	msg	in	string	A custom message to be appended in the log/alert. Default value is “”.

-- Examples:
watchdog_timer(watchdog_ctrl, 500 us, ERROR, "Watchdog timer");

extend_watchdog()

Extends the timeout of the watchdog timer by the specified time. If no time is given, the original timeout will be used as the time extension.

extend_watchdog(extend_watchdog, [time_extend])

Object	Name	Dir.	Type	Description
signal	watchdog_ctrl	inout	t_watchdog_ctrl	Signal controlling the watchdog timer
constant	time_extend	in	time	Time to extend the watchdog timer. Default value is original timeout.

-- Examples:
extend_watchdog(watchdog_ctrl, 100 us);

reinitialize_watchdog()

Re-initializes the watchdog timer with a new timeout.

reinitialize_watchdog(watchdog_ctrl, timeout)

Object	Name	Dir.	Type	Description
signal	watchdog_ctrl	inout	t_watchdog_ctrl	Signal controlling the watchdog timer
constant	timeout	in	time	New watchdog timeout

-- Examples:
reinitialize_watchdog(watchdog_ctrl, 1 ms);

terminate_watchdog()

Terminates the concurrent procedure where the watchdog timer is running. Once this is done the watchdog can’t be started again. This should normally be called at the end of the simulation.

terminate_watchdog(watchdog_ctrl)

Object	Name	Dir.	Type	Description
signal	watchdog_ctrl	inout	t_watchdog_ctrl	Signal controlling the watchdog timer

-- Examples:
terminate_watchdog(watchdog_ctrl);

Types

• t_alert_level
• t_attention
• t_match_strictness
• t_format_spaces
• t_truncate_string
• t_radix
• t_radix_prefix
• t_ascii_allow
• t_blocking_mode
• t_format_zeros
• t_from_point_in_time
• t_log_destination
• t_log_format
• t_log_if_block_empty
• t_quietness
• t_identifier_option
• t_range_option
• t_vvc_select
• t_list_action
• t_bfm_sync
• t_bfm_delay_type
• t_inter_bfm_delay
• t_order
• t_flag_returning
• t_watchdog_ctrl
• t_alert_counters
• t_normalization_mode
• t_data_routing
• t_report_alert_counters
• t_report_sb
• t_report_vvc
• t_byte_endianness
• t_test_status
• t_extent_tickoff

Message IDs

The predefined message IDs are listed in the table below. All the message IDs are defined in adaptations_pkg.vhd

Message ID	Description
– Bitvis utility methods
NO_ID	Used as default prior to setting actual ID when transferring ID as a field in a record
ID_UTIL_BURIED	Used for buried log messages where msg and scope cannot be modified from outside
ID_BITVIS_DEBUG	Bitvis internal ID used for UVVM debugging
ID_UTIL_SETUP	Used for Utility setup
ID_LOG_MSG_CTRL	Dedicated ID for enable/disable_log_msg.
ID_ALERT_CTRL	Used inside Utility library only - when setting IGNORE or REGARD on various alerts.
ID_NEVER	Used for avoiding log entry. Cannot be enabled.
ID_FINISH_OR_STOP	Used when terminating the complete simulation - independent of why
ID_CLOCK_GEN	Used for logging when clock generators are enabled or disabled.
ID_GEN_PULSE	Used for logging when a gen_pulse procedure starts pulsing a signal.
ID_BLOCKING	Used for logging when using synchronization flags
ID_WATCHDOG	Used for logging the activity of the watchdog
ID_RAND_GEN	Used for logging “Enhanced Randomization” values returned by rand()randm()
ID_RAND_CONF	Used for logging “Enhanced Randomization” configuration changes, except from name and scope
ID_FUNC_COV_BINS	Used for logging functional coverage add_bins() and add_cross() methods
ID_FUNC_COV_BINS_INFO	Used for logging functional coverage add_bins() and add_cross() methods detailed information
ID_FUNC_COV_RAND	Used for logging functional coverage “Optimized Randomization” values returned by rand()
ID_FUNC_COV_SAMPLE	Used for logging functional coverage sampling
ID_FUNC_COV_CONFIG	Used for logging functional coverage configuration changes
– General
ID_POS_ACK	To write a positive acknowledge on a check
– Directly inside test sequencers
ID_LOG_HDR	For all test sequencer log headers. Special format with preceding empty line and underlined message (also applies to ID_LOG_HDR_LARGE and ID_LOG_HDR_XL).
ID_LOG_HDR_LARGE	For all test sequencer large log headers.
ID_LOG_HDR_XL	For all test sequencer extra large log headers.
ID_SEQUENCER	For all other test sequencer messages.
ID_SEQUENCER_SUB	For general purpose procedures defined inside TB and called from test sequencer.
– BFMs
ID_BFM	BFM operation (e.g. message that a write operation is completed) (BFM: Bus Functional Model, basically a procedure to handle a physical interface).
ID_BFM_WAIT	Typically BFM is waiting for response (e.g. waiting for ready, or predefined number of wait states).
ID_BFM_POLL	Used inside a BFM when polling until reading a given value, i.e., to show all reads until expected value found.
ID_BFM_POLL_SUMMARY	Used inside a BFM when showing the summary of data that has been received while waiting for expected data.
ID_CHANNEL_BFM	Used inside a BFM when the protocol is split into separate channels
ID_TERMINATE_CMD	Typically used inside a loop in a procedure to end the loop (e.g. for sbi_poll_until() or any looped generation of random stimuli
– Segment Ids, finest granularity of packet data
ID_SEGMENT_INITIATE	Notify that a segment is about to be transmitted or received
ID_SEGMENT_COMPLETE	Notify that a segment has been transmitted or received
ID_SEGMENT_HDR	Notify that a segment header has been transmitted or received. It also writes header info
ID_SEGMENT_DATA	Notify that a segment data has been transmitted or received. It also writes segment data
– Packet Ids, medium granularity of packet data
ID_PACKET_INITIATE	Notify that a packet is about to be transmitted or received
ID_PACKET_PREAMBLE	Notify that a packet preamble has been transmitted or received
ID_PACKET_COMPLETE	Notify that a packet has been transmitted or received
ID_PACKET_HDR	Notify that a packet header has been transmitted or received. It also writes header info
ID_PACKET_DATA	Notify that a packet data has been transmitted or received. It also writes packet data
ID_PACKET_CHECKSUM	Notify that a packet checksum has been transmitted or received
ID_PACKET_GAP	Notify that an inter-packet gap is in process
ID_PACKET_PAYLOAD	Notify that a packet payload has been transmitted or received
– Frame Ids, roughest granularity of packet data
ID_FRAME_INITIATE	Notify that a frame is about to be transmitted or received
ID_FRAME_COMPLETE	Notify that a frame has been transmitted or received
ID_FRAME_HDR	Notify that a frame header has been transmitted or received. It also writes header info
ID_FRAME_DATA	Notify that a frame data has been transmitted or received. It also writes frame data
– Distributed command systems
ID_UVVM_SEND_CMD	Logs the commands sent to the VVC
ID_UVVM_CMD_ACK	Logs the command’s ACKs or timeouts from the VVC
ID_UVVM_CMD_RESULT	Logs the fetched results from the VVC
ID_CMD_INTERPRETER	Message from VVC interpreter about correctly received and queued/issued command
ID_CMD_INTERPRETER_WAIT	Message from VVC interpreter that it is actively waiting for a command
ID_IMMEDIATE_CMD	Message from VVC interpreter that an IMMEDIATE command has been executed
ID_IMMEDIATE_CMD_WAIT	Message from VVC interpreter that an IMMEDIATE command is waiting for command to complete
ID_CMD_EXECUTOR	Message from VVC executor about correctly received command - prior to actual execution
ID_CMD_EXECUTOR_WAIT	Message from VVC executor that it is actively waiting for a command
ID_CHANNEL_EXECUTOR	Message from a channel specific VVC executor process
ID_CHANNEL_EXECUTOR_WAIT	Message from a channel specific VVC executor process that it is actively waiting for a command
ID_NEW_HVVC_CMD_SEQ	Message from a lower level VVC which receives a new command sequence from an HVVC
ID_INSERTED_DELAY	Message from VVC executor that it is waiting a given delay
– Await completion
ID_OLD_AWAIT_COMPLETION	Temporary log messages related to old await_completion mechanism. Will be removed in v3.0
ID_AWAIT_COMPLETION	Used for logging the procedure call waiting for completion
ID_AWAIT_COMPLETION_LIST	Used for logging modifications to the list of VVCs waiting for completion
ID_AWAIT_COMPLETION_WAIT	Used for logging when the procedure starts waiting for completion
ID_AWAIT_COMPLETION_END	Used for logging when the procedure has finished waiting for completion
– Distributed data
ID_UVVM_DATA_QUEUE	Information about UVVM data FIFO/stack (initialization, put, get, etc)
– VVC system
ID_CONSTRUCTOR	Constructor message from VVCs (or other components/process when needed)
ID_CONSTRUCTOR_SUB	Constructor message for lower level constructor messages (like Queue-information and other limitations)
ID_VVC_ACTIVITY
– Monitors
ID_MONITOR	General monitor information
ID_MONITOR_ERROR	General monitor errors
– SB package
ID_DATA	To write general handling of data
ID_CTRL	To write general control/config information
– Specification requirement coverage
ID_SPEC_COV_INIT	Used for logging specification requirement coverage initialization
ID_SPEC_COV_REQS	Used for logging the specification requirement list
ID_SPEC_COV	Used for logging general specification requirement coverage methods
– File handling
ID_FILE_OPEN_CLOSE	Id used when opening / closing file
ID_FILE_PARSER	Id used in file parsers
– Special purpose - Not really IDs
ALL_MESSAGES	Not an ID. Applies to all IDs (apart from ID_NEVER).

Message IDs are used for verbosity control in many of the procedures and functions in UVVM-Util, and are toggled by using the procedures enable_log_msg() and disable_log_msg().

Example: A check is performed each clock cycle

check_value(my_boolean_condition, error, "Verifying condition", C_SCOPE, ID_POS_ACK, my_msg_id_panel);

The message ID ‘ID_POS_ACK’ is enabled by default, and will report a positive acknowledge if the check passes. Since the check is performed each clock cycle, the positive acknowledge will be printed each clock cycle. There are two possibilities if you wish to turn off the positive acknowledge message:

• Disable ‘ID_POS_ACK’ in my_msg_id_panel (or use another msg_id_panel) by calling disable_log_msg(ID_POS_ACK, my_msg_id_panel). This will disable positive acknowledge messages for any procedure call that uses this msg_id_panel.

• Call check_value() with ‘ID_NEVER’ instead of ‘ID_POS_ACK’. This will disable the positive acknowledge for this particular call of check_value(), but all other calls to check_value() will report a positive acknowledge.

Using Hierarchical Alert Reporting

• Methods are defined in alert_hierarchy_pkg.vhd

• Enable hierarchical alerts via the constant C_ENABLE_HIERARCHICAL_ALERTS in the adaptations package.

• By default, there is only one level in the hierarchy tree, and one scope with name given by C_BASE_HIERARCHY_LEVEL in the adaptations package. This scope has a stop limit of 0 by default.

• To add a scope to the hierarchy, call add_to_alert_hierarchy().

• Any scope that is not registered in the hierarchy will be automatically registered if an alert is triggered in that scope. The parent scope will then be C_BASE_HIERARCHY_LEVEL. Changing the parent is possible by calling add_to_alert_hierarchy() with another scope as parent. This is only allowed if the parent is C_BASE_HIERARCHY_LEVEL and may cause an odd-looking summary (total summary will be correct).

Intended use:

In UVVM mostly use the scope to describe components, e.g. VVCs. It can also be smaller structures, but it has to have its own sequencer. A good way to set up the hierarchy is to let every scope register themselves with the default parent scope, and then in addition make every parent register each of its children. This is because the child scope doesn’t have to have the same parent scope in all testbenches/test-harnesses, i.e. the child doesn’t know its parent.

• In the child, call add_to_alert_hierarchy(<child scope>). This will add the scope of the child to the hierarchy with the default (base) parent.

• In the parent, first call add_to_alert_hierarchy(<parent scope>). Then call immediately add_to_alert_hierarchy(<child scope>, <parent scope>) for each of the scopes that shall be children of this parent scope. This will re-register the children to the correct parent.

Example output

Methods

TODO: procedure initialize_hierarchy( constant base_scope : string := C_BASE_HIERARCHY_LEVEL; constant stop_limit : t_alert_counters := (others => 0) );

add_to_alert_hierarchy()

Add a scope in the alert hierarchy tree.

add_to_alert_hierarchy(scope, [parent_scope, [stop_limit]])

Object	Name	Dir.	Type	Description
constant	scope	in	string
constant	parent_scope	in	string	Default value is C_BASE_HIERARCHY_LEVEL.
constant	stop_limit	in	t_alert_counters	Default value is (others => ‘0’).

-- Examples:
add_to_alert_hierarchy("tier_2", "tier_1");

TODO: procedure set_hierarchical_alert_top_level_stop_limit( constant alert_level : t_alert_level; constant value : natural );

TODO: impure function get_hierarchical_alert_top_level_stop_limit( constant alert_level : t_alert_level ) return natural;

TODO: procedure hierarchical_alert( constant alert_level: t_alert_level; constant msg : string; constant scope : string; constant attention : t_attention );

increment_expected_alerts()

Increment the expected alert counter for a scope.

increment_expected_alerts(scope, alert_level, [amount])

Object	Name	Dir.	Type	Description
constant	scope	in	string
constant	alert_level	in	t_alert_level
constant	amount	in	natural	Default value is 1.

-- Examples:
increment_expected_alerts("tier_2", ERROR, 2);

amount

1

set_expected_alerts()

Set the expected alert counter for a scope.

set_expected_alerts(scope, alert_level, expected_alerts)

Object	Name	Dir.	Type	Description
constant	scope	in	string
constant	alert_level	in	t_alert_level
constant	expected_alerts	in	natural

-- Examples:
set_expected_alerts("tier_2", WARNING, 5);

increment_stop_limit()

Increment the stop limit for a scope.

increment_stop_limit(scope, alert_level, [amount])

Object	Name	Dir.	Type	Description
constant	scope	in	string
constant	alert_level	in	t_alert_level
constant	amount	in	natural	Default value is 1.

-- Examples:
increment_stop_limit("tier_1", ERROR);

set_stop_limit()

Set the stop limit for a scope.

increment_stop_limit(scope, alert_level, stop_limit)

Object	Name	Dir.	Type	Description
constant	scope	in	string
constant	alert_level	in	t_alert_level
constant	stop_limit	in	natural

-- Examples:
set_stop_limit("tier_1", ERROR, 5);

TODO: procedure print_hierarchical_log( constant order : t_order := FINAL );

TODO: procedure clear_hierarchy( constant VOID : t_void );

Adaptations package

The adaptations_pkg.vhd is intended for local modifications to library behavior and log layout. This way only one file needs to merge when a new version of the library is released. This package may of course also be used to set up a company or project specific behavior and layout.

The package has constants for customizing functionality such as:

• setting the alert and log files names

• removing UVVM initial and release info printed in simulation

• log format, e.g.: log prefix, log widths, scope default value

• message ids

• verbosity control, e.g.: default log msg ID, default message ID panel, default message ID indentation

• alert counters, e.g.: default alert attention, default stop limit

• hierarchical alerts, e.g.: enabling hierarchical alerts

• synchronization, e.g.: maximum sync flags

• enhanced randomization, e.g.: initial randomization seeds

• functional coverage, e.g.: maximum number of coverpoints

• VVC framework, e.g.: maximum number of VVC instances

• scoreboard, e.g.: maximum number of SB instances

• hierarchical VVCs, e.g.: supported interfaces

• CRC

Global signal	Type	Description
global_show_msg_for_uvvm_cmd	boolean	If true, the msg parameter for the commands using the msg_id ID_UVVM_SEND_CMD will be shown

Global variable	Type	Description
shared_default_log_destination	t_log_destination	The default destination for the log messages (Default: CONSOLE_AND_LOG)

Additional Documentation

There are two other main documents for the UVVM Utility Library:

• Making a simple, structured and efficient VHDL testbench – Step-by-step (PPT)

• UVVM Utility Library – Concepts and Usage (PPT)

There is also a webinar available on ‘Making a simple, structured and efficient VHDL testbench – Step-by-step’ (via Aldec [2])

Compilation

The UVVM Utility Library must be compiled with VHDL-2008 or newer.

Compile order for the UVVM Utility Library

Compile to library	File
uvvm_util	uvvm_util/src/types_pkg.vhd
uvvm_util	uvvm_util/src/adaptations_pkg.vhd
uvvm_util	uvvm_util/src/string_methods_pkg.vhd
uvvm_util	uvvm_util/src/protected_types_pkg.vhd
uvvm_util	uvvm_util/src/global_signals_and_shared_variables_pkg.vhd
uvvm_util	uvvm_util/src/hierarchy_linked_list_pkg.vhd
uvvm_util	uvvm_util/src/alert_hierarchy_pkg.vhd
uvvm_util	uvvm_util/src/license_pkg.vhd
uvvm_util	uvvm_util/src/methods_pkg.vhd
uvvm_util	uvvm_util/src/bfm_common_pkg.vhd
uvvm_util	uvvm_util/src/generic_queue_pkg.vhd
uvvm_util	uvvm_util/src/data_queue_pkg.vhd
uvvm_util	uvvm_util/src/data_fifo_pkg.vhd
uvvm_util	uvvm_util/src/data_stack_pkg.vhd
uvvm_util	uvvm_util/src/rand_pkg.vhd
uvvm_util	uvvm_util/src/func_cov_pkg.vhd
uvvm_util	uvvm_util/src/uvvm_util_context.vhd

Note

Modelsim and Riviera-PRO users can compile the library by sourcing the following file: script/compile_src.do.

Suppressed warnings

The compile script compiles the Utility Library with the following directives for the vcom command to suppress warnings about the use of protected types and interface objects not being globally static. These can be ignored.

• Modelsim: -suppress 1346,1236

• Riviera-PRO: -nowarn COMP96_0564 -nowarn COMP96_0048

Simulator compatibility and setup

• See Prerequisites for a list of supported simulators.

Required setup:

• Textio buffering should be removed or reduced. (Modelsim.ini: Set UnbufferedOutput to 1)

• Simulator transcript (and log file viewer) should be set to a fixed width font type for proper alignment (e.g. Courier New 8)

• Simulator must be set up to break the simulation on failure (or lower severity)

Note

Disclaimer: This IP and any part thereof are provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with this IP.

Footnotes

[1] (1,2)

IEEE = Method is native for VHDL-2008 (method is listed here for completeness).

[2]

https://www.aldec.com/en/support/resources/multimedia/webinars/1673