LCS2016_050 < P1076

P1076 Web>VHDL2017>LCS2016_050 (2017-07-16, JimLewis) (raw view)EditAttach
---+ Language Change Specification for API for Assert
---++ 

| <sticky><b>LCS Number:</b>    </sticky> | LCS-2016-050 |
| <sticky><b>Version:</b>       </sticky> | 6 |
| <sticky><b>Date:</b>          </sticky> | 24-Mar-2017  |
| <sticky><b>Status:</b>        </sticky> | Voting |
| <sticky><b>Author:</b>        </sticky> | Jim Lewis %BR% Patrick Lehmann %BR% Martin Zabel |
| <sticky><b>Email:</b>         </sticky> | [[Main.JimLewis]] |
| <sticky><b>Source Doc:</b>    </sticky> | [[AssertApi][API for Assert]] |
| <sticky><b>More Doc:</b>    </sticky> | [[LCS2016_050_history][history]] |
| <sticky><b>GitLab Branch:</b> </sticky> | [[https://gitlab.com/IEEE-P1076/Packages/tree/JimLewis/LCS2016-050-Assert-API][LCS2016-050-Assert-API]] |
| <sticky><b>Summary:</b>       </sticky> | API for Assert |


---++ Style Notes

<noautolink>

<sticky>
Changes are shown in %RED%red font%ENDCOLOR%.  
Deletions are %RED%<del>crossed out</del>%ENDCOLOR%. 
Editing notes in %GREEN%green font%ENDCOLOR%. 
 
---++ 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
%GREEN%[050.1:  Add the following subprograms to package std.env on page 275 before "end package ENV;"]%ENDCOLOR%
<pre>
%RED%
-- 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 ;
%ENDCOLOR%
</pre>


%GREEN%[050.2:  New paragraphs before Notes on page 275]%ENDCOLOR%

%RED%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.%ENDCOLOR%

%RED%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.%ENDCOLOR%

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

%RED%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.%ENDCOLOR%

%RED%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.
%ENDCOLOR%

%RED%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.%ENDCOLOR%

%RED%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).%ENDCOLOR%

%RED%<b>Syntax rules</b>%ENDCOLOR%<pre>%RED%
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"
%ENDCOLOR%</pre>

%RED%Case sensitive format variables:%ENDCOLOR%
   * %RED%"s" - Severity level converted to a string in lower case.%ENDCOLOR%
   * %RED%"S" - Severity level converted to a string in upper case.%ENDCOLOR%
   * %RED%"r" - Message string from report or assert statement.%ENDCOLOR%
   * %RED%"t" - Time converted to a string at which the report or assert statement
    was triggered.%ENDCOLOR%
   * %RED%"i" - The instance path from where assert/report was called.%ENDCOLOR%


%RED%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.%ENDCOLOR%

%RED%Allowed alignment characters are:%ENDCOLOR%
   * %RED%'<' - Forces the field to be left-aligned within the available space. This is
    the default for variables s, S, r and i.%ENDCOLOR%
   * %RED%'>' - Forces the field to be right-aligned within the available space. This is
    the default for variable t.%ENDCOLOR%
   * %RED%'^' - Forces the field to be centered within the available space.%ENDCOLOR%

%RED%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.%ENDCOLOR%

%RED%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.%ENDCOLOR%

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

%RED% 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.%ENDCOLOR%


%RED%<b>Example:</b> %BR%
The following call to SetVhdlAssertFormat specifies that assert/report print the
output using a single line.%ENDCOLOR%
<pre>%RED%
    SetVhdlAssertFormat("** {S}: {r: <10} at {t.ns}    in: {i}") ;
    report "Yikes!" severity failure ;
%ENDCOLOR%</pre>

%RED%Creates the following output:%ENDCOLOR%
<pre>%RED%** FAILURE: Yikes!     at 217600 ns    in: /tb_top%ENDCOLOR%</pre>


%BR%
%BR%
---++ Comments 

%COMMENT%</sticky>

</noautolink>
Topic revision: r31 - 2017-07-16 - 15:35:46 - JimLewis
P1076