Language Change Specification for Conditional Compilation Directives

Voting Results: Cast your votes here

• Yes:
  1. Peter Flake - 2016-11-24
  2. Brent Hayhoe - 2016-12-02
  3. Rob Gaddi - 2017-03-02 - ver 5
  4. Thomas Preusser - 2017-02-24 - ver 6 - assuming the identifier being FALSE is corrected to be an expression (below BNF of conditional_analysis_block) - ver 7
  5. Jim Lewis - 2017-03-05 - ver 5

• No:
  1. Patrick Lehmann - 2017-01-11 - ver 2 - See Martin's comments

• Abstain:
  1. Lieven Lemiengre - 2017-01-27
  2. Brent Hayhoe - 2017-02-16 Version 3 - Abstain due to lack of personal time for review.
  3. Martin Thompson- 2017-02-17
  4. Farrell Ostler - 2017-01-16 - ver 6

Details of Language Change:

Key:

• LRM text is shown between single quotes '... P1076 LRM quoted text ...'
• Existing LRM text is shown in BLACK font
• Additional LRM text is shown in RED
• Deleted LRM text is shown in RED with strike-through

LRM 24 Standard tool directives

page 445 bottom

Add section 24.2 to the LRM

24.2 Conditional Analysis Tool Directives

Conditional analysis directives allow the VHDL description to be varied according to the choice of tool or usage. Each directive occupies a complete line of graphic characters. The directive may be commented out by preceding it with --, in which case the directive is ignored.

The tool shall provide string identifiers and values which are visible to the conditional analysis directives. These identifiers may be built into the tool or provided to the tool invocation by the user. The tool shall provide a mechanism for the user to supply identifiers and associated values, such as DEBUG_LEVEL"2".

The analysis phase of tool execution shall ignore the lines of description which are excluded and therefore perform no syntax checks on those lines.

conditional_analysis_directive ::= 
     `if conditional_analysis_expression then
   | `elsif conditional_analysis_expression then
   | `else
   | `end [ if ]
   | `warning string_literal
   | `error string_literal

The order in which these directives must be used and their meaning is like the if statement (section 10.8) and is specified by the following grammar, where source_text means a sequence of graphic characters, which may be valid VHDL:

conditional_analysis_block ::=
     source_text { conditional_analysis_block }
   | `warning string_literal { conditional_analysis_block }
   | `error string_literal { conditional_analysis_block }
   | `if conditional_analysis_expression then { conditional_analysis_block }
      {`elsif conditional_analysis_expression then { conditional_analysis_block } }
      [`else { conditional_analysis_block } ]
      `end [ if ] { conditional_analysis_block }

The `if directive includes the following analysis block if the expression is TRUE and excludes the block if the expression is FALSE.The `elsif directive includes the following analysis block if the expression is the first one in the set to be TRUE and excludes the block if the expression is FALSE or if a previous conditional analysis expression in the set was TRUE. The `else directive includes the following analysis block if none of the conditional analysis expressions in the set was TRUE, and excludes the block otherwise.

The `warning directive shall cause the analyser to copy the string literal to the analysis log but not stop the analysis. The `error directive shall cause the analysis to fail as well as copying the string literal to the analysis log.

conditional_analysis_expression ::= 
     conditional_analysis_relation
   | conditional_analysis_relation { and conditional_analysis_relation }
   | conditional_analysis_relation { or conditional_analysis_relation }
   | conditional_analysis_relation { xor conditional_analysis_relation }
   | conditioanl_analysis_relation { xnor conditional_analysis_relation }

conditional_analysis_relation ::=
     (  conditional_analysis_expression )
   | not ( conditional_analysis_expression )
   | conditional_analysis_identifier = string_literal
   | conditional_analysis_identifier /= string_literal
   | conditional_analysis_identifier < string_literal
   | conditional_analysis_identifier <= string_literal
   | conditional_analysis_identifier > string_literal
   | conditional_analysis_identifier >= string_literal

In accordance with the rest of VHDL, the conditional analysis identifier is not case sensitive, but the string literal is. If the conditional analysis identifier has not been defined, its string value is assumed to be the empty string "". The relational operators shall behave as in section 9.2.3 where the operands are one-dimensional arrays of type CHARACTER.

24.2.1 Standard Conditional Analysis Identifiers

The tool shall supply the following identifiers:

     VHDL_VERSION
     TOOL_TYPE
     TOOL_VENDOR
     TOOL_NAME
     TOOL_EDITION
     TOOL_VERSION

The VHDL_VERSION identifier shall have one of the following string values:

     "1987", "1993", "2000", "2002", "2008", etc.

The TOOL_TYPE identifier shall have one of the following string values:

     "SIMULATION", "SYNTHESIS", "FORMAL"

The values of the other identifiers are at the discretion of the tool vendor. The tool name is expected to be more generic than the tool edition. The tool version is expected to increase chronologically so that the ordering operators can be used. Given an older tool version OLD_VERSION and a newer tool version NEW_VERSION, the expression NEW_VERSION > OLD_VERSION should return TRUE.

Comments

Any reason this isn't included in the LCS list at the top of the Vhdl2019CollectedRequirements page? It should be there if it's ready for voting.

I helped push for making everything a string. Now as I look at how I plan on using these, I want to do numeric comparisons on VHDL_VERSION and TOOL_VERSION. Any clue if supporting both integers and strings is really hard? I can help with the grammar changes if desired.

-- Ryan Hinton - 2016-12-21

I don't think a full integer support is supported for VHDL-2017. (Can be proposed later if we see good implementation results in the tools.) But I would also prefer <, <=, >, >= operations based on strings. Strings can be ordered (like VHDL does) by defining a collation. VHDL could define a fixed collation or we add a directive to set the collation for comparisons (E.g. in MySQL a charset and collation can be set globally). `SetCollation "latin1_swedish_ci" => character set Latin1, sorting order swedish, case insensitive.

-- Patrick Lehmann - 2016-12-31

compilation_relation on the right-hand-side of compilation_expression misses underline characters in the EBNF rule.

-- Patrick Lehmann - 2017-01-02

I am not very fond of creating another namespace for compilation identifiers that is inaccessible for other more flexible statements like conditional generates. This will provoke libraries with code like:

'if VHDL_VERSION = "1987"
constant VHDL_VERSION : string := "1987";
'elsif VHDL_VERSION = "1993"
constant VHDL_VERSION : string := "1993";
'elsif
  ...
'end if

The fixed set of compilation identifiers also precludes the most useful specification of user-defined identifiers.

-- Thomas Preusser - 2017-01-03

@Thomas As discussed in several meetings, a pre-processor was not considered an option to address the issues of tool and version incompatibilities. Generate statements can't be used because they don't hinder tools to analyze the body of such statements.

Tool directives and conditional compilation shall not aim to provide macros and defines. But yes, users are free to emulate defines with tool directives and conditional compilation. There is no significant difference to PoC 's SIMULATION constant.

The set of identifiers is not fixed; this LCS defines a minimal set of identifiers. "These identifiers may be built into the tool or provided to the tool invocation by the user."

-- Patrick Lehmann - 2017-01-03

Okay, I read over the part with the user-specified identifiers.

Otherwise, I did not argue against the proposal in whole but the new namespace of identifiers. This will provoke the copying into proper VHDL constants that I sketched. And yes, this is different from PoC 's SIMULATION constant, which can readily be accessed wherever I need it.

-- Thomas Preusser - 2017-01-04

The namespace must be separate because it should be possible to implement the conditional analysis directives by a pre-processor, which will remove all the conditional analysis identifiers from the output files. This is probably how conditional analysis will be retro-fitted to old tools.

-- Peter Flake - 2017-01-26

I think I found some bugs:

1. The definition of compilation_directive misses the reference to conditional_compilation_block.

2. The definition of compilation_directive misses a then to be consistent with the existing syntax. This would also allow comments after a compilation expression for documentation and also easier reading if a complex compilation expression is scattered across multiple lines.

3. The root of this preprocessor tree (which is of course compilation_directive) should be explicitly named.

4. A definition of null and source_text is missing.

5. At the moment an `if is considered everywhere, also in comments or in the middle of a VHDL statement. I prefer the C way. Preprocessor directives might be only preceded by spaces within a line.

6. For the tool version, I would detail the "chronological order" to something like: Given an older tool version OLD_VERSION and a newer tool version NEW_VERSION, the expression NEW_VERSION > OLD_VERSION should return TRUE.

-- Martin Zabel - 2017-01-11

MZ: At the moment an `if is considered everywhere, also in comments or in the middle of a VHDL statement. I prefer the C way. Preprocessor directives might be only preceded by spaces within a line.

PL: I found LRM 15.11, stating how tool directives start and end. They seem to behave like comments and can be placed e.g. after a statement in the same line.

-- Patrick Lehmann - 2017-01-14

The LRM has been consistent in using Analyze/Elaborate terminology when referring to the processing of VHDL design units, while systematically excluding the use of the word "compile" (except for six minor lapses; see Note 1).

LCS 61 (which is at version 2 at the time of this writing) throws this discipline out by couching the concept of conditional inclusion of parts of a description as "conditional compilation." This is probably not a good choice; "compile" should not become part of the official terminology at this point.

Note 1: The six lapses are: (1) "Compiles" instead of "Analyzes" in Annex C, introduced in LRM 1993 and renamed as Annex D in LRM 2008. (2) Four cases, one each in clauses 16.6, 16.7, 16.10 and 16.11 of LRM 2008, where the prose explains how compliant implementations of the corresponding packages can be achieved. Here, "may choose to simply compile the package body" could instead be, "may choose to simply use the package body." (3) In the VHPI Header (LRM 2008, Annex B), as part of a comment in the header source code, talks of "compiled data" instead of "analyzed data."

(There is also a use of the word "compilation" in Annex B.3. In this case it is used relative to a C Language file and, therefore, is appropriate.)

-- Farrell Ostler - 2017-01-16

Ironically, VHDL_VERSION would be always greater or equal than "2017" because this feature is not available in an earlier version.

-- Martin Zabel - 2017-01-21

@MZ Try putting the following in your testbench: "std.env.stop(0);" and see which revisions it runs under. This is VHDL-2008 code, I think I have seen it run on earlier versions.

-- Jim Lewis - 2017-02-07

Sounds like the concerns about the names not being visible can be solved by LCS_2016_006d

-- Jim Lewis - 2017-02-10

@Jim: Not quite, you need a lookup mechanism as specified by LCS 006e to access tool- and user-defined identifiers.

-- Thomas Preusser - 2017-02-10

Regarding version 3: As already posted on 2017-01-11: the definition of compilation_directive misses the reference to conditional_compilation_block. And even more, the current BNF would allow to start with a `elsif, or `else or `end instead of just `if. Furthermore the if after `endif could not be optional, it my be part of the intended source text.

My view is, design units are analyzed as usual until the tool directive compilation_directive is encountered. Then according to the conditions, one of the conditional_compilation_block=s may be included. This =conditional_compilation_block may again include another tool directive. Thus, the BNFs should be:

conditional_analysis_directive ::= 
  `if conditional_analysis_expression conditional_analysis_block
  {`elsif conditional_analysis_expression conditional_analysis_block}
  [`else conditional_analysis_block]
   `end

conditional_analysis_block ::=
     null
   | source_text
   |  conditional_analysis_directive

This would also define the matching `elsif, or `else and `end if conditional analysis directives are nested.

NOTE: The analyzer must parse the text of the design file until he founds the `end of the outermost conditional analysis directives, before he can continue with the analysis of the design file. I suspect that the goal of this LCS can be only achieved by a separate pre-processing pass before analysis.

-- Martin Zabel - 2017-02-10

The EBNF rules still miss the reserved word then after if and elsif.

-- Patrick Lehmann - 2017-02-10

Regarding whether the places where tool directives can occur:

The lexer already distinguishes between a comment and a tool directive (and many more), see clause 15.3, 1st paragraph (at bottom of page 227). Clause 15.9, 4th paragraph (middle of page 235) states even more:

The presence or absence of comments has no influence on whether a description is legal or illegal. Furthermore, comments do not influence the execution of a simulation module; their sole purpose is to enlighten the human reader.

Thus, tool directives within comments are simply ignored by the lexer. All other tool directives are identified as such by the lexer and further processed by the parser (analyze step).

-- Martin Zabel - 2017-02-17

Meeting Feb 23, 2017 @MZ Discussed issue of 02-17, and decided that independent of where a tool directive is allowed, the requirement for conditional analysis is that a conditional tool directive shall be on a line by itself.

-- Jim Lewis - 2017-02-23

Is the EBNF for conditional_analysis_directive really needed? It just duplicates snippets from the EBNF for conditional_analysis_block. Additionally within the text after this latter EBNF, you will find "expression is TRUE" but "identifier is FALSE".

-- Thomas Preusser - 2017-02-24

I think we ought to allow at least a 'warning to coexist with regular code within the same block.

-- Thomas Preusser - 2017-03-02

The grammar has been corrected.

-- Peter Flake - 2017-03-09