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

BIRD ID#:       134
ISSUE TITLE:    AMI Function Return Value Clarification
REQUESTOR:      Arpad Muranyi, Mentor Graphics
DATE SUBMITTED: May 20, 2011
DATE REVISED:
DATE ACCEPTED BY IBIS OPEN FORUM:June 24, 2011

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

STATEMENT OF THE ISSUE:

The IBIS 5.0 specification defines the return values of the AMI_Init
and AMI_GetWave functions as "1" for success and "0" for failure, but
doesn't define what constitutes success or failure.  As a result, some
models return a failure code (0) for functional problems even if they
are able to complete execution successfully, while other models return
a failure code (0) only when they experience serious program execution
failures.  Not knowing the nature of the error code, it is difficult to
implement appropriate exception handling routines in the EDA tools.

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

STATEMENT OF THE RESOLVED SPECIFICATIONS:


On pg. 188 and 189 insert after these lines:


| 1 for success
| 0 for failure


the following lines:


| Algorithmic models shall return a failure code (0) if and only if the
| function call fails due to a program execution error.  In all other
| cases the return code shall be "success" (1), even if the function
| cannot operate properly due to some functional problems.  For example,
| if a function includes a CDR which is unable to get into a stable mode,
| the function shall still return a success code (1).  Examples for
| returning a failure code (0) may include an invalid data type, a
| null pointer during run time, or anything that prevents the successful
| execution of the model's code.
|
| The authors of Algorithmic Models are encouraged to provide feedback
| to the EDA tool's users through the various available messaging
| options about any difficulties the model encounters during execution,
| regardless of what the value of the function's return code is.
|

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

ANALYSIS PATH/DATA THAT LED TO SPECIFICATION:

There is an (unspoken) agreement between software developers that the
function returns a failure code when the function call fails, but not
when the device it models cannot operate properly.

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

ANY OTHER BACKGROUND INFORMATION:

This BIRD was approved at the IBIS Open Forum teleconference of 
June 24, 2011.

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