(r6) AssertApi < P1076/Ballots

P1076/Ballots Web>Vhdl2019CollectedRequirements>AssertApi (revision 6) (raw view)~~EditAttach~~
---+ API for VHDL Assert Statements

<br />%TOC%

---++ Proposal Editing Information
   * Who Updates: Main.JimLewis, &lt;Add YourName &gt;, ...
   * Date Proposed: 2012-08-17
   * Date Last Updated: 2012-08-17
   * Priority:
   * Complexity:
   * Focus: Testbench
   * Proposal Maturity: Brainstorming
---++ 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.

---++ Related Issues: PSL Attributes

Will want to keep API consistent.

---++ Proposal

---+++ Assert Attributes

Suggested to keep a strong correspondence with VHDL ASSERT with PSL ASSERT. May not be necessary since there are other ways to program this functionality. Requires the assert to have a statement label.

---++++ A'TRANSACTION

The intent is to be able to trigger a process when a labeled VHDL assert evalutates to true.
<pre>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. 
</pre>

---++++ A'EVENT

If multiple different VHDL ASSERT statements trigger a process, this one allows us to detect which one triggered the process
<pre>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.
</pre>

---++++ A'COUNT

Allows a count of specific VHDL assert statement to be accessed.
<pre>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.
</pre>

---+++ ASSERT API - Predefined Functions

?? replace level with an array of level values?

Add turn on/off printing of the severity_level value

The following is preliminary ideas on a control interface for VHDL ASSERT statements.

type HIER_LEVEL_TYPE is (CURRENT, BELOW) ;

HIER parameter specifies if the command applies the the current level of hierarchy or current level plus below.

PATH parameter specifies the path in a consistent manner with external name specifications.

---++++ ASSERT_IGNORE

procedure ASSERT_IGNORE(LEVEL : SEVERITY_LEVEL := NOTE; PATH : STRING := "/" ; HIER : HIER_LEVEL_TYPE := BELOW) ;

Enables VHDL ASSERT statements within the scope of path.

Intent: Give VHDL control to which assertions print and which get ignored.

---++++ ASSERT_ENABLE

procedure ASSERT_ENABLE(LEVEL : SEVERITY_LEVEL := NOTE; PATH : STRING := "."; HIER : HIER_LEVEL_TYPE := CURRENT) ;

Enables VHDL ASSERT statements within the scope of path.

Intent: Turn assertions on - such as after the design enters reset.

---++++ ASSERT_DISABLE

procedure ASSERT_DISABLE(LEVEL : SEVERITY_LEVEL := NOTE; PATH : STRING := "/"; HIER : HIER_LEVEL_TYPE := BELOW) ;

Disables VHDL ASSERT statements within the scope of path.

Intent: Turn assertions off - such as before the design enters reset.

---++++ ASSERT_STOP

procedure ASSERT_STOP(LEVEL : SEVERITY_LEVEL := ERROR; PATH : STRING := "/" ; HIER : HIER_LEVEL_TYPE := BELOW) ;

Enables VHDL ASSERT statements within the scope of path.

Intent: Give VHDL control to which assertions cause a simulation to stop. Default level in the language is failure. Allows it to be set for the entire design or a specific design.

---++++ READ_STOP

procedure READ_STOP(ENABLE : Boolean := TRUE ; PATH : STRING := "/" ; HIER : HIER_LEVEL_TYPE := BELOW) ;

Intent: Give VHDL control to what happens during a textio read error. Language currently reports the error and continues with an invalid read value. READ_STOP 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).

---++++ ASSERT_FORMAT

procedure ASSERT_FORMAT(format : string) ; procedure ASSERT_FORMAT(severity : severity_level; format: string) ;

String parameter designates format of assertion. For example (inspired by: [[http://www.tkt.cs.tut.fi/kurssit/1212/K13/Kalvot/lect_7_testbench_k13_v01.pdf][inspired by slide 44]]): 
<verbatim>ASSERT_FORMAT("** %S: %R" & LF & "  Time: %T Iteration: %D Instance: %I");
...
report "Yikes!" severity failure ;</verbatim>

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

The following modifies the output to one line:
<verbatim>ASSERT_FORMAT("** %S: %R    at %T    in: %I");
...
report "Yikes!" severity failure ;</verbatim>

Creates something similar to simulator defaults:
<verbatim>** FAILURE: Yikes!    at 217600 ns    in: /tb_top</verbatim>

---++++ ASSERT_TOTAL_COUNT

function ASSERT_TOTAL_COUNT(LEVEL : SEVERITY_LEVEL := NOTE; PATH : STRING := ".") return natural;

Returns the total number of times VHDL assert statements triggered during a simulation.

Intent: Effectively an error count value due to assert statements.

---++++ ASSERT_COUNT

function ASSERT_COUNT(LEVEL : SEVERITY_LEVEL := NOTE; PATH : STRING := ".") return natural;

Returns the number of VHDL assert statements that have triggered at least once during a simulation

Intent: When Coupled with ASSERT_GET_NAME enables identification of all assertions that have triggered during this simulation.

---++++ ASSERT_GET_NAME

function ASSERT_GET_NAME(LEVEL : SEVERITY_LEVEL := NOTE; N : INTEGER := 1 ; PATH : STRING := ".") return natural;

Returns the string value of the label of the N'th PSL assert statement whose a count greater than the 0. The PATH parameter specifies the path of the design.

Intent: When Coupled with ASSERT_COUNT enables identification of all assertions that have triggered during this simulation.
---+++ Use Models

---++ Questions

Enable/Disable functionality - one procedure with parameters or two procedures

Enable/Disable functionality - how to handle hierarchy below the current level?

---++ 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
<verbatim>function get_assert_count(sev : severity_level := WARNING) return natural;</verbatim>

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

-- Main.RobGaddi - 2016-03-31<br /><br />
---++ Supporters

_Add your signature here to indicate your support for the proposal_

_-- Main.JimLewis - 2014-12-04_
Topic revision: r1 - 2020-02-17 - 15:34:49 - TWikiGuest
P1076/Ballots