Getting VHDL values ~~~~~~~~~~~~~~~~~~~ 1.VHPI value function prototypes -------------------------------- 1.2 getting a VHDL value ------------------------- (int) vhpi_get_value(vhpiHandle objHdl, vhpi_value_p value_p); vhpi_get_value takes 2 arguments: objHdl is a handle to the object to get the value from. value_p is a pointer to a value structure that contains information on how to format the value. The function returns 1 on success or 0 on failure to get the value. The error resulting from this function call may be checked immediately after the vhpi_get_value call by calling vhpi_check_error. The following errors are possible: This is not a valid object to get a value from the object does not carry a value or the object is NULL. bad format; the given format is inappropriate for the subtype of the object, or has not been set. The value does not fit, for example requesting the value of a real as an integer may result in an overflow. The value is returned but truncated. The simulator has made some performance optimizations that makes this object and value unaccessible. The value structure (see section 5) must have been allocated by the user. The format field and in some cases the subformat field must have been set by the user. The space to hold the value is allocated by the interface (str, vhpiTimeS vhpiPhysS for example). The user must copy this value out otherwise it might be overwritten by a subsequent call to vhpi_get_value. On the return, the size and corresponding union value and in some cases the elemValue fields have been set (see table section 4). For string values (vhpiStringVal, vhpi[Bin,...]StrVal...) the interface allocates the string buffer and sets the str field pointer of the vhpiValueS structure to point to the allocated buffer. For time values, the interface allocates the vhpiTimeS or vhpiPhysS structure if needed and puts a pointer to it into the caller's value structure. Time values are returned with the type field set to vhpiInt and the unit set to vhpiFS. Physical values are returned with the type field set to vhpiInt and the unit set to 0 (the base unit). In case where the format is set by the user to vhpiObjTypeVal, the returned value will be returned in the most appropriate format for the type of the object. The interface will set the format field and in some cases the subformat field as well. Another document specifies the formats in which the value will be returned depending on the type of the object (objTypeVal_spec). 1.2 Functions to interpret values of complex types: ---------------------------------------------------- They allow to: iterate on the values of the fields of an object of a record type. iterate on the values of the elements of an object of an array type. Given a reference handle of the object of a composite type, it is possible to iterate through each record field or array element and get the value of that sub-element. The iteration methods are respectively vhpiSelectedNames, and vhpiIndexedNames. vhpi_iterate(vhpiSelectedNames, objHdl) vhpi_iterate(vhpiIndexedNames, objHdl) These methods return an ordered list of elements. In case of values of multi-dimensional arrays, each returned handle represents an element in that array. If the array has 3 dimensions r, c, t each handle returned can be represented by the 3 indices in r_indx, c_indx and t_indx. The elements are returned by varying the index of the last index constraint first. For each index range, the variation starts by the left index to the right index, independently of the direction of the range. Example: type array (1 to 2), (4 to 6), (8 downto 7) of integers. iterating on the array elements will return the elements represented by the following indices in the order they are declared. (1,4,8) (1,4,7) (1,5,8) (1,5,7) (1,6,8) (1,6,7) (2,4,8) (2,4,7) (2,5,8) (2,5,7) (2,6,8) (2,6,7) In the case of arrays of arrays, each returned handle represents an element in the base array. Example: type arr_of_arr (1 to 2) of bit_vector(1 to 16); signal s: arr_of_arr; vhpi_iterate(vhpiIndexedNames, sHdl); sHdl is a handle to signal s; The iteration function will return handles to s(1) and s(2) which are vectors of 16 bits each. The type of these handles is vhpiIndexedName. The value of each handle will be the value of the 16 bits vectors it refers to. In the case of an object of a record type, iterating through the record fields should return the selected object fields in the order they are declared. The kind of these handles is vhpiSelectedNameK. The value of such a handle will be the value of the selected field of the object. The selectedNames iteration method can only be called on an object which type is a record type. The indexedNames iteration method can only be called on an object which type is an array type. The reference handle kinds of the selectedNames and indexedNames iteration methods can either be members of the object class or of the name class. These 2 methods allow to walk through any complex VHDL object. 2.Object types that have a value: --------------------------------- all objects: vhpiConstDeclK vhpiSigDeclK vhpiFileDeclK vhpiVarDeclK vhpiGenericDeclK vhpiPortDeclK vhpiSigParamDeclK vhpiVarParamDeclK vhpiConstParamDeclK vhpiFileParamDeclK Note that the value can be fetched if the object declaration has been elaborated. If the value is fetched at the end of elaboration, the value is the default (`left) or initial value of the object provided in the declaration. The value of a generic after elaboration will be the value after generic propagation. During simulation, the value fetched is the value of the object at this particular time. For a fileDecl, the value is the logical name of the file supplied in the declaration. The value is of type string. For a variable of an access type, two values can be fetched: the access value and the dereference value of the variable. The access value designates the created object (just like a pointer). This is different from the value of the object which can be fetched by dereferencing the object. The value of a dereference name (.ALL) will be the value pointed by the object. The default initial value of a variable of an access type is NULL (NULL pointer). The default access value of a variable without an initial expression will be NULL, it will be illegal to try to get the derefence value of that variable. The initial access value of a variable with an initial expression will be the access value of the initial expression. Other objects that have values: class name (indexedName, sliceName, selectedName, simpNmae, attrName). There is the possibility of getting a value for the sub-classes of class literal . We defined different properties for each sub-classes vhpiIntValP for class intLiteral, vhpiRealValP fpr class realLiteral, and vhpiStrValP for classes stringLiteral, bitStringLiteral,charLiteral and enumLiteral. issue: ------ It will not be possible to fetch directly the value of any other expression such as binaryExpr, function call etc... The reason for that is that it would require the implementation of a expression evaluator, or to require code to be generated for each expression. Values of expression can be deduced from the object value they are assigned to. For foreign subprogram calls, it is possible to get the actual values associated with the formal parameters. Subprogram are dynamically elaborated therefore the values of their parameters or declared items can only be fetched when the program is currently executed or suspended. We provide a method to get the current equivalent process and a method to access the stack of an equivalent process. The user can only fetch the values of parameters or declared items if the subprogram call is returned either as the current executed process or is on the call stack of the current executed process or is on the stack of a suspended process. Sub-program parameter values can only be fetched when the subprogram is executed because they come to existence dynamically. In order to get a value for either a parameter or a declared item within that subprogram, the ast of the parameter or declared item, the pib of the subpCall and the stack frame level must be provided. Other types of objects which have values are simulation objects such as transactions (vhpiTransaction). Transactions values can only be fetched during a simulation session. Object values can be fetched after simulation initialization has completed in a simulation session, or after elaboration in an elaboration session. These class types have a property named "value" of type vhpiValueP 3. Value Types: --------------- . integer values . real values . enumerated values . character values . boolean values . severity_level . physical values . time values . bit values . std_logic values . string values . array values one-dimensional arrays . bit vectors or std_logic vectors . integer arrays... . array of records multi-dimensional arrays array of arrays . record values record fields are discrete types records of records records fiels are array type . access types . file types 4. Table of legal formats: -------------------------- This table describes the possible formats for the various types. Any user-defined type has a base type that can be mapped to the type category listed in that table. Captions: -: this field is irrelevant and does not need to be set. The first column lists VHDL types, the second column gives the possible formats for that type, the third column gives which field in the value structure will be used to store the value. The fourth column gives the possible subFormats for the VHDL type, this is only used for one dimensional array of discrete types or access of discrete types. For time or physical types, the fourth column is used to describe the setting of the unit and type fields. For one-dimensional array of discrete types, the fifth column describes which field of the elemValue structure will be used to store the value. For physical (resp. time) types, the fifth column will be used to describe which fields of the s_vhpi_phys (resp s_vhpi_time) structure will be used to store the value. Note: for getting vecVal values of array of time or physical values, the user has to set the format field to vhpiVecVal, the subformat field vhpiTimeVal or vhpiPhysVal. ---------------------------------------------------------------- | setting of fields in the | setting fields in | | s_vhpi_value structure | elemValue, s_vhpi_[phys,time] | ------------------------------------------------------------------------------- VHDL TYPE | format | value field | subFormat | elemValue | | | | type,unit | phys, time | ------------------------------------------------------------------------------- integer | vhpiIntVal | integer | - | - | | vhpi[...]StrVal str,size | | | | vhpiStringVal str,size | | | (*) integer values can be returned as strings in binary, octal, decimal | hexadecimal or pure string formats. In the case of binary, a 2# will | precede the value of the string. (Octal, 8#, decimal 10#, hexadecimal 16#.| In these cases the string value will be null terminated to indicate the | end of the string, the size field will be set to the number of characters | in the string. | ------------------------------------------------------------------------------- enumerated | vhpiIntVal | integer | - | - | | vhpiStringVal| str,size | - | - | (*)vhpiIntVal format : | the value returned is the position value of the enumeration identifier | vhpiStringVal format: | the string of the identifier representing the enumerated thing, the size | field will be set to the number of characters in the string. | ------------------------------------------------------------------------------- character | vhpiCharVal | character | - | - | vhpiIntVal | integer | - | - | vhpiStringVal str,size | - | - | (*) character types are enumerated types, if the format field is set to | vhpiIntVal, the value returned is the position of the character in the | standard char type | vhpiStringVal, the character is returned as the identifier string of the | character enumerated value. The size field is set to the number of | of characters in the string. | ------------------------------------------------------------------------------- boolean | vhpiIntVal | integer | - | - | | vhpiStringVal str,size | - | - | (*) boolean is another enumerated standard types of 2 values: false and true. | The value returned is the position of the enumerated value 0 for false and| 1 for true. | vhpiStringVal will return the identifier string of the enumerated value | "false" and "true". The size field is set to the number of characters in | the string. | ------------------------------------------------------------------------------- severity_level| vhpiIntVal | integer | - | - | | vhpiStringVal str,size | - | - | (*) severity level is another enumerated standard types of 4 values: note, | warning, error and failure. | The value returned is the position of the enumerated value. | vhpiStringVal will return the identifier string of the enumerated value | "note","warning""error", "failure". The size field is set to the number of| characters in the string. | ------------------------------------------------------------------------------- real | vhpiRealVal | real | - | - | | vhpiIntVal | integer | - | - | | vhpiStringVal str,size | - | - | (*) if the format is set to vhpiIntVal, the real value is rounded to its | closest (lower or higher) integer value | With the vhpiStringVal format, the size field is set to the number of | characters in the string. The string is null terminated. | ------------------------------------------------------------------------------- std time | vhpiTimeVal | time | - | - | any physical | vhpiStringVal str,size | - | - | phys not time | vhpiPhysVal | phys | - | see below | (*) For standard time the requested format can be set to vhpiTimeVal | or vhpiStringVal. | (*) For physical types other than standard time the requested format can be set to vhpiPhysVal or vhpiStringVal. | (*) vhpi_get_value allocates the time or physical structure (s_vhpi_time or s_vhpi_phys) when accessing the value of an object of a time or physical type. The type and unit fields of the time and physical structures will be set by the vhpi interface. vhpi_get_value will set the value pointer of the caller value structure to point to the allocated time or physical structure (*) vhpiPhysVal should be used for any physical type other that time. | vhpiTimeVal should be used for standard time values | vhpiStringVal can be used for any physical type. | (*) for vhpiPhysVal, the VHPI interface sets the unit field of the | s_vhpi_phys structure to the base unit, and the type field is set | to vhpiIntVal. (*) for vhpiTimeVal, the VHPI interface sets the unit field to vhpiFS | (precision of the simulator) and the type field to vhpiIntVal. | For the vhpiInt type, the high and low fields of the structure will be | used to provide the value. | If the user wants to get the a time or physical value in another unit, he has to do the conversion himself. The vhpiAuto or vhpiReal are not available for the getting time or | or physical values of objects. The vhpiAuto and vhpiReal type can be used | for the vhpi_get_time function which gets the current simulation time | (refer to the utils spec). (*) with the vhpiStringVal format it is possible to get the value returned as | a string. The string will contain the integer or real value of the | multiplicand followed by the name (string identifier) of the units. | A space character separates the multiplicand from the unit name. The unit | name is returned in lower cases. The size field is set to the number of | characters in the string. The string is null terminated. The value is | returned in the best fit unit chosen by the interface. The unit is | provided as part of the returned string. | (*) A time value can only be retrieved for an object of type time. | The function vhpi_get_value should not be used to get the current | simulation time (use vhpi_get_time instead) | ------------------------------------------------------------------------------- string | vhpiStringVal| str,size field | - | - | number of characters in the string | (*)in order to return the value of a string type value, the string size must | be specifed (number of characters in the string. A VHDL string may contain | the NULL character which is not indicative of the end of the string. | ------------------------------------------------------------------------------- std_logic | vhpiLogicVal | logic, size field = 1 | bit | | | MVL7 | | | | vhpiIntVal | integer,size field = 1 | | vhpiStringVal str,size field = 1 character | (*) logic scalar value can be represented as logic values or as integer values| for the vhpiIntVal format the value returned corresponds to the position of the enumerated value in the type, for example a logic of X will be returned as 1 for the IEEE std_logic type 1164. | (*) with the vhpiStringVal format the logic value is returned as a string of 1| character. | (*) The vhpiLogicVal format can only be used for standard logic types or | subtypes which values can be mapped to the predefined value set of 0,x,z,1 l,w, z and -,u Examples of such types are MVL7, MVL9, bit, MVL4. | In some cases the integer value (position in the enumerated type) will be | different from the logic value. | ------------------------------------------------------------------------------- array | | | | one dimension| vhpiVectorVal| vector, size field = number of array | | | elements represented by the | | | value. | (*) The element values of the array are returned in the order specified by | going from the left most index to the right most index. This is | independent of the direction of the range of the array. | of bit, | vhpiIntVal | integer, size field set to the number of array | elements represented by the value. | (*) 32 bits vectors can be represented by integer values | in case of more than 32 bits, an OVERFLOW error occurs, the integer value | only represents the 32 lower bits. | ---------------------------------- | subFormat | elemValue | --------------------------------- of integers | vhpiVectorVal| vector | vhpiIntVal | integer | of reals | vhpiVectorVal| vector | vhpiRealVal | real | of logic | vhpiVectorVal| vector | vhpiLogicVal | logic | | vhpiBinStrVal| str,size | - | - | | vhpiOctStrVal| str,size | - | - | | vhpiDecStrVal| str,size | - | - | | vhpiHexStrVal| str,size | - | - | (*) With the vhpi[Bin,Oct,Dec,Hex]StrVal formats, the logic vector value is | converted to a binary, octal, decimal or hexadecimal string. | The conversions used are the same as for Leapfrog. Conversion such as an X| logic value into a binary format are defined. | of time | vhpiVectorVal| vector | vhpiTimeVal | phys | of physical | vhpiVectorVal| vector | vhpiPhysVal | phys | of enumerated| vhpiVectorVal| vector | vhpiIntVal | integer | all above | vhpiStringVal| str,size | the string is null terminated | | | size is set to the number of | | | of characters in the string | (*) With the vhpiStringVal format, the one dimensional array value is | returned as a string. This format is only available for 1-dim arrays of | of discrete types. | | of access | vhpiVectorVal| vector | vhpiPtrVal | integer | (*) The vhpiVectoVal value of an array of access type returns an ordered list | of integer values each one corresponding to the access value of each | element in the array. | of records | not supported | (*) Need to iterate through the array elements before getting a value | X dimensions | vhpiVectorVal | vector,size | size field = number of array | | elements represented by the | | value | array of arrays|not supported| (*) Need to iterate through the array elements before getting a value ------------------------------------------------------------------------------ record | vhpiStringVal | str,size | size = number of characters | | in the string. | | (*) the value returned is a string, where each record element is separated by | a comma. You can also iterate through the filed and the value of each separate field ------------------------------------------------------------------------------ access | vhpiPtrVal | integer | - | - | | vhpiDerefVal | | subformat set | | integer | integer | vhpiIntVal | - | logic | | logic | vhpiLogicVal | - | string | | str,size | vhpiStringVal| - | real | | real | vhpiRealVal | - | physical | | phys | vhpiPhysVal | - | access | | integer | vhpiPtrVal | - | record | | str | vhpiStringVal| - | array | | str | vhpiStringVal| - | (*) With the format set to vhpiPtrVal, the value returned will be the | access value of the object designated by the handle. It will be returned | as an integer id. The handle type could be an allocator or a variable of | an access type. | With the format set to vhpiDerefVal, the value returned will be the | de referenced value of the object. The subformat field should be set to | a format compatible with the type of the dereferenced value; for example | if the access type is defined as access to integer, the subformat should | be set to vhpiIntVal. If the access type is an access to another access | type, the value subformat can only be set to vhpiPtrVal. | ------------------------------------------------------------------------------ 4. EXAMPLES ----------- type bit3 is array (1 to 3) of std_logic; type myrecord is record i: integer; r: real; b3: bit3; end record; -- array of records: my_recarray type my_recarray is array (0 to 2) of myrecord; -- multi-dimension: array 2 dimensions of time values type my_2dim is array (0 to 2, 1 to 3 ) of time; type word is array of (1 to 8) of bits; type mem is array (1 to 4) of word; A typical value returned for type my_array would be; ---------------------------------------------------------------------------- type | value format | value example ---------------------------------------------------------------------------- myrecord.i | vhpiIntVal | value.integer = 1 | | value.size = 1 ---------------------------------------------------------------------------- myrecord.r | vhpiRealVal | value.real = 2.0 | | value.size = 1 ---------------------------------------------------------------------------- myrecord.b3 |value.format = | value->vector | vhpiVectorVal | value.size = 3 |value.subFormat=| | vhpiLogicVal | value->vector->elemValue.logic = vhpi0 | | (value->vector+1)->elemValue.logic = vhpiX | | (value->vector+2)->elemValue.logic = vhpi1 |value.format = | vhpiStringVal | value->str = "1X0" | | size = 3 characters ------------------------------------------------------------------------------- myrecord | value.format = | not possible, need to iterate through the | vhpiObjTypeVal | selected names and get their values | | ------------------------------------------------------------------------------- my_recarray | value.format = | not possible directly, need to iterate | vhpiObjTypeVal | through each array element and for each | | array element (which is a record) iterate | | through each selected name ------------------------------------------------------------------------------- time | value.format = | value->time = { type = vhpiInt 10 ns | vhpiTimeVal | unit = vhpiFS | | utime.time.high = 0 | | utime.time.low = 10000000 } | value.format = | | vhpiStringVal| value->str = "10 ns" size = 5 ------------------------------------------------------------------------------- my_2dim | value.format = | elements laid out as (row idx, column idx) 10ns 1us 10s| vhpiVectorVal| (0,1) (0,2) (0,3) 10s 2 s 3s| value.subFormat| (1,1) (1,2) (1,3) 1fs 4fs 5ps| vhpiTimeVal | (2,1) (2,2) (2,3) | | time values are represented by 64 bits each | | my_2dim(0,1) = {vhpiInt, vhpiFS, utime.time.high = 0, utime.time.low = 10000000 } ---------------------------------------------------------------------------- word | value.format = | value->vecVal = {1,1,1,1,0,0,0,0} "1111_0000" | vhpiVectorVal | word index 1 2 3 4 5 6 7 8 | value.subformat| | vhpiLogicVal | | vhpiIntVal | value.integer = 240 | value.format = | value->str = "2#11110000" | vhpiBinStrVal | value->size = 10 ---------------------------------------------------------------------------- mem | value.format = | This is not possible, need to iterate through "1111_0000" | vhpiObjTypeVal | array element with the indexedName method, "0000_1111" | | and then ask for the value of each word in a "1010_1010" | | the objTypVal "0101_0101" | | | | ---------------------------------------------------------------------------- NOTE: since multi-dimensional arrays, array of arrays, array of records, records values are laid out as consecutive bytes, it is necessary to interpret the value according to the type of the object. In order to get partial values for an indexed or selected object, use the iteration methods. The value returned and stored in the str field is NULL terminated. However a NULL may be encountered in the string itself. The size field is set to the number of characters in the string and can be used in order to determine if the NULL character marks the end of the string. 5. The value structure ----------------------- We have a specialized time structure to be used for time values. The physical structure should be used for any other physical types. /* time value */ typedef struct vhpiTimeS { int type; /* vhpi{Real,Int,Auto] */ int unit; /* vhpiFS, vhpiPS, vhpiNS, vhpiUS, vhpiMS, vhpiS, vhpiMN, vhpiHR */ union { struct t_time { unsigned int high; unsigned int low; /* for vhpiInt or vhpiAuto */ } time; double real; /* for vhpiReal */ } utime; } vhpiTimeT; /* physical value */ /* identical to the time structure but with different field names. */ typedef struct vhpiPhysS { int type; /* vhpi{Real,Int] */ int unit; /* position of the physical unit 0 for the base unit, 1 for the first declared secondary unit, 2 for the second declared unit etc...*/ union { struct t_phys { unsigned int high; unsigned int low; /* for vhpiInt or vhpiAuto */ } phys; double real; /* for vhpiReal or vhpiAuto */ } uphys; } vhpiPhysT; /* physical types */ #define vhpiReal 0 /* real physical value format, units set by the unit field */ #define vhpiInt 1 /* integer physical value format, units set by the unit field */ #define vhpiAuto 2 /* physical value, unit determined automatically by estimating the best unit fit for the value Can be used for any physical type including time */ /* time unit values */ #define vhpiFS -15 /* femto second */ #define vhpiPS -12 /* pico second */ #define vhpiNS -9 /* nano second */ #define vhpiUS -6 /* micro second */ #define vhpiMS -3 /* milli second */ #define vhpiS 0 /* second */ #define vhpiMN 1 /* minute */ #define vhpiHR 2 /* hour */ /* vector value */ typedef struct vhpiVecvalS { /* following fields are repeated enough times to contain vector */ union { char character; /* character value */ char logic; /* IEEE std logic */ int integer; /* integer or enumeration value */ double real; /* real value */ struct vhpiPhysT *phys; /* physical value */ struct vhpiTimeT *time; /* time value */ }elemValue; } vhpiVecvalT; /* value structure */ typedef struct vhpiValueS { int format; /* vhpi[[Bin,Oct,Dec,Hex]Str,Logic,Int,Real,Phys, Char, String,Vector, Ptr,Deref,Time,ObjType]Val */ int subFormat; /* vhpi[Logic,Int,Real,Phys,Time,Ptr]Val only for vectors or access types */ int size; /* different meanings depending on the format: vhpiStringVal, vhpi(Bin...}StrVal size of the string for array type values: the number of the array elements for record type values: the number of record fields */ /* size is 1 for vhpi[Int,Real,Logic,Char, Phys,Time,Ptr,Deref]Val formats */ union { char *str; /* string value */ char character; /* character value */ char logic; /* vhpi[U,X,0,1,Z, W,L,H, -] */ int integer; /* integer value */ double real; /* real value */ struct t_vhpi_phys *phys; /* physical value */ struct t_vhpi_time *time; /* time value */ struct t_vhpi_vecval *vector; /* vector value */ } value; } vhpiValueT; /* value formats */ #define vhpiBinStrVal 1 #define vhpiOctStrVal 2 #define vhpiDecStrVal 3 #define vhpiHexStrVal 4 #define vhpiLogicVal 5 #define vhpiIntVal 6 #define vhpiRealVal 7 #define vhpiStringVal 8 #define vhpiVectorVal 9 #define vhpiCharVal 10 #define vhpiTimeVal 11 #define vhpiPhysVal 12 #define vhpiObjTypeVal 13 #define vhpiDerefVal 14 #define vhpiPtrVal 15 /* IEEE std_logic values */ #define vhpiU 0 /* uninitialized */ #define vhpiX 1 /* unknown */ #define vhpi0 2 /* forcing 0 */ #define vhpi1 3 /* forcing 1 */ #define vhpiZ 4 /* high impedance */ #define vhpiW 5 /* weak unknown */ #define vhpiL 6 /* weak 0 */ #define vhpiH 7 /* weak 1 */ #define vhpiDontCare 8 /* don't care */ ISSUES: ------ 1) values of expression Should we support to build in a VHDL interpreter for VHPI? 2)enumeration type of less than 256 values could be stored in a char (8 bits) value field 3) what is the table subset that should be used for setting a value (vhpi_put_value, vhpi_schedule_transaction 4) strin values hsould be returned as their lowercase equivalent? should we specify the case?