LCS2016_061 < P1076

P1076 Web>VHDL2017>LCS2016_061 (2020-02-17, JimLewis) (raw view)EditAttach
---+!! Language Change Specification for Conditional Compilation Directives

%TOC%

| <sticky><b>LCS Number:</b></sticky> | LCS-2016-61 |
| <sticky><b>Version:</b></sticky>  | 7 |
| <sticky><b>Date:</b></sticky>  | v3 26-Jan-17, v4 18-Feb-17, v5 2-Mar-17, v6 9-Mar-17,v7 13-Apr-17 |
| <sticky><b>Status:</b></sticky>  | |
| <sticky><b>Author:</b></sticky>  | [[Main.PeterFlake][Peter Flake]] |
| <sticky><b>Email:</b></sticky>  | <span data-mce-mark="1">%USERINFO{"PeterFlake" format="$emails"}%</span> |
| <sticky><b>Source Doc:</b></sticky> | [[ConditionalCompilation][Conditional Compilation]] <span data-mce-mark="1">%BR%</span> [[VHDLPreprocessor][VHDL Preprocessor]] |
| <sticky><b>Summary:</b></sticky>  | Provide conditional compilation mechanism |

---++ Voting Results: Cast your votes here

   * Yes:
      1 %USERSIG{PeterFlake - 2016-11-24}%
      1 %USERSIG{BrentHahoe - 2016-12-02}%
      1 %USERSIG{RobGaddi - 2017-03-02}% - ver 5
      1 %USERSIG{ThomasPreusser - 2017-02-24}% - ver 6 - assuming the identifier being FALSE is corrected to be an expression (below BNF of =conditional_analysis_block=) - ver 7
      1 %USERSIG{JimLewis - 2017-03-05}% - ver 5

   * No:
      1 %USERSIG{PatrickLehmann - 2017-01-11}% - ver 2 - See Martin's comments

   * Abstain:
      1 %USERSIG{LievenLemiengre - 2017-01-27}%
      1 %USERSIG{BrentHahoe - 2017-02-16}% Version 3 - Abstain due to lack of personal time for review.
      1 %USERSIG{MartinThompson- 2017-02-17}%
      1 %USERSIG{FarrellOstler - 2017-01-16}% - ver 6

---++ Details of Language Change:

Key:
   * LRM text is shown between single quotes <sticky>%BLACK%<b>'... P1076 LRM quoted text ...'</b>%ENDCOLOR%</sticky>
   * Existing LRM text is shown in <sticky>%BLACK%<b>BLACK font</b>%ENDCOLOR%</sticky>
   * Additional LRM text is shown in <sticky>%RED%<b>RED</b>%ENDCOLOR%</sticky>
   * Deleted LRM text is shown in <sticky>%RED%<strike><b>RED with strike-through</b></strike>%ENDCOLOR%</sticky>

---+++ LRM 24 Standard tool directives
---++++!! page 445 bottom

Add section 24.2 to the LRM

<span data-mce-mark="1">
%RED%</span><b>24.2 Conditional Analysis Tool Directives</b>

<span data-mce-mark="1">
%RED%</span>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".

<span data-mce-mark="1">
%RED%</span>The analysis phase of tool execution shall ignore the lines of description which are excluded and therefore perform no syntax checks on those lines. 
<sticky><pre>%RED%
conditional_analysis_directive ::= 
     `<b>if</b> conditional_analysis_expression <b>then</b>
   | `<b>elsif</b> conditional_analysis_expression <b>then</b>
   | `<b>else</b>
   | `<b>end</b> [ <b>if</b> ]
   | `<b>warning</b> string_literal
   | `<b>error</b> string_literal
</pre></sticky>

<span data-mce-mark="1">
%RED%</span>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: 
<sticky><pre>%RED%
conditional_analysis_block ::=
     source_text { conditional_analysis_block }
   | `<b>warning</b> string_literal { conditional_analysis_block }
   | `<b>error</b> string_literal { conditional_analysis_block }
   | `<b>if</b> conditional_analysis_expression <b>then</b> { conditional_analysis_block }
      {`<b>elsif</b> conditional_analysis_expression <b>then</b> { conditional_analysis_block } }
      [`<b>else</b> { conditional_analysis_block } ]
      `<b>end</b> [ <b>if</b> ] { conditional_analysis_block }
</pre></sticky>

<span data-mce-mark="1">
%RED%</span>The `<b>if</b> directive includes the following analysis block if the expression is TRUE and excludes the block if the expression is FALSE.The `<b>elsif</b> 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 `<b>else</b> directive includes the following analysis block if none of the conditional analysis expressions in the set was TRUE, and excludes the block otherwise.

The `<b>warning</b> directive shall cause the analyser to copy the string literal to the analysis log but not stop the analysis. The `<b>error</b> directive shall cause the analysis to fail as well as copying the string literal to the analysis log.
<sticky><pre>%RED%
conditional_analysis_expression ::= 
     conditional_analysis_relation
   | conditional_analysis_relation { <b>and</b> conditional_analysis_relation }
   | conditional_analysis_relation { <b>or</b> conditional_analysis_relation }
   | conditional_analysis_relation { <b>xor</b> conditional_analysis_relation }
   | conditioanl_analysis_relation { <b>xnor</b> conditional_analysis_relation }
</pre>
<pre>%RED%
conditional_analysis_relation ::=
     (  conditional_analysis_expression )
   | <b>not</b> ( 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
</pre></sticky>

<span data-mce-mark="1">
%RED%</span>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.

<span data-mce-mark="1">
%RED%</span><b>24.2.1 Standard Conditional Analysis Identifiers</b>

<span data-mce-mark="1">
%RED%</span>The tool shall supply the following identifiers: 
<sticky><pre>%RED%
     VHDL_VERSION
     TOOL_TYPE
     TOOL_VENDOR
     TOOL_NAME
     TOOL_EDITION
     TOOL_VERSION
</pre></sticky>

<span data-mce-mark="1">
%RED%</span>The VHDL_VERSION identifier shall have one of the following string values: 
<sticky><pre>%RED%
     "1987", "1993", "2000", "2002", "2008", etc.
</pre></sticky>

<span data-mce-mark="1">
%RED%</span>The TOOL_TYPE identifier shall have one of the following string values: 
<sticky><pre>%RED%
     "SIMULATION", "SYNTHESIS", "FORMAL"
</pre></sticky>

%RED%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 &gt; OLD_VERSION should return TRUE.%ENDCOLOR%

---+ 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.

-- <span data-mce-mark="1">%BUBBLESIG{RyanHinton - 2016-12-21}%</span>

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 &lt;, &lt;=, &gt;, &gt;= 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" =&gt; character set Latin1, sorting order swedish, case insensitive.

-- <span data-mce-mark="1">%BUBBLESIG{PatrickLehmann - 2016-12-31}%</span>

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

-- %BUBBLESIG{PatrickLehmann - 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 <b>generate</b>s. This will provoke libraries with code like: 
<pre>'if VHDL_VERSION = "1987"
constant VHDL_VERSION : string := "1987";
'elsif VHDL_VERSION = "1993"
constant VHDL_VERSION : string := "1993";
'elsif
  ...
'end if
</pre>

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

-- %BUBBLESIG{ThomasPreusser - 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."

-- %BUBBLESIG{PatrickLehmann - 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.

-- %BUBBLESIG{ThomasPreusser - 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.

-- %BUBBLESIG{Main.PeterFlake - 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 &gt; OLD_VERSION should return TRUE.

-- %BUBBLESIG{MartinZabel - 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.

-- %BUBBLESIG{PatrickLehmann - 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.)

-- %BUBBLESIG{FarrellOstler - 2017-01-16}%

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

-- %BUBBLESIG{MartinZabel - 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.

-- %BUBBLESIG{JimLewis - 2017-02-07}%

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

-- %BUBBLESIG{JimLewis - 2017-02-10}%

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

-- %BUBBLESIG{ThomasPreusser - 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:
<sticky><pre>%RED%
conditional_analysis_directive ::= 
  `<b>if</b> conditional_analysis_expression conditional_analysis_block
  {`<b>elsif</b> conditional_analysis_expression conditional_analysis_block}
  [`<b>else</b> conditional_analysis_block]
   `<b>end</b>
</pre>
<pre>%RED%
conditional_analysis_block ::=
     null
   | source_text
   |  conditional_analysis_directive
</pre></sticky>

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.

-- %BUBBLESIG{MartinZabel - 2017-02-10}%

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

-- %BUBBLESIG{PatrickLehmann - 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).

-- %BUBBLESIG{MartinZabel - 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.

-- %BUBBLESIG{JimLewis - 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".

-- %BUBBLESIG{ThomasPreusser - 2017-02-24}%

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

-- %BUBBLESIG{ThomasPreusser - 2017-03-02}%

The grammar has been corrected.

-- %BUBBLESIG{PeterFlake - 2017-03-09}%

%COMMENT%
Topic revision: r44 - 2020-02-17 - 15:34:35 - JimLewis
P1076