/* Copyright SIMetrix Technologies Ltd. 2007, all rights reserved. Header SxRemoteDataInterface.h created 11.05.2007 Library: Notes: SIMetrix Remote Data Interface ============================== Provides a means of obtaining simulation data from a running instance of SIMetrix. This header file provides the bulk of the documentation for the interface. See also the application RDIConsole which demonstrates how to use the interface. The interface has been carefully designed to be tolerant of compiler settings, in particular the structure alignment. It is also uses only 'C' language syntax for widest compatibility. Further the interface has provision for future expansion without losing compatibility in either direction - forward or backward. To use the interface, an application must dynamically load the DLL sxrdif.dll (Windows) or libsxrdif.so shared library (Linux) and link to the function srd_InitialiseInterface. See SRD_InitialiseInterfaceProc below for args and return type. This function when called fills a SRD_Interface struct with the function pointers that make up the interface. See SRD_Interface definition below for description of the functions. Basic information about SIMetrix data handling ============================================== SIMetrix organises simulation data into 'groups'. Each group has a name which may not contain white space. Group names are usually allocated by SIMetrix and have a name related to the analysis type. E.g. tran1, ac4, op3, simplis_pop3. There is always a group called 'global'. This is used to store vectors created on the command line as well as some global data used by SIMetrix scripts. Groups contain 'vectors'. Vectors can have real, complex or string types and may contain 0 or more elements. Vectors may also be 'multi-division'. Multi-divsion vectors are created for multi-step runs such as Monte Carlo. They are similar to two-dimensional arrays but differ in that the 'row length' is not constant. Multi-division vectors are explained in the script reference manual. Most simulation numeric vectors have a 'reference'. The reference is the x-values that is the data used to specify the x-axis co-ordinates. For analog vectors (vectors created by the analog simulator) the reference is shared. In a transient analysis for example, the reference is the TIME vector and as all voltages and currents in the simulation are re-calculated at every time point, all voltages and currents share the same x-values. However, this isn't the case for digital values as these are only created when there is an event. So digital vectors do not share the TIME vector and each has its own. Finally, although analog vectors currently created by the simulator always share a reference vector, this should never be assumed. Some vectors are 'aliasses'. An alias is actually a string that represents an arithmetic expression. The numeric value of the vector is obtained by evaluating the expression. By default when the data for an aliassed vector is requested (using getvectordata) the evaluation will occur and numeric data will be returned. There is an option allowing the actual string expression to be examined. Aliasses are used to store currents where it is possible to calculate that current from other stored values. They save both disc space and simulation time. The functions in this interface provide access to all data stored in groups. */ #ifndef SxRemoteDataInterface_h_33 #define SxRemoteDataInterface_h_33 /*---------- Macro definitions ---------*/ #define SRD_MAJOR_VERSION 1 #define SRD_MINOR_VERSION 1 /* Exported function */ #define SRD_INITIALISE_INTERFACE "srd_InitialiseInterface" /*--------------------------------------*/ /*---------- Type definitions ----------*/ typedef unsigned char SRD_BOOL ; typedef enum SRD_ErrorCode { SRDE_Ok, SRDE_ConnectionClosed, /* Connection to SIMetrix is broken. Usually because SIMetrix is not running*/ SRDE_BadHandle, /* An invalid handle was passed to an interface function */ SRDE_BadVectorData, /* Bad pointer to SRD_VectorData passed to destroyData */ SRDE_BadVersion, /* Interface version is not compatible */ SRDE_BadArgs, /* Arguments passed to interface function bad. */ SRDE_NoGroup, /* Group name passed does not exist*/ SRDE_AllocFail, /* Allocation failed in SIMetrix */ SRDE_BadDivisionIndex, /* Division index out of range */ SRDE_BadOffset, /* Offset out ofrange */ SRDE_BadXVec, /* Request for X-values but vector does not have any x-values (aka 'reference' see notes)*/ SRDE_NoVec, /* Vector name unknown */ SRDE_BadAlias, /* Alias could not be resolved */ SRDE_BadCommand, /* Bad command sent to SIMetrix. (internal error) */ SRDE_Exception, /* SIMetrix threw an exception while handling the interface request (internal error) */ SRDE_Unknown, /* unknown error (internal error) */ SRDE_UnexpectedReply, /* Unexpected reply from SIMetrix (internal error) */ SRDE_UnexpectedDataType, /* Interface returned an unexpected data type (internal error) */ SRDE_UnsupportedXDataType, /* Interface returned an unexpected data type for the x-values (internal error) */ SRDE_SXRDIF_Incompatible, /* Wrong version of sxrdif is being used for SIMetrix */ // Require SRD_MINOR_VERSION>0 SRDE_NoSxCommandInterface, /* Call to sendCommand without calling openSxCommand */ SRDE_SxCommandFailed, /* Call to sendCommand failed */ SRDE_SxCommandBusy, /* sendCommand failed as SIMetrix is busy - e.g. is running a simulation. Try again */ /* Some compilers allow variable length enums - this forces this one to be 4 bytes */ SRDE_ForceFourByte=100000L } SRD_ErrorCode ; /* Type of exported function */ typedef SRD_ErrorCode (*SRD_InitialiseInterfaceProc)(struct SRD_Interface *iface, int *major, int *minor) ; typedef enum SRD_VectorDataOptions { SRDV_Y, /* Return Y data only*/ SRDV_X, /* Return X data only */ SRDV_XY, /* Return both X and Y data */ SRDV_AliasLiteral, /* If data is an alias, don't resolve the alias, just return its literal string value */ /* Some compilers allow variable length enums - this forces this one to be 4 bytes */ SRDV_ForceFourByte=100000L } ; typedef enum SRD_OpMode { SRDO_None, /* Don't return operating point values */ SRDO_Literal, /* Return op values for non-aliassed vectors only */ SRDO_All, /* return op values for all vectors. WARNING: can be a resource and time hungry operation */ /* Some compilers allow variable length enums - this forces this one to be 4 bytes */ SRDO_ForceFourByte=100000L } SRD_OpMode ; typedef enum SRD_DataType { SRDD_Real, /* Data of type double */ SRDD_Complex, /* Data of type SRD_Complex */ SRDD_String, /* Data of type const char * */ SRDD_Unknown, /* Some compilers allow variable length enums - this forces this one to be 4 bytes */ SRDD_ForceFourByte=100000L } SRD_DataType ; /* Used to pass data back from getGroupNames function */ typedef struct SRD_Strings { const char **strings ; /* Array of strings. Both array and the string data are owned by the interface */ int numStrings ; /* Number of elements in strings */ } SRD_Strings ; /* Used to return information about a single vector following call to getVectorInfo */ typedef struct SRD_VectorInfo { /* operating point value if requested This is the first point in the vector. See SRD_Options::opMode */ double scalarVal ; /* The total number of points in the vector across all divisions */ int totalLength, /* Number of divisions. Multi-step runs such as Monte Carlo create multi-div vectors in which case this value will be non-unity. See script manual for details of multi division vectors */ numDivisions, /* Index into SRD_VectorInfoArray::vectorInfo of 'reference vector'. The reference vector contains the X-values, e.g. 'Time' for a transient analysis. This is only valid when calling getVectorInfo with vecName NULL - i.e. when all vectors are returned. If vecName is specified, SRD_VectorInfoArray::vectorInfo points to only a single value and so the index has no meaning. This value will be -1 if the vector has no reference. It will also be -1 for vectors that do have a reference but the reference is not shared. This happens with digital data generated by the event driven digital simulator. For these the reference data may only be obtained by specifying SRDV_XY or SRDV_X in the call to GetVectorData. For analog vectors, the reference is usually the same for all vectors and so greatest efficiency is achieved by fetching it once and sharing the data subsequently. */ refIndex ; /* -1 if no ref or unnamed */ /* The name of the vector. Can have any ASCII printable character except white space. */ const char *name ; /* dataType: real, complex or string */ SRD_DataType dataType ; /* The vector has a reference - e.g. x-values. (See above). Note that this can be true even if refIndex above is -1 - see refIndex comments for explanation. */ SRD_BOOL hasRef, /* Vector is an alias. See general notes for an explanation */ isAlias, /* set true is an alias evaluation failed when calculating scalarVal - see above */ aliasFailed, /* unused - for future expansion */ spare1 ; /* Physical type name. One of the following: PT_UNKNOWN PT_NONE PT_VOLT PT_AMP PT_SECOND PT_HERTZ PT_OHM PT_SIEMEN PT_FARAD PT_HENRY PT_JOULE PT_WATT PT_COULOMB PT_WEBER PT_VOLT2 PT_VOLT2T PT_VOLTSQRT PT_AMP2 PT_AMP2T PT_AMPSQRT PT_VOLTSPERSEC PT_CONSTANT PT_CELSIUS PT_DIGITAL PT_DEFAULT Other may be added in the future */ char physTypeName[24] ; /* For future expansion */ char unused[24] ; } SRD_VectorInfo ; typedef struct SRD_VectorInfoArray { SRD_VectorInfo *vectorInfo ; /* Array of SRD_VectorInfo objects. Owned by interface */ int numElems ; /* Number of elements in vectorInfo */ } SRD_VectorInfoArray ; typedef struct SRD_Options { /* GetVectorInfo function can optionally return a single scalar value for the requested vector or vectors. The single value is the first element of the vector and is typically used for operating point values for transient analyses. This defines that operation. See SRD_OpMode description */ SRD_OpMode opMode ; /* What data to return from getVectorData function. See SRD_VectorDataOptions for details */ SRD_VectorDataOptions dataOptions ; int divisionIndex, /* getVectorData function. For multi-div vectors. >=0 */ offset ; /* getVectorData function. Element index of start value. >=0 */ /* Set this when calling getVectorData if the data is to be used for incremental plotting This is a 'hint' value. It doesn't change the data that is returned but instructs SIMetrix to store the data internally in a manner that is more efficient for incremental plots */ SRD_BOOL incremental ; /* For future expansion */ char unused[31] ; } SRD_Options ; typedef struct SRD_Complex { double real, imag ; } SRD_Complex ; /* Object used to return data from call to getVectorData */ typedef struct SRD_VectorData { /* Data arrays. Note that these can be very large. 100MBytes is not uncommon and blocks in excess of 1GByte are possible albeit rare. Large objects (currently > 64K) are pointers to shared blocks (returned by MapViewOfFile in Windows and shmat in Linux) and these are allocated and loaded by the SIMetrix process directly. Because of the potential size of these blocks, the calling application should avoid making deep copies if this is possible. */ union { double *realData ; SRD_Complex *complexData ; const char **stringData ; } d ; /* Reference data - i.e. X-values. Only set if requested by dataOptions set to SRDV_X or SRDV_XY */ double *refData ; /* Number of elements in array */ int numElems ; /* Real, complex or string */ SRD_DataType dataType ; /* For future expansion */ char unused[32] ; } SRD_VectorData ; /* Interface function pointers */ typedef struct SRD_Interface { /* openInterface This function must always be called first before any other action. It creates a handle that is required for calling all other functions. You may have multiple interfaces open at any time. Some functions need to allocate memory for the returned results. This memory is associated with the handle value and will be destroyed when closeInterface is called on that handle. */ SRD_ErrorCode (*openInterface)(int ident, void **handle) ; /* closeInterface Close the interface and releases any memory allocated by it. closeInterface must ultimately be called for each call to openInterface. Failure to do so will result in a memory leak. */ SRD_ErrorCode (*closeInterface)(void *handle) ; /* getGroupNames Returns an array of strings providing a the data group names currently available. */ SRD_ErrorCode (*getGroupNames)(void *handle, SRD_Strings **strings) ; /* getVectorInfo Returns information about a vector or all the vectors in a group. Usually this function would be called with vecName NULL in which case all vectors in groupName will be returned. This is the only way of finding the vector names available. 'options' may be used to specify the 'operating point' option. When enabled, a single scalar value for the vector is returned in addition to the remaining information. This is the first point of the data and in a transient run is usually the "operating point" value commonly used to annotate schematics with bias point data. */ SRD_ErrorCode (*getVectorInfo)(void *handle, const char *groupName, const char *vecName, const SRD_Options *options, SRD_VectorInfoArray **vectorInfo) ; /* getVectorData Returns the vector's data. See SRD_VectorData and SRD_Options for a full explanation. */ SRD_ErrorCode (*getVectorData)(void *handle, const char *groupName, const char *vecName, const SRD_Options *options, SRD_VectorData **data) ; /* destroyData Destroys the data objects created by getVectorData (SRD_VectorData), getVectorInfo (SRD_VectorInfoArray) or getGroupNames (SRD_Strings). Pass one of SRD_VectorData, SRD_VectorInfoArray or SRD_Strings pointers to the destroyData function. The function will determine the type of object passed then delete it and any data associated with it. Note that this only destroys data stored in the interface and does not communicate with SIMetrix. closeInterface will also destroy all data not explicitly destroyed by destroyData. */ SRD_ErrorCode (*destroyData)(void *handle, void *data) ; /* Everything after this point requires SRD_MINOR_VERSION>0 or SRD_MAJOR_VERSION>1 The srd_InitialiseInterface function returns major and minor version values and these should be checked before calling the following */ /* openSxCommand Commands can be sent to SIMetrix using sendCommand. A successful call to this function must be made before sendCommand may be used. This only needs to be called once */ SRD_ErrorCode (*openSxCommand)(void *handle) ; /* sendCommand Send a command to SIMetrix */ SRD_ErrorCode (*sendCommand)(void *handle, const char *command) ; char unused[32] ; } SRD_Interface ; /*--------------------------------------*/ /*---------- Extern data ---------------*/ /*--------------------------------------*/ /*--------- Extern functions -----------*/ /*--------------------------------------*/ /*--------- Inline functions -----------*/ /*--------------------------------------*/ #endif