//------------------------------------------------------------------------------ // simapi.h - simapi.dll functions, types, and definitions (Level 1) // by NGIS II Sensor API workgroup // This header file is written in Borland C++ 4.5 version // by Auotmated Precision Inc. // //------------------------------------------------------------------------------ // Notes: The following file represents the DLL version of the SIM.H // file generated by the NGISII SIM API Committee. The major // change that was made was the removal of the class structure. // The file is "flatened." The SIMAPI macros allow for both // the SIM developer and user to compile against the same file. // The Develop adds the SIMAPI definition to their code. This // is at the top of the APIDLL.C file. Commented by Nat of ATR. // Rev Date: 11/6/96 // Rev Note: By Eun Soo LEE of Automated Precision, Inc. // Change the following 16 items. // // 1) Delete the following type definition because the return values are the error // message numbers except zero, not the true/false function status anymore. // If the return value is zero, it means the function terminates normally without // error. // typedef int BOOL; //removed! // // 2) Modify the following type definition // typedef enum // { // DONE = 1, // EXEC = 2, // FAIL = 3 // }STATUS; // ---->typedef enum // { DONE = 1, // EXEC = 2, // FAIL = 3, // PAUSE = 4, //added! // ABORT = 5, //added! // IDLE = 6 //added! // }STATUS; // // 3) Modify the following type definition // typedef enum // { // ESTOP = 1 /* what others */ // }ERROR_TYPE;*/ // ---->typedef enum // { NO_ERROR = 0, //added! // ESTOP = 1, // ABORTED = 2 //added! // /* what others */ // }ERROR_TYPE; // // 4) Query SIM monitor to see if alive. Return heartbeat number. // SIMAPI long SMAlive ( void ); // ----> SIMAPI ulong SMAlive (void); // Change the long to unsigned long. // // 5) SIM strapping function. Insert the strapping type parameter. // SIMAPI long SMStrap ( long address ); // ----> SIMAPI long SMStrap (STRAP_TYPE strap, long address); // // 6) Query the FIFO manager to verify that "num_words" words (32 bits each) is // avaiable for data storage. Why STATUS return? // SIMAPI STATUS DCallocateFifoSize(int num_words); // ----> SIMAPI int DCallocateFifoSize(int num_words); // // 7) Return Error message number. And, BINARY_CHANNELS data type used for Sync signal. // SIMAPI BOOL EVsetTriggerStore(CHANNELS SyncEvents, TRANS_TYPE type ); // ----> SIMAPI int EVsetTriggerStore(BINARY_CHANNELS SyncEvents, TRANS_TYPE type ); // // 8) Return Error message number. // SIMAPI BOOL EVsetCounterStore(ulong timer_num, ulong count_down ); // ----> SIMAPI int EVsetCounterStore(ulong timer_num, ulong count_down); // // 9) Return Error message number. // SIMAPI BOOL // ----> SIMAPI int // // 10) Return Error message number. // SIMAPI BOOL // ----> SIMAPI int // // 11) Return Error message number. // SIMAPI BOOL EVcommandedStore( void ); // ----> SIMAPI int EVcommandedStore( void ); // // 12) Return Error message number. // SIMAPI BOOL OUTsetOutput(BINARY_CHANNELS zero_channels, // ----> SIMAPI int OUTsetOutput(BINARY_CHANNELS zero_channels, // // 13) Return Error message number. // SIMAPI BOOL EXsetNumberExec(int count); // ----> SIMAPI int EXsetNumberExec(int count); // // 14) Return Error message number. // SIMAPI BOOL EXContinuous( void ); // ----> SIMAPI int EXContinuous( void ); // // 15) Return error type instead of a number. // SIMAPI int MONgetError(void); // ----> SIMAPI ERROR_TYPE MONgetError( void ); // // 16) No return value required. // SIMAPI int MONgetErrorText(char * str, int error_num); // ----> SIMAPI void MONgetErrorText( char *str, int error_num ); #ifndef __SIMAPI__ #define __SIMAPI__ /* // Standard DLL Macro Stuff // #if !defined (__SIM_API__) #define SIMAPI __declspec(dllimport) #else #define SIMAPI __declspec(dllexport) #endif */ // Changed by Eun Soo LEE, API 11/6/96 because of for using Borland C++ #if !defined (__SIM_API__) #define SIMAPI #else #define SIMAPI _export #endif // Includes // #include #include #include // Defines // //typedef int BOOL; //deleted by API. <--- (1) #ifndef ENABLE #define ENABLE 1 #define DISABLE 0 #endif #define MAX_ERROR_MESSAGE_SIZE 256 #ifndef ulong #define ulong unsigned long #endif // Enumerations // typedef enum { COLD = 1, HOT = 2 }RESTART_TYPE; typedef enum { DUAL_PORT_RAM = 1, IO_BUS = 2, SERIAL_PORT = 3, PARALLEL_PORT = 4 }STRAP_TYPE; typedef enum { TRANS_0 = 1, TRANS_1 = 2, TRANS_RISE = 3, TRANS_FALL = 4 }TRANS_TYPE; typedef enum { GREATER_THAN = 1, LESS_THAN = 2, GREATER_EQUAL = 3, LESS_EQUAL = 4, EQUAL = 5 }COMPARE_TYPE; /*typedef enum <--- (2) { DONE = 1, EXEC = 2, FAIL = 3 }STATUS;*/ typedef enum { DONE = 1, EXEC = 2, FAIL = 3, PAUSE = 4, ABORT = 5, IDLE = 6 }STATUS; /*typedef enum <--- (3) { ESTOP = 1 // what others = }ERROR_TYPE;*/ typedef enum { NO_ERROR = 0, ESTOP = 1, ABORTED = 2 /* what others */ } ERROR_TYPE; // Structures // // -------------------------------------------------------------------------------- // // SIM enumerated definitions for // // transition types // compare operators // channels // manufactures channels (low order byte are the sync bus bits) // // -------------------------------------------------------------------------------- // Structures // typedef struct CHANNELS // This is bit field definition { unsigned Channel31 :1; // MSB unsigned Channel30 :1; unsigned Channel29 :1; unsigned Channel28 :1; unsigned Channel27 :1; unsigned Channel26 :1; unsigned Channel25 :1; unsigned Channel24 :1; unsigned Channel23 :1; unsigned Channel22 :1; unsigned Channel21 :1; unsigned Channel20 :1; unsigned Channel19 :1; unsigned Channel18 :1; unsigned Channel17 :1; unsigned Channel16 :1; unsigned Channel15 :1; unsigned Channel14 :1; unsigned Channel13 :1; unsigned Channel12 :1; unsigned Channel11 :1; unsigned Channel10 :1; unsigned Channel9 :1; unsigned Channel8 :1; unsigned Channel7 :1; unsigned Channel6 :1; unsigned Channel5 :1; unsigned Channel4 :1; unsigned Channel3 :1; unsigned Channel2 :1; unsigned Channel1 :1; unsigned Channel0 :1; // LSB }CHANNELS;// 32 Bits typedef struct BINARY_CHANNELS // This is bit field definition { unsigned ManBit23 :1; // MSB unsigned ManBit22 :1; unsigned ManBit21 :1; unsigned ManBit20 :1; unsigned ManBit19 :1; unsigned ManBit18 :1; unsigned ManBit17 :1; unsigned ManBit16 :1; unsigned ManBit15 :1; unsigned ManBit14 :1; unsigned ManBit13 :1; unsigned ManBit12 :1; unsigned ManBit11 :1; unsigned ManBit10 :1; unsigned ManBit9 :1; unsigned ManBit8 :1; unsigned ManBit7 :1; unsigned ManBit6 :1; unsigned ManBit5 :1; unsigned ManBit4 :1; unsigned ManBit3 :1; unsigned ManBit2 :1; unsigned ManBit1 :1; unsigned ManBit0 :1; unsigned Sync6 :1; unsigned Sync5 :1; unsigned Sync4 :1; unsigned Sync3 :1; unsigned Sync2 :1; unsigned Sync1 :1; unsigned Sync0 :1; unsigned SyncF :1; // LSB }BINARY_CHANNELS;// 32 Bits // Make all the Functions "C" Calling Program // Pops the parameter from the stack #ifdef __cplusplus extern "C" { #endif // Routines // // SIMManager -- SIMManager -- SIMManager -- SIMManager -- SIMManager -- SIMManager // SIMManager -- SIMManager -- SIMManager -- SIMManager -- SIMManager -- SIMManager // // Restart SIM monitor or firmware, return 0=alive SIMAPI long SMRestart ( RESTART_TYPE reset ); // Query SIM monitor to see if alive. Return heartbeat number. <--- (4) //SIMAPI long SMAlive ( void ); // Query SIM monitor to see if alive. Return heartbeat number. SIMAPI ulong SMAlive ( void ); // Physical access information, return 0 = worked, -1 err <--- (5) //SIMAPI long SMStrap ( long address ); // Physical access information, return 0 = worked, otherwise error mes sage number SIMAPI long SMStrap ( STRAP_TYPE strap, long address ); // Return 0 = ok, otherwise return the manufacturer's error message number. // attempts to load & run sim executable, not a job SIMAPI long SMLoad ( char * fulllpathfilename ); // Return name of SIM manager SIMAPI void SMName ( char * name ); // Return ASCII text of error message SIMAPI void SMErrorMsg ( int errnum, char* errorMsg ); // // CONFIGURATION // -------------------------------------------------------------- // // For level one use "ini" file for configuration information // // Expect that a calibration procedure would generate entries // into this file. At Level 1, this mechanism is transparent between // in that vendors may use different ini file format and parameter // entries SIMAPI long SMConfig( char * intputFilename); // // SIM TASK MANAGEMENT // ----------------------------------------------------------------- // Sim Task will be identified by a long integer even though we have // only one SimTask at a time // SIMAPI long SMCreateSimTask ( void ); SIMAPI long SMRestartSimTask ( long simId ); SIMAPI long SMStartSimTask ( long simId ); SIMAPI long SMStopSimTask ( long simId ); SIMAPI long SMDeleteSimTask ( long simId ); // SIMTask -- SIMTask -- SIMTask -- SIMTask -- SIMTask -- SIMTask -- SIMTask // SIMTask -- SIMTask -- SIMTask -- SIMTask -- SIMTask -- SIMTask -- SIMTask // // -------------------------------------------------------------------------------- // // SIM TASK CLASS DEFINITION LEVEL 1 // // // SimTask Method Prefixes: // Config : CFG - none in level 1, configuring done globally in manager // DataSetup : DC // Event : EV // Exec : EX - single versus blocks of data storage // Output (to hardware) : OUT // Monitor : MON // Data Retrieval : DR // // -------------------------------------------------------------------------------- // // DATA SETUP // -------------------------------------------------------------- // The FIFO is the mechanism in which the SIM stores data and the user // retrieves data. For Level 1, the FIFO is a buffering data structure // with fixed length data records defined a priori. Values are inserted // after every SIM cycle in which a trigger occurred. For Level1, there // are no variable length packets. A "snapshot" or capture of all // programmed channels is stored in the FIFO even if the channel was not // triggered. If a channel was not triggered, a "no value" is still // inserted into the corresponding channel record in the FIFO // buffer. FIFO data storage is based on the assumption of only a single // SIMtask running on the SIM at a time. // The setup of the fifo describes what data to capture after a trigger // =. The setup enumerates the "channels" to capture and the "types" of // data to store -- raw, processed, and manufacturing data. A user // programs the setup by providing channel bit masks, each enabled bit // signifying that channel to be recorded, where a "raw" data mask // signifying which channels to capture raw data, a "processed" data mask // signifying which channels to capture processed data, and a // "manufacturing" data mask with the lower byte signifying sync bus // signals to capture and the upper bytes defines as per manufacturers // specification, for example, io capture. // // Return 0=success, otherwise return the manufacturer's error message number. // SIMAPI int DCsetup(ulong raw, // mask for raw data per channel ulong processed, // mask for processed data per channel ulong manufacturer_data // 32 bits by 32 each 4 byte words ); // // Setup returns number of bytes in fifo // SIMAPI int DCqueryFIFORecordLength( void ); // Query the FIFO manager to verify that "num_words" words (32 bits each) is // avaiable for data storage // SIMAPI STATUS DCallocateFifoSize(int num_words); <--- (6) SIMAPI int DCallocateFifoSize( int num_words ); // Query the maximum size FIFO in words (32 bits each) SIMAPI int DCgetMaxFifoSize( void ); // Example: // zyx yx v-----sync bit // setup( 00011, 0010, 0001); // // FIFO // // --------------------------------- // | xraw | yraw | yproc | manu | // --------------------------------- // Byte 0 4 8 12 16 // Type long long float 32 bits // // ----------------------------------- // Manuf | | | | Sync | // 1 ----------------------------------- = // Byte 0 1 2 3 4 // // Sync Byte - :0 Fail // :1 S0 // :2 S1 // :3 S2 // :4 S3 // :5 S4 // :6 S5 // :7 S6 // // // EVENT TRIGGER PROGRAMMING // -------------------------------------------------------------- // // Channel programming by identifying triggering events. // // e.g., if S0 = 0 then store var endif // // - Level 1 identifies stock transitions in the API // // These canned (i.e., enumerated list) or stock transitions are mapped // on a per channel basis. // // Each channel can have a transition or threshold type associated with // it. Programming associates a trigger to a channel. All data // as specified in the FIFO data setup is captured when any trigger. //--------------------------------------------------------------------- // Definition of Trigger Store // // SIMAPI BOOL EVsetTriggerStore(CHANNELS SyncEvents, TRANS_TYPE type ); <--- (7) SIMAPI int EVsetTriggerStore(BINARY_CHANNELS SyncEvents, TRANS_TYPE type ); //------------------------------------------------------------- // Example : // // We want to have a trigger store when Sync1 goes // from 0 -> 1. //------------------------------------------------------------- // static BINARY_CHANNELS sync_channel; // Clears all channels // BOOL ok; // // sync_channel.Sync1 = 1; // // ok = SetTriggerStore( sync_channel, TRANS_RISE ); //------------------------------------------------------------- //--------------------------------------------------------------------- // Definition of Counter Store (ms) // // SIMAPI BOOL EVsetCounterStore(ulong timer_num, ulong count_down ); <--- (8) SIMAPI int EVsetCounterStore( ulong timer_num, ulong count_down ); //------------------------------------------------------------- // Example : // // We want to have a timer store when timer 2 counts // down from 100 ms //------------------------------------------------------------- // BOOL ok; // // ok = SetCounterStore( 2, 100 ); //------------------------------------------------------------- //--------------------------------------------------------------------- // Definition of Threshold Store Raw // //SIMAPI BOOL <--- (9) SIMAPI int EVsetThresholdStoreRaw( CHANNELS channel, COMPARE_TYPE comparison, ulong value, ulong reset); //------------------------------------------------------------- // Example : // // We want to have a threshold store when channel 1 // raw value goes above 500 and reset when it gets // below 400 //------------------------------------------------------------- // static CHANNELS channel; // Clears all channels // BOOL ok; // // channel.Channel1 = 1; // // ok = SetTriggerStore( channel, GREATER_THAN, 500, 400 ); //------------------------------------------------------------- //--------------------------------------------------------------------- // Definition of Threshold Store Processed // //SIMAPI BOOL <--- (10) SIMAPI int EVsetThresholdStoreProcessed( CHANNELS channel, COMPARE_TYPE comparison, float value, float reset); //------------------------------------------------------------- // Example : // // We want to have a threshold store when channel 1 // processed value goes below 23.1 and reset when it gets // above 25.4 //------------------------------------------------------------- // static CHANNELS channel; // Clears all channels // BOOL ok; // // channel.Channel1 = 1; // // ok = SetThresholdStoreProcessed( channel, // LESS_THAN, // 23.1, // 25.4 ); //------------------------------------------------------------- //--------------------------------------------------------------------- // Definition of Commanded Store, user initiates event trigger // to cause data storage to FIFO // SIMAPI BOOL EVcommandedStore( void ); <--- (11) SIMAPI int EVcommandedStore( void ); //------------------------------------------------------------- // Example : // // We want an immediate store //------------------------------------------------------------- // BOOL ok; // // // ok = ImmediateStore(); //------------------------------------------------------------- // // OUTPUT // -------------------------------------------------------------- // // Output allows the user to enable a channel to become zeroed, oned or toggled // upon an event trigger. Typically, this hardware signal is used to notify // a motion board or other slaved piece of hardware that an event has occured // SIMAPI BOOL OUTsetOutput(BINARY_CHANNELS zero_channels, <--- (12) SIMAPI int OUTsetOutput(BINARY_CHANNELS zero_channels, BINARY_CHANNELS one_channels, BINARY_CHANNELS toggle_channels); // ------------------------------------------------ // Example // // sync2 => 0 // toggle Man16 // all others untouched // // BC zero_ch=0; // BC one_ch; // BC toggle_ch; // BOOL ok; // // zero_chan.Sync2=ENABLE; // toggle_ch.ManBit16=ENABLE; // // ok=SetOutput(zero_ch, one_ch, toggle_ch); // // EXEC // -------------------------------------------------------------- // // Execution specifies the number of executions to attach to the event condition. // //SIMAPI BOOL EXsetNumberExec(int count); <--- (13) SIMAPI int EXsetNumberExec(int count); //SIMAPI BOOL EXContinuous( void ); <--- (14) SIMAPI int EXContinuous( void ); // ------------------------------------------------ // Example // // We want 100 SIM task executions. // // BOOL ok; // // ok = EXsetNumberExec(100); // // Comments // // 1) Check that FIFO size is not execeeded, otherwise // data could be overwritten and lost. // // 2) Level 2 will identify failure detection // // MONITOR // -------------------------------------------------------------- // // Monitor is used to query the SIM task concerning its data and status // All queries return long words, defined as 32 bits; // fetch n words (32bits each) where n is defined as the // number of enabled channels SIMAPI int MONgetData( CHANNELS raw_channels, CHANNELS processed_channels, BINARY_CHANNELS manufacturers_channels, void * loc, int record_sizes_match_check); // General purpose function to return status SIMAPI STATUS MONgetStatus(void); // If aborted task, SIM will return error message //SIMAPI int MONgetError(void); <--- (15) SIMAPI ERROR_TYPE MONgetError( void ); // Convenience function : return error message as ASCII text // user input error number, and SIM returns error string //SIMAPI int MONgetErrorText(char * str, int error_num); <--- (16) SIMAPI void MONgetErrorText( char *str, int error_num ); // // QUERY FUNCTIONS // // SIM manager has started a task and task has sucessfully completed SIMAPI int MONisDone( void ); // SIM manager has started a task and task is executing normally SIMAPI int MONisExecuting( void ); // SIM manager has started a task and task has aborted SIMAPI int MONisFailed( void ); // SIM task is configured and ready for SIM manager to run SIMAPI int MONisReady( void ); // // DATA RETRIEVAL // -------------------------------------------------------------- // // Data Retrieval is of fixed packet sizes as defined in FIFO data setup. // Retrieve entire packet not individual pices of data. // // stores "num" records from the FIFO into loc (which better point // to a large enough memory space). Number of stored records in FIFO // is updated to reflect this retrieval. SIMAPI int DRretrieveRecrods( int num, void * loc, int record_size_match_check); // returns the number of stored records in the FIFO SIMAPI int DRgetNumRecords( void ); // End Routines // #ifdef __cplusplus }// extern "C" #endif #endif //__SIMAPI__