Language Change Specification for API for Assert

LCS Number:	LCS-2016-050
Version:	6
Date:	24-Mar-2017
Status:	Voting
Author:	Jim Lewis Patrick Lehmann Martin Zabel
Email:	Main.JimLewis
Source Doc:	API for Assert
More Doc:	history
GitLab Branch:	LCS2016-050-Assert-API
Summary:	API for Assert

Style Notes

Changes are shown in red font. Deletions are crossed out. Editing notes in green font.

Reviewing Notes

This LCS only intends to implement the basic features of the proposal. If an extended or advanced feature of the proposal is to be implemented, it should be implemented by a separate LCS and voted on separately.

Details of Language Change

Section 16.5 Standard environment package

[050.1: Add the following subprograms to package std.env on page 275 before "end package ENV;"]

-- VHDL Assert Failed
impure function IsVhdlAssertFailed return boolean ; 
impure function IsVhdlAssertFailed (Level : SEVERITY_LEVEL ) return boolean ; 

-- VHDL Assert Count
impure function GetVhdlAssertCount return natural ; 
impure function GetVhdlAssertCount (Level : SEVERITY_LEVEL ) return natural ; 

--  Clear VHDL Assert Errors
procedure ClearVhdlAssert; 

-- Assert Enable, Disable/Ignore Asserts 
procedure SetVhdlAssertEnable(Enable : boolean := TRUE) ;
procedure SetVhdlAssertEnable(Level : SEVERITY_LEVEL := NOTE; Enable : boolean := TRUE) ; 
impure function GetVhdlAssertEnable(Level : SEVERITY_LEVEL := NOTE) return boolean ; 

--  Assert statement formatting
procedure SetVhdlAssertFormat(Level : SEVERITY_LEVEL; format: string) ;
procedure SetVhdlAssertFormat(Level : SEVERITY_LEVEL; format: string; Valid : out boolean) ;
impure function GetVhdlAssertFormat(Level : SEVERITY_LEVEL) return string ; 

--  VHDL Read Severity
procedure SetVhdlReadSeverity(Level: SEVERITY_LEVEL := FAILURE) ; 
impure function GetVhdlReadSeverity return SEVERITY_LEVEL ;

[050.2: New paragraphs before Notes on page 275]

An API to collected information on report and assert statements is provided. Information is collected per severity level (FAILURE, ERROR, WARNING, or NOTE) and can be enabled and disabled per severity level.

The procedure SetVhdlAssertEnable enables asserts for the the corresponding SEVERITY_LEVEL when the parameter enable is TRUE. A value of FALSE disables the corresponding severity level. Unless overridden by tool settings, after elaboration of a design, all severity levels are enabled. When called without a severity level parameter, SetVhdlAssertEnable applies the enable to all SEVERITY_LEVEL values.

The function GetVhdlAssertEnable returns the enable state of the passed severity level.

When called without any parameters, the function IsVhdlAssertFailed returns TRUE if any VHDL assert or report statement was triggered to report a severity level of either FAILURE, ERROR, or WARNING. IsVhdlAssertFailed includes the implied asserts due to read statements in std.textio. When called with a parameter of FAILURE, ERROR, or WARNING, the function IsVhdlAssertFailed returns TRUE when a VHDL assert or report statement with the corresponding severity level was triggered. At the start of elaboration of a design, IsVhdlAssertFailed returns FALSE.

When called without any parameters, the function GetVhdlAssertCount returns the number of triggered VHDL assert or report statements, whose SEVERITY_LEVEL was either FAILURE, ERROR, or WARNING. GetVhdlAssertCount includes the implied asserts due to read statements in std.textio. When called with a parameter of FAILURE, ERROR, or WARNING, the function GetVhdlAssertCount returns the number of triggered VHDL assert or report statements with the corresponding severity level. At the start of elaboration of a design, GetVhdlAssertCount returns 0.

The procedure ClearVhdlAssert clears any state of collected information of VHDL assert and report statements having been executed. After calling ClearVhdlAssert, IsVhdlAssertFailed will return FALSE and GetVhdlAssertFailed will return 0. This allows a VHDL testbench to clear alerts after reset or between tests.

The procedure SetVhdlAssertFormat sets the format string for an assert or report statement with a given severity level. The format string may contain string replacements extending from a singular left curly bracket to the next right curly bracket. These brackets delimit the name of a format variable with an optionally following colon and format specification string. The string replacement contains no whitespace except if the optional fill character is a whitespace character. If the format string does not meet the following syntax rules, then the operation has no effect, i.e. the previous format string is kept; in this case the procedure SetVhdlAssertFormat with 2 parameters reports a failure using the previous format string. The procedure SetVhdlAssertFormat with 3 parameters returns via the boolean parameter Valid whether the format string was valid (TRUE) or not (FALSE).

Syntax rules

string_replacement   ::= "{" variable [format_specification] "}"
format_specification ::= ":" [ [fill] align] [width] ["." precision]
variable             ::= "s" | "S" | "r" | "t" | "i"
fill                 ::= graphic_character
align                ::= "<" | ">" | "^"
precision            ::= "fs" | "ps" | "ns" | "us" | "ms" | "sec" | "min" | "hr"

Case sensitive format variables:

• "s" - Severity level converted to a string in lower case.
• "S" - Severity level converted to a string in upper case.
• "r" - Message string from report or assert statement.
• "t" - Time converted to a string at which the report or assert statement was triggered.
• "i" - The instance path from where assert/report was called.

The format specification consists of an optional alignment character, an optional width (integer number) and an optional precision. The alignment character can be preceeded by an optional fill character. The precision can only be applied to the t variable. It is delimited by a dot and its value is the string representation of a secondary unit of type TIME.

Allowed alignment characters are:

• '<' - Forces the field to be left-aligned within the available space. This is the default for variables s, S, r and i.
• '>' - Forces the field to be right-aligned within the available space. This is the default for variable t.
• '^' - Forces the field to be centered within the available space.

The default fill character is space. Doubled left curly brackets do not introduce string replacements but translate to single left curly brackets in the derived formatted output.

The default assert and report format string is implementation defined. Not all of the formatting specifiers need to be used. Additional vendor specific formatting extensions are permitted. The LF character can be used to create multiline outputs.

The function GetVhdlAssertFormat returns the format string of the specified severity level.

The procedure SetVhdlReadSeverity sets the severity level for VHDL read statements. The function GetVhdlReadSeverity returns the severity level of VHDL read statements. The default value is ERROR.

Example:
The following call to SetVhdlAssertFormat specifies that assert/report print the output using a single line.

    SetVhdlAssertFormat("** {S}: {r: <10} at {t.ns}    in: {i}") ;
    report "Yikes!" severity failure ;

Creates the following output:

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

Comments