API for VHDL Assert Statements

Proposal Editing Information

• Who Updates: JimLewis, <Add YourName >, ...
• Date Proposed: 2012-08-17
• Date Last Updated: 2016-Dec-29
• Priority:
• Complexity:
• Focus: Testbench
• Proposal Maturity: Finalizing for LCS

Requirement Summary

Add subprograms and attributes for VHDL assert statements that allow enabling/disabling assert statements as well as getting a count of assert statements

Rationale

Feedback for testbench usage.

There are numerous Alert capabilities in open source packages that are a replacement for assert. What we need here is a basic ability. For more advanced capability, one can use one of the open source Alert packages.

Related Issues: PSL Attributes

Keep consistent with PSL API.

Proposal

Basic ASSERT API - std.env

VHDL Assert Failed

impure function VhdlAssertFailed return boolean ; 
impure function VhdlAssertFailed (Severity : SEVERITY_LEVEL ) return boolean ; 

When called without any parameters, VhdlAssertFailed returns TRUE if any VHDL assert or report statement reported a severity whose severity_level was either FAILURE, ERROR, or WARNING. VhdlAssertFailed includes the implied asserts due to read statements in std.textio. When called with a parameter of FAILURE, ERROR, or WARNING, a return value of TRUE indicates that a VHDL assert statement with the corresponding severity level was reported.

Clear VHDL Assert Errors

procedure ClearVhdlAssert return boolean ; 

Clears any sense of VHDL Assert having been executed. After calling ClearVhdlAssert, VhdlAssertFailed will return FALSE. Allows a VHDL testbench to clear alerts after reset or between tests.

Assert Enable, Disable/Ignore Asserts

procedure SetAssertEnable(Severity : SEVERITY_LEVEL := NOTE; Enable : boolean := TRUE) ; 
impure function GetAssertEnable(Severity : SEVERITY_LEVEL := NOTE) return boolean ; 

When Enable is TRUE, enable the corresponding severity level. When Enable is FALSE, disable the corresponding severity level.

Assert statement formatting

procedure SetAssertFormat(format : string) ; 
procedure SetAssertFormat(severity : severity_level; format: string) ;
impure function GetAssertFormat retrun string ; 
impure function GetAssertFormat(severity : severity_level) return string ;

String parameter designates format of assertion. For example (inspired by: inspired by slide 44):

SetAssertFormat("** %S: %R" & LF & "  Time: %T Iteration: %D Instance: %I");
...
report "Yikes!" severity failure ;

Creates something similar to simulator defaults:
** FAILURE: Yikes!
    Time: 217600 ns Iteration: 0 Instance: /tb_top

The following modifies the output to one line:

SetAssertFormat("** %S: %R    at %T    in: %I");
...
report "Yikes!" severity failure ;

Creates something similar to simulator defaults:

** FAILURE: Yikes!    at 217600 ns    in: /tb_top

VHDL Read Severity

procedure SetVhdlReadSeverity(Severity: severity_level := FAILURE) ; 
impure function GetVhdlReadSeverity return severity_level ; 

Sets the severity level for VHDL read statements.

Extended ASSERT API - std.env

Assert Stop Count

procedure SetAssertStopCount(Severity : SEVERITY_LEVEL := FAILURE; Count : integer := integer'right) ; 
impure function GetAssertStopCount(Severity : SEVERITY_LEVEL := FAILURE) return integer ; 

Count sets the number of the corresponding asserts can happen before the simulation stops.

Getting the Assert Count

impure function GetAssertCount return AssertCountType ;
impure function GetAssertCount return integer ;
impure function GetAssertCount (severity : severity_level) return natural;

type AssertCountType is array (SEVERITY_LEVEL) of integer ; 

Returns the number of times VHDL assert statements have triggered during a simulation. Generally a count of 1 indicates a test has failed.

Read Stop Count

procedure SetReadStopCount(Count : integer := 0) ; 
impure function GetReadStopCount return integer ; 

Count sets the number of the corresponding unhandled read errors (read procedure without a valid boolean parameter) can occur before the simulation stops.

Defaults to integer'right (makes behavior consistent with current language)

Intent: Give VHDL control to what happens during a textio read error. Language currently reports the error and continues with an invalid read value. SetReadStopCount with defaults will cause unhandled texio read errors (those generated by the read procedure with two parameters) will cause the simulator to stop (like std.env.stop).

Get Read Error Count

impure function GetReadErrorCount return integer;

Returns the number of times VHDL read statements have generated an unhandled error during a simulation. Generally a count of 1 indicates a test has failed.

Advanced Capability

While advanced capability is needed in the PSL API, the same does not apply to the VHDL API. Unless the VHDL community decided to significantly expand the capability of VHDL Asserts, it is better to use one of the open source Alert/Log packages. Going further, since these packages do exist, it is not worth the investment of the community to recreate them inside the language.

Assert Attributes

Proposed to keep a strong correspondance between VHDL Assert and PSL Assert. For VHDL, there are other ways to do this, so this attributes are not as important.

A'TRANSACTION

The intent is to be able to trigger a process when a labeled VHDL assert evalutates to true.

Kind: Signal.
Prefix: A VHDL assert statement with the static label A.
Result type: Type BIT. 
Result: A signal whose value toggles to the inverse of its previous value in each 
simulation cycle in which a VHDL assert statement is true. 
Restrictions: A description is erroneous if it depends on the initial value of A'TRANSACTION. 

A'EVENT

If multiple different VHDL ASSERT statements trigger a process, this one allows us to detect which one triggered the process

Kind: Function.
Prefix: A VHDL assert statement with the static label A. 
Result type: Type BOOLEAN.
Result: A value TRUE during each simulation cycle in which a VHDL assert statement is true.

A'COUNT

Allows a count of specific VHDL assert statement to be accessed.

Kind: Function.
Prefix: A VHDL assert statement with the static label A. 
Result type: Type INTEGER.
Result: The number of times a VHDL assert statement evaluated to true.

Hierarchy control

type HIER_LEVEL_TYPE is (CURRENT, BELOW) ; 

HIER_LEVEL_TYPE specifies if the command applies the the current level of hierarchy or current level plus below. PATH is a string based value that specifies the path in a consistent manner with external name specifications.

Assert Enable, Disable/Ignore Asserts

procedure SetAssertEnable(
    Severity : SEVERITY_LEVEL := NOTE; 
    Path : string := ".";
    Hier : string :=HIER_LEVEL_TYPE := ALL ;  
    Enable : boolean := TRUE
) ; 

Enable/disable paths such as ieee.numeric_std.

General Comments

Need a way to count and disable errors generated by testbenches so we can produce pass/fail messages when a test completes. How about just in std.env we put

function get_assert_count(sev : severity_level := WARNING) return natural;

That would report the number of any counts of level "sev" or above of any 1) failed asserts or 2) reports.

-- RobGaddi - 2016-03-31

Supporters

Add your signature here to indicate your support for the proposal -- JimLewis - 2014-12-04