The SG_VALU data structure is designed to accommodate data values of an attribute after SansGUI Data Type Funneling, explained in the previous chapter.
The SG_VALU data structure contains the following elements:
Data Type: to indicate the data type of the values in the data array.
Dimension: to provide the size information about the data array, up to three dimensions.
Data Array: to store the actual data values, according to the data type specified.
The implementation of SG_VALU structure in the C programming language (found in SGdll.h in subdirectory inc under the installation directory) is listed as following:
typedef struct SG_VALU_tag
{
SG_CONST UINT nType;
SG_CONST INT iSize;
SG_CONST INT iCols;
INT iRows;
union
{
void *SG_CONST vData;
INT *SG_CONST iData;
FLOAT *SG_CONST fData;
DOUBLE *SG_CONST dData;
TCHAR *SG_CONST cData;
TCHAR *SG_CONST *SG_CONST sData;
};
} SG_VALU;
SansGUI has been built with 8 byte packing (default in MSVC and CVF) for member alignment in all data structures. However, because the members are either integer quantities or pointers, they are all 4 bytes implemented in 32-bit systems. SG_CONST is a macro that should be treated as const. The INT, UINT, FLOAT, DOUBLE and TCHAR are macros defined as int, unsigned int, float, double and char, respectively. They may be defined with system dependencies in the header file SGtypes.h in directory inc under the installation directory. The usages of the elements are explained in the following sections:
This structure member contains the type information regarding the data array. In addition to the types defined in the Object Data Representation section in Chapter 1, nType is also used for the scope of the attribute/variable and the status of the value:
SG_TYPE_INP: This scope bit indicates that the values are for an input attribute/variable. The values are entered by the user and shall not be modified during simulation runs.
SG_TYPE_OUT: This scope bit indicates that the values are for an output attribute/variable. The values are generated by the simulator or user overriding functions.
SG_TYPE_INO: This scope bit indicates that the values are for an input/output attribute/variable. The values may be entered by the user, initialized by the simulator or user overriding functions, and modified programmatically.
SG_TYPE_HID: This scope bit indicates that the values are for a hidden attribute/variable. The values are handled programmatically and shall not require any user input. They can be revealed in a service session in the SansGUI Run-Time Environment.
SG_TYPE_PORT: This scope bit indicates that the values are for a port attribute/variable. It is similar to SG_TYPE_INO except that they are handled separately in the SansGUI environment.
SG_TYPE_NOV: This status bit indicates that the type of the values has been determined and yet the data array has not been initialized, thus, containing no value.
SG_TYPE_COL: This status bit indicates that the multidimensional data array is to be treated as column-major order (as in Fortran). It is in row-major order (as in C) when this bit is not set.
The types defined in the Object Data Representation section can be obtained by performing a bitwise-AND operation of nType and SG_TYPE_MASK:
nType & SG_TYPE_MASK
Alternatively, you can use the modulo operation of nType and SG_TYPE_MASK to obtain the actual type:
nType % SG_TYPE_MASK
The scope and status are fetched by the certain bit as stated above. There are predicate macros, started with SG_IsNull, defined in SGdll.h header file for your convenience.
These three integer values specify the dimension of the data array. In general, iSize indicates the total size of the data array, iCols indicates the number of columns, and iRows indicates the number of rows in the multi-dimensional array. When the data array is 3-dimensional, the third dimension is represented by the number of sheets, which can be calculated by:
Number of sheets = iSize / iCols / iRows
There are, however, some issues in specific types of data arrays:
For SG_TYPE_CHAR, the value of iSize indicates the actual number of characters allocated in the memory for the string, including the terminating NULL character. The value of iCols is normally iSize - 1 for the actual length of the string and iRows is always 1. Notice that iRows is not declared as a constant because SansGUI allows the resize functions in the SansGUI Application Programming Interface (API) to send a request to allocate a new string with the length set in iRows. When a resize function returns, SansGUI checks if the value in iRows differs from that of iCols. If they are different, SansGUI will allocate a new string and copy as many characters in the old string to the new one as possible. Therefore, if you do not want the string to be resized, make sure that you set iRows (originally 1) equal to iCols before returning from the resize function. This data type can only be assigned to a cell attribute with a regular string value.
For SG_TYPE_STR, these three numbers indicates the dimensions of the pointers to fixed length strings (jagged character arrays). Strings of this type cannot be resized.
SG_TYPE_URL and SG_TYPE_REF are handled in the same way as SG_TYPE_STR.
For SG_TYPE_DATE, the value of iSize indicates the number of integers allocated, not the number of date elements in the data array. One can obtain the actual number of date elements by using the pre-defined macro SG_INTS_DATE:
Number of date elements = iSize / SG_INTS_DATE
For SG_TYPE_TIME, the value of iSize indicates the number of integers allocated, not the number of time elements in the data array. One can obtain the actual number of time elements by using the pre-defined macro SG_INTS_TIME:
Number of time elements = iSize / SG_INTS_TIME
For SG_TYPE_LINK, the value of iSize is always the same as defined by the macro SG_INTS_LINK.
The data array stores the values of an attribute/variable. From the data structure, it is a union of different typed pointers pointing to the beginning of the data array.
vData: is defined as a void pointer. It is used by SansGUI only. The simulator and the user overriding functions normally should not referred to this pointer.
iData: is defined to point to an array of integers. It is used when the type indicates SG_TYPE_INT, SG_TYPE_DATE, SG_TYPE_TIME, SG_TYPE_QUAL, or SG_TYPE_LINK.
fData: is defined to point to an array of single precision floating point numbers. It is used when the type is SG_TYPE_FLT.
dData: is defined to point to an array of double precision floating point numbers. It is used when the type is SG_TYPE_DBL.
cData: is defined to point to an array of characters terminated with a null-character. It is used when the type is SG_TYPE_CHAR.
sData: is defined to point to an array of jagged length strings. It is used when the type is SG_TYPE_STR, SG_TYPE_URL, or SG_TYPE_REF.
To access the third integer from the data array (0-based), for example, use
SG_VALU* pValue;
/* initialize pValue to point to
* a proper value structure
*/
INT iThird = pValue->iData[2];
The data structure and the memory allocation module in SansGUI have been implemented in the C programming language. An include file named SGdllf.h is provided for users who program in Fortran. The data structure TYPE in Fortran 90 and the POINTER feature in Compaq Visual Fortran (CVF) are used to access the structure members. For details on these structure members, please consult the SG_VALU Structure in C section above.
type SG_VALU
sequence
integer :: nType
integer :: iSize
integer :: iCols
integer :: iRows
integer(4) :: vData
end type SG_VALU
and there are access pointers defined in the header file for convenience.
integer, dimension(*) :: iData
POINTER(PTR_iData, iData)
real*4 dimension(*) :: fData
POINTER(PTR_fData, fData)
real*8 dimension(*) :: dData
POINTER(PTR_dData, dData)
character, dimension(*) :: cData
POINTER(PTR_cData, cData)
We explicitly declare integer(4) for all pointers in the data structure. Being different from the C implementation, the variant types of data array can be referred to via the vData pointer. Suppose zValues is an element of SG_VALU type, we can access the third integer from it (1-based) as:
integer :: iThird
PTR_iData = zValues%vData
iThird = iData(3)
More elaborated examples can be found in the next section SG_OBJ Data Structure and the DLL Function Prototype section in Chapter 3.
|
|
SansGUI Modeling and Simulation Environment Version 1.2
Copyright © 2000-2003 ProtoDesign, Inc. All rights reserved.