[ibis-macro] Re: Usage Out syntax rules

From: "Muranyi, Arpad" <Arpad_Muranyi@xxxxxxxxxx>
To: "ibis-macro@xxxxxxxxxxxxx" <ibis-macro@xxxxxxxxxxxxx>
Date: Mon, 2 Jan 2012 21:58:22 +0000

Happy New Year!


I gave myself an AR in the last ATM meeting (December 20, 2011)
to revise the BIRD draft I wrote on the problems discovered with
the Usage Out rules (or their lack of).  Please review the attached
file and let me know if there is anything that needs changing.

Based on our discussion in the last ATM meeting I "implemented"
the following thoughts in this draft:


1) EDA tool may ignore ({Format} <data_format> <data>) for Usage Out,
   - except for Table which is used for formatting purposes (BIRD 132)
2) Corner should not be allowed for Usage Out
   - since AMI model is not aware of EDA tool's simulation corner
3) Default and Value are synonyms (no special meaning given to Default)
4) Default is only a picker for multi valued data when user doesn't pick
   - therefore it is not allowed for Usage Out parameters for which the
     user does not make any selections


Please note that in #1 I use the words "may ignore" (instead of
"must" or  "should") so that we wouldn't exclude the possibility
of writing new BIRDs in the future to implement some of those
ideas which were suggested by Ambrish.

I would like to discuss this BIRD draft in the meeting tomorrow,
so please be prepared with your comments.

Thanks,

Arpad
==================================================================

*****************************************************************************
*****************************************************************************

BIRD ID#:        xxx
ISSUE TITLE:     Usage Out Syntax Correction
REQUESTER:       Arpad Muranyi, Mentor Graphics, Inc.
DATE SUBMITTED:  January ??, 2012
DATE REVISED:    
DATE ACCEPTED BY IBIS OPEN FORUM:  

*****************************************************************************
*****************************************************************************

STATEMENT OF THE ISSUE:

The IBIS specification's definition for Usage Out parameters states that
"Parameter is Output only from executable", but it is not clear whether
this means "output only", as opposed to input or I/O, or whether this
means "output coming only from executable", meaning that the source of
the data can only be the AMI executable model and nothing else.

Consequently questions arise about the purpose of the <data> in the .ami
file for Usage Out parameters.  Is this <data> supposed to be used for
initializing something, and if so what and how?  Related to this, the
meaning of "Default" needs to be clarified also, because it is not clear
whether it means "default value" for the initialization mentioned above,
or whether it means "default pick" for multi-valued parameters, such as
Format Range, List, Increment, Steps for the case when the user doesn't
make a selection before a simulation is started.

Depending on what the answer is to the above questions, one might also
wonder whether the .ami parameter file should contain a value for Usage
Out parameters at all.  The general syntax for AMI parameters does not
distinguish between Usage Out and any other Usage types, which implies
that <data> is required for all Usage types.  This creates a conflict with
one of the possible interpretations that the only source of the Usage Out
parameter <data> is the AMI model.

*****************************************************************************

STATEMENT OF THE RESOLVED SPECIFICATIONS:

EDA tool may ignore ({Format} <data_format> <data>) for Usage Out,
- except for Table which is used for formatting purposes (BIRD 132)

Corner should not be allowed for Usage Out
- since AMI model is not aware of EDA tool's simulation corner

Default and Value are synonyms (no special meaning given to Default)

Default is only a picker for multi valued data when user doesn't pick
- therefore it is not allowed for Usage Out parameters for which the
  user does not make any selections

Since BIRD 127.4 contains significant modifications in this area of the
IBIS specification, some of the resolutions described here are to be
applied to BIRD 127.4 as indicated.


On pg. 140 of the IBIS v5.0 specification, change these lines:


|   Usage: (required for model specific parameters)
|     In     Parameter is required Input to executable
|     Out    Parameter is Output only from executable
|     Info   Information for user or EDA platform
|     InOut  Required Input to executable.  Executable may return different
|            value.

to:

|   Usage: (required for model specific parameters)
|*    In     Parameter value is a required input to the AMI model
|*    Out    Parameter value is coming from the AMI model
|     Info   Information for user or EDA platform
|*    InOut  Parameter value is a required input to the AMI model.
|*           The AMI model may return a different value.


On pg. 140 of the IBIS v5.0 specification, change these lines:


|     Corner    <typ value> <slow value> <fast value>

to:

|     Corner    <typ value> <slow value> <fast value>
|*              Corner is not allowed with Usage Out parameters


In BIRD 127.4, change these lines:


|   Default <value>:
|*    Default and Value are mutually exclusive, and must not be used together
|*    for the same parameter.  Default is not allowed for Table, Gaussian,
|*    Dual-Dirac and DjRj.  Default is optional for Range, List, Corner, 
|*    Increment and Steps.  If a Default <value> is specified, its value must
|*    have the same Type as the parameter.  For example, if Type is Boolean,
|*    <value> must be either True or False, if Type is Integer, <value> must
|*    be an integer.  Also, if Default is specified, <value> must be a member
|*    of the set of allowed values of the parameter.  If Default is not
|*    specified, the default value of the parameters will be the <typ> value.

to:

|   Default <value>:
|*****When used with single value data, Default and Value are mutually
|*    exclusive, and must not be used together for the same parameter.
|*****In these situations, Default is a synonym of Value and does not imply
|*****any additional meaning or actions.  Default is not allowed for any Usage
|*****Out parameter types, and Table, Gaussian, Dual-Dirac and DjRj.  Default
|*****is optional for Range, List, Corner, Increment and Steps.  When Default
|*****is specified for any of these parameter types, it shall be used by the
|*****EDA tool to pick one value from all the possibilities for that parameter
|*****if the user does not make such a selection.
|*
|*    If a Default <value> is specified, its value must have the same Type as
|*    the parameter.  For example, if Type is Boolean, <value> must be either
|*    True or False, if Type is Integer, <value> must be an integer.  Also, if
|*    Default is specified, <value> must be a member of the set of allowed
|*    values of the parameter.  If Default is not specified, the default value
|*    of the parameters will be the <typ> value.


In BIRD 127.4, change these lines:


|*              All parameters must be in the following format:
|*
|*              (parameter_name (Usage <usage>)
|*                              (Type <data_type>)
|*                              ({Format} <data_format> <data>)
|*                              (Default <value>)
|*                              (Description <string>))
|*
|*              Notes:
|*              1) The order of the entries is not important.
|*              2) The word Format is optional as indicated by the curly
|*                 braces "{" and "}" and may be ignored by the EDA tools.
|*                 (The examples do not show the word Format).
|*              3) Certain reserved parameter names allow only certain
|*                 <data_format> selections, as described below.
|*              4) The <data_format> selection of Value and Default are
|*                 always mutually exclusive.  Certain parameters may require
|*                 Value or Default, but Value and Default are not allowed to
|*                  be present together for the same parameter.
|*              5) <data_format> is always required for selections other
|*                 than Value.
|*              6) Default is optional for <data_format> Range, List, Corner, 
|*                 Increment and Steps.
|*              7) Default is not allowed for <data_format> Table, Gaussian,
|*                 Dual-Dirac and DjRj.
|**             8) Additional rules apply when <data_format> is Table.  The
|**                format for <data> describes a set of rows containing data
|**                values.  Each row has its set of column data values enclosed
|**                by parentheses '(' and ')'.  Each row contains the same
|**                number of column values.  Any or all of these columns may
|**                have different data types.  For this case the <data_type>
|**                argument is either a list of data types (one for each
|**                column), or a single data type.  If it is a single data
|**                type then this type shall be applied to all of the columns
|**                in each row.
|***            9) Description is optional.

to:

|*              All parameters must be in the following format:
|*
|*              (parameter_name (Usage <usage>)
|*                              (Type <data_type>)
|*                              ({Format} <data_format> <data>)
|*                              (Default <value>)
|*                              (Description <string>))
|*
|*****          For Usage Out parameters, ({Format} <data_format> <data>) may
|*****          be ignored by the EDA tool, except when <data_format> is Table
|*****          where a one-row Table is required in <data> to serve as a
|*****          template for single and multi-row tables.  
|*****
|*              Notes:
|*              1) The order of the entries is not important.
|*              2) The word Format is optional as indicated by the curly
|*                 braces "{" and "}" and may be ignored by the EDA tools.
|*                 (The examples do not show the word Format).
|*              3) Certain reserved parameter names allow only certain
|*                 <data_format> selections, as described below.
|*              4) The <data_format> selection of Value and Default are
|*                 always mutually exclusive.  Certain parameters may require
|*                 Value or Default, but Value and Default are not allowed to
|*                  be present together for the same parameter.
|*              5) <data_format> is always required for selections other
|*                 than Value.
|*              6) Default is optional for <data_format> Range, List, Corner, 
|*                 Increment and Steps.
|*****          7) Default is not allowed for Usage Out parameters and
|*****             <data_format> Table, Gaussian, Dual-Dirac and DjRj.
|**             8) Additional rules apply when <data_format> is Table.  The
|**                format for <data> describes a set of rows containing data
|**                values.  Each row has its set of column data values enclosed
|**                by parentheses '(' and ')'.  Each row contains the same
|**                number of column values.  Any or all of these columns may
|**                have different data types.  For this case the <data_type>
|**                argument is either a list of data types (one for each
|**                column), or a single data type.  If it is a single data
|**                type then this type shall be applied to all of the columns
|**                in each row.
|***            9) Description is optional.

*****************************************************************************

ANALYSIS PATH/DATA THAT LED TO SPECIFICATION

The author of this BIRD posted an email on the IBIS ATM email reflector
(ibis-macro@xxxxxxxxxxxxx) on December 12, 2011 with questions and
suggestions on these problems.  This email resulted in a very active email
exchange between December 12 and 19, 2011, involving private and public
messages.  This email thread revealed that various experts in this field
have a wide range of interpretation on this topic.  The topic was also
discussed at length in the December 20, 2011 ATM meeting, where the
following slides were used for the discussion:

http://www.vhdl.org/pub/ibis/macromodel_wip/archive/20111220/arpadmuranyi/Notes%20on%20Usage%20Out%20parameters%20in%20IBIS-AMI/UsageOutFixNotes_2011_12_20.pdf

Most of the questions were answered by Walter Katz (SiSoft), stating what
the original intent of the IBIS-AMI specification was.  However, the meeting
ended inconclusively on some points.  This BIRD attempts to correct the
wording of the specification to reflect the original intent as described 
in the December 20, 2011 ATM teleconference without putting road blocks in
front of some of the suggested additional capabilities for the future.

*****************************************************************************

ANY OTHER BACKGROUND INFORMATION:

*****************************************************************************

[ibis-macro] Re: Usage Out syntax rules

Other related posts: