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

Voting Results: Cast your votes here

Yes:

1. Jim Lewis - 2017-02-06 - ver 3
2. Rob Gaddi - 2017-02-08 - ver 3
3. Torsten Meissner - 2017-02-15 - ver 3
4. Martin Thompson- 2017-02-17 ver 3
5. Martin Zabel - 2017-03-07 - ver 5
6. Patrick Lehmann - 2017-01-03 - ver 5
7. Thomas Preusser - 2017-03-07 - ver 5
8. Steve Grout- 2017-03-07 - ver 5
9. Peter Flake - 2017-03-09 - ver 5 - see comment

No:

Abstain:

1. Brent Hayhoe - 2017-02-16 Version 3 - Abstain due to lack of personal time for review.

Revision Notes

Revision 6: 24-Mar-2017

• Changed Severity to Level

Revision 5: 06-Mar-2017

• Removed trailing "}" sign from EBNF.
• Applied text changes as provided by Thomas

Revision 4: 28-Feb-2017

• If an invalid format string is specified in the call of SetVhdlAssertFormat, then the previous format string is kept and either a failure is reported or a boolean flag is set.

Revision 3: 06-Feb-2017

• Added text: When called without a Severity parameter, SetVhdlAssertEnable applies the enable to all SEVERITY_LEVEL values
• Changed GetVhdlAssertFailed to GetVhdlAssertCount

Revision 2: 03-Jan-2017

Revision 1: 29-Dec-2016

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.

Comments

What about VHDL's write and open statements?

-- Patrick Lehmann - 2016-12-31

The proposed format option miss an escape sign for "%", which is usually "%%". You should also specify the format %S is it: "Warning", "WARNING" or "warning" or the result of SEVERITY'image(x)? Should it support a short form e.g. "%s" for "F" (failure), "E" (error), "W" (warning), "N" (note), or should %s vs. %S denote the casing: warning / WARNING? %T specifies the time. Most formatted outputs break because simulators use different length for the time value. E.g. 500 ns, 900 ns 1 us, 1.100 ns. This brings us to fill characters and justification. I would prefer the newer escape patterns like used by Python, .NET, .... They use {var:rules}. {time: >10} formats time, fills with spaces, the justification is right and the minimum length is 10. See e.g. https://docs.python.org/3.4/library/string.html#formatspec

-- Patrick Lehmann - 2016-12-31

Looks good in general.

Please, fix consistency details:

• Try to adhere to the coding style of existing library code. Even the proposed additions use inconsistent capitalization SEVERITY_LEVEL vs. severity_level, Severity vs. severity. Indeed, you should not use severity at all for argument names as it is a reserved word.
• Why do we have GetVhdlAssertCount but only GetAssertEnable?
• In VHDL, characters come in single quotes. Double quoted characters are strings of length one.
• The format variables are suddenly all capitalized when referenced in the default alignment specification.
• The sentence "The replacement string contains no whitespace except if the optional fill character is a whitespace character." does not seem to get it right for usual time representations and, in fact, not even for the one used in your example. It certainly fails for many report messages as well. You might want to state that the replacement is not padded in any way unless an oversized replacement width is specified. What is to happen when a specified width is too small? Will the replacement be truncated or not?
• Vendor-specific format extensions are not necessarily a good idea as they encourage code that requires explicit porting effort. If supported at all, tools should be required to behave well when a non-standard format variable is either not known or its replacement string appears to be ill-formed. E.g., they might be required to ignore them totally.

Some typos:

• Information (are -> is) collected ...
• ... all severity level[s] are enabled.
• sets the format for a[n] assert or report statement
• format{able} variable
• The (formatable object -> format variable) can be followed by an optional (":" -> ':') character
• doubl{e}ing

-- Thomas Preusser - 2017-01-03

@Thomas While adding the format specifications, I didn't review the existing code nor the proposal, which already contains faulty VHDL code. I'll rework this as soon as I have finished other LCS' on my list.

The TWiki history shows that several user added functions and procedures with different coding styles.

I also search for current references to delimiter signs: The current LRM doesn't use e.g. ":" it uses colon. I'll change all character references to explicit character names. Variables are not restricted to single characters.

"replacement string" should be "string replacement". Because of VHDL own interpretation of (E)BNF syntax, a special rule is required to exclude all whitespaces introduced by edges in a corresponding railroad diagram.

-- Patrick Lehmann - 2017-01-03

Thanks for the updates.

TBP#1: Yes, I misread this replacement string / string replacement to be the replacement. What you mean is the format specification. Maybe, you can change your terminology to be clearer.

TBP#2: The statement "The curly bracket characters can be escaped by doubling the same." is too vague. In fact, literal opening braces need to be doubled in a format string in order not to be mistaken to introduce a format specification. Requiring literal closing braces to be doubled creates an undefined situation when a single closing brace is encountered outside of a format specification. Either this becomes an error or closing braces are simply classified by context without doubling. The latter approach might make it difficult to come up with a syntax to allow a closing brace as a fill character. It is also not obvious whether specifying a literal opening brace as a fill character should require doubling or not.

TBP#3: As formats may be malformed, the response on an error should be defined. Possible approaches are:

• Ignore and leave out faulty format specifications.
• Copy faulty format specifications literally to the produced output.
• Raise an error (of a configurable severity level?) when setting a faulty format, and optionally fall back to a default format.
• Produce an error (of a configurable severity level?) when using a faulty format, and optionally fall back to a default format.

-- Thomas Preusser - 2017-01-04

Can you call these subprograms during elaboration ?

-- Tristan Gingold - 2017-01-09

They was not the intent. However, if we want that, we may want function forms of set so they can be called directly in a declaration.

-- Jim Lewis - 2017-01-09

I think the LCS is incomplete:

• What is returned by GetVhdlAssertCount with and without the parameter?
• What is done by the procedure SetVhdlAssertEnable with just one parameter?

-- Martin Zabel - 2017-01-23

@MZ.1 Without a severity parameter, GetVhdlAssertCount gets the total count for WARNING, ERROR, and FAILURE. With a severity parameter, it returns the count for the specified severity value. This is fixed in Version 3. It was simply a naming issue, I changed GetVhdlAssertFailed to GetVhdlAssertCount

@MZ.2 Without a severity parameter, SetVhdlAssertEnable applies the Enable parameter to either enable or disable all severity flags. With a severity parameter, SetVhdlAssertEnable applies the Enable parameter to either enable or disable the specified severity value.

This is fixed in version 3. I added the final sentence to the paragraph on SetVhdlAssertEnable:
When called without a Severity parameter, SetVhdlAssertEnable applies the enable to all SEVERITY_LEVEL values

-- Jim Lewis - 2017-02-07

So, to be clear, GetVhdlAssertCount GetVhdlAssertCount(WARNING) + GetVhdlAssertCount(ERROR) + GetVhdlAssertCount(FAILURE)=, IsAssertFailed(sev) (GetVhdlAssertCount(sev) /!= 0)=, and IsAssertFailed (GetVhdlAssertCount /!= 0)=. Is that reading right?

Also, why the explicit rejection of NOTE level assertions? I understand the logic of the above of not including them into the math of the argumentless calls, but according to that text I'm actively barred from requesting GetVhdlAssertCount(NOTE).

-- Rob Gaddi - 2017-02-08

Version 3 still does not define what happens when the "format" string in the call of SetVhdlAssertFormat has an invalid syntax. See also Thomas' comment on 2017-01-04.

Possible solution: Add the following to the new paragraph before subsection "Syntax Rules".

If a string replacement has an invalid syntax, then it will not be replaced, that is, it will be copied literally to the produced output.

-- Martin Zabel - 2017-02-10

@RG.1 Correct on GetVhdlAssertCount and IsAssertFailed.

@RG.2 VHDL Asserts have two components: Error reporting and message filtering. Through the simulator GUI you can turn them on and off. I interpreted NOTEto be an item that is only a message that can be filtered - turned on or off and not an item that is signaling any form of an error, hence, I do not count it.

OTOH, if we had a GetVhdlAssertCount(NOTE), then the sum returned by GetVhdlAssertCount would likely need to include that value. I have used vendor models that used NOTE extensively. Do you see these as something you want to count? Some of them were quite annoying.

-- Jim Lewis - 2017-02-14

Updated to version 4: Handling of invalid format strings.

-- Martin Zabel - 2017-02-28

TBP #1: The format_specification appears to introduce a spurious closing brace.

TBP #2: Consider these clarifying substitutions:

FROM: The string supports format specifiers in string replacements. A string replacement is a string starting with a left curly bracket, followed by the format variable and closed by a right curly bracket. The format variable can be followed by an optional colon and format specification string.

TO: 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.

FROM: The curly bracket characters can be escaped by doubling the same.

TO: Doubled left curly brackets do not introduce string replacements but translate to single left curly brackets in the derived formatted output.

TBP #3: Curly brackets are regularly referred to as braces. The current LRM is inconsistent in its use of these names. If we could decide on one name, we should probably make the LRM fully consistent with another LCS in this respect.

-- Thomas Preusser - 2017-02-28

TPB #1: fixed
TPB #2: changed

TPB #3: Curly brackets are regularly referred to as braces. ...
PL: LRM 15.2 Character set defined the names (incl. aliases) of special characters. The word brace or braces is only used in LRM 1.x and was introduced in the 2008 revision, by adding sections 1 and 2 before the old section 1. I notified Ernst, that we should correct section 1.

-- Patrick Lehmann - 2017-03-06

Why is the assert count always 0 immediately after elaboration? Surely a function called during elaboration can have an assertion?

-- Peter Flake - 2017-03-09