qspy.h

Go to the documentation of this file.

 
#ifndef QSPY_H
#define QSPY_H
 
#define QSPY_VER "6.9.3"
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum {
    QSPY_ERROR,
    QSPY_SUCCESS
} QSpyStatus;
 
typedef enum {
    QSPY_ATTACH = 128,    
    QSPY_DETACH,          
    QSPY_SAVE_DICT,       
    QSPY_SCREEN_OUT,      
    QSPY_BIN_OUT,         
    QSPY_MATLAB_OUT,      
    QSPY_SEQUENCE_OUT,    
    QSPY_SEND_EVENT,      
    QSPY_SEND_AO_FILTER,  
    QSPY_SEND_CURR_OBJ,   
    QSPY_SEND_COMMAND,    
    QSPY_SEND_TEST_PROBE  
    /* ... */
} QSpyCommands;
 
typedef struct {
    uint8_t const *start; 
    uint8_t const *pos;   
    uint32_t tot_len;     
    int32_t  len;         
    uint8_t  rec;         
} QSpyRecord;
 
typedef struct {
    uint16_t version;
    uint8_t endianness;
    uint8_t objPtrSize;
    uint8_t funPtrSize;
    uint8_t tstampSize;
    uint8_t sigSize;
    uint8_t evtSize;
    uint8_t queueCtrSize;
    uint8_t poolCtrSize;
    uint8_t poolBlkSize;
    uint8_t tevtCtrSize;
    uint8_t tstamp[6];
} QSpyConfig;
 
typedef uint64_t KeyType;
typedef uint32_t SigType;
typedef uint64_t ObjType;
 
/* limits */
enum {
    QS_RECORD_SIZE_MAX  = 512,  /* max QS record size [bytes] */
    QS_LINE_LEN_MAX     = 1000, /* max length of a QSPY line [chars] */
    QS_FNAME_LEN_MAX    = 256,  /* max length of filenames [chars] */
    QS_SEQ_LIST_LEN_MAX = 300,  /* max length of the Seq list [chars] */
    QS_DNAME_LEN_MAX    = 64,   /* max dictionary name length [chars] */
};
 
/* pointer to the callback function for customized QS record parsing  */
typedef int (*QSPY_CustParseFun)(QSpyRecord * const me);
typedef void (*QSPY_resetFun)(void);
 
void        QSpyRecord_init     (QSpyRecord * const me,
                                 uint8_t const *start, size_t tot_len);
QSpyStatus  QSpyRecord_OK       (QSpyRecord * const me);
uint32_t    QSpyRecord_getUint32(QSpyRecord * const me, uint8_t size);
int32_t     QSpyRecord_getInt32 (QSpyRecord * const me, uint8_t size);
uint64_t    QSpyRecord_getUint64(QSpyRecord * const me, uint8_t size);
int64_t     QSpyRecord_getInt64 (QSpyRecord * const me, uint8_t size);
char const *QSpyRecord_getStr   (QSpyRecord * const me);
uint8_t const *QSpyRecord_getMem(QSpyRecord * const me,
                                 uint8_t size,
                                 uint32_t *pNum);
 
/* QSPY configuration and high-level interface .............................*/
void QSPY_config(QSpyConfig const *config,
    void   *matFile,
    void   *seqFile, char const *seqList,
    QSPY_CustParseFun custParseFun);
QSpyConfig const *QSPY_getConfig(void);
void QSPY_configTxReset(QSPY_resetFun txResetFun);
 
void QSPY_configMatFile(void *matFile);
void QSPY_configSeqFile(void *seqFile);
 
void QSPY_reset(void);
void QSPY_parse(uint8_t const *buf, uint32_t nBytes);
void QSPY_txReset(void);
 
void QSPY_setExternDict(char const *dictName);
QSpyStatus QSPY_readDict(void);
QSpyStatus QSPY_writeDict(void);
 
bool QSPY_command(uint8_t cmdId); /* execute an internal QSPY command */
void QSPY_sendEvt(QSpyRecord const * const qrec);
void QSPY_sendObj(QSpyRecord const * const qrec);
void QSPY_sendCmd(QSpyRecord const * const qrec);
void QSPY_sendTP (QSpyRecord const * const qrec);
 
size_t QSPY_encode(uint8_t *dstBuf, size_t dstSize,
                   uint8_t const *srcBuf, size_t srcBytes);
size_t QSPY_encodeResetCmd(uint8_t *dstBuf, size_t dstSize);
size_t QSPY_encodeInfoCmd (uint8_t *dstBuf, size_t dstSize);
size_t QSPY_encodeTickCmd (uint8_t *dstBuf, size_t dstSize, uint8_t rate);
 
SigType QSPY_findSig(char const *name, ObjType obj);
KeyType QSPY_findObj(char const *name);
KeyType QSPY_findFun(char const *name);
KeyType QSPY_findUsr(char const *name);
 
void QSPY_stop(void); /* orderly close all used files */
char const* QSPY_tstampStr(void);
 
/* last human-readable line of output from QSPY */
#define QS_LINE_OFFSET  8
enum QSPY_LastOutputType { REG_OUT, INF_OUT, ERR_OUT };
typedef struct {
    char buf[QS_LINE_OFFSET + QS_LINE_LEN_MAX];
    int  len;  /* the length of the composed string */
    int  rec;  /* the corresponding QS record ID */
    int  type; /* the type of the output */
} QSPY_LastOutput;
 
extern QSPY_LastOutput QSPY_output;
 
void QSPY_onPrintLn(void); /* callback to print the last line of output */
 
#define SNPRINTF_LINE(format_, ...) do {                       \
    int n_ = SNPRINTF_S(&QSPY_output.buf[QS_LINE_OFFSET],      \
                (QS_LINE_LEN_MAX - QS_LINE_OFFSET),            \
                format_,  ##__VA_ARGS__);                      \
    if ((0 < n_) && (n_ < QS_LINE_LEN_MAX - QS_LINE_OFFSET)) { \
        QSPY_output.len = n_;                                  \
    }                                                          \
    else {                                                     \
        QSPY_output.len = QS_LINE_LEN_MAX - QS_LINE_OFFSET;    \
    }                                                          \
} while (0)
 
#define SNPRINTF_APPEND(format_, ...) do {                                 \
    int n_ = SNPRINTF_S(&QSPY_output.buf[QS_LINE_OFFSET + QSPY_output.len],\
                (QS_LINE_LEN_MAX - QS_LINE_OFFSET - QSPY_output.len),      \
                format_, ##__VA_ARGS__);                                   \
    if ((0 < n_)                                                           \
        && (n_ < QS_LINE_LEN_MAX - QS_LINE_OFFSET - QSPY_output.len)) {    \
        QSPY_output.len += n_;                                             \
    }                                                                      \
    else {                                                                 \
        QSPY_output.len = QS_LINE_LEN_MAX - QS_LINE_OFFSET;                \
    }                                                                      \
} while (0)
 
/* prints information message to the QSPY output (without sending it to FE) */
void QSPY_printInfo(void);
 
/* prints error message to the QSPY output (sending it to FE) */
void QSPY_printError(void);
 
/* for backwards compatibility */
#define QSPY_line (&QSPY_output.buf[QS_LINE_OFFSET])
 
#ifdef __cplusplus
}
#endif
 
#endif /* QSPY_H */