qs.h

Go to the documentation of this file.

 
#ifndef QS_H
#define QS_H
 
#ifndef Q_SPY
    #error "Q_SPY must be defined to include qs.h"
#endif
 
/****************************************************************************/
enum QSpyRecords {
    /* [0] QS session (not maskable) */
    QS_EMPTY,             
    /* [1] SM records */
    QS_QEP_STATE_ENTRY,   
    QS_QEP_STATE_EXIT,    
    QS_QEP_STATE_INIT,    
    QS_QEP_INIT_TRAN,     
    QS_QEP_INTERN_TRAN,   
    QS_QEP_TRAN,          
    QS_QEP_IGNORED,       
    QS_QEP_DISPATCH,      
    QS_QEP_UNHANDLED,     
    /* [10] Active Object (AO) records */
    QS_QF_ACTIVE_DEFER,   
    QS_QF_ACTIVE_RECALL,  
    QS_QF_ACTIVE_SUBSCRIBE, 
    QS_QF_ACTIVE_UNSUBSCRIBE, 
    QS_QF_ACTIVE_POST_FIFO, 
    QS_QF_ACTIVE_POST_LIFO, 
    QS_QF_ACTIVE_GET,     
    QS_QF_ACTIVE_GET_LAST,
    QS_QF_ACTIVE_RECALL_ATTEMPT, 
    /* [19] Event Queue (EQ) records */
    QS_QF_EQUEUE_POST_FIFO, 
    QS_QF_EQUEUE_POST_LIFO, 
    QS_QF_EQUEUE_GET,     
    QS_QF_EQUEUE_GET_LAST,
    QS_QF_RESERVED2,
 
    /* [24] Memory Pool (MP) records */
    QS_QF_MPOOL_GET,      
    QS_QF_MPOOL_PUT,      
    /* [26] QF records */
    QS_QF_PUBLISH,        
    QS_QF_NEW_REF,        
    QS_QF_NEW,            
    QS_QF_GC_ATTEMPT,     
    QS_QF_GC,             
    QS_QF_TICK,           
    /* [32] Time Event (TE) records */
    QS_QF_TIMEEVT_ARM,    
    QS_QF_TIMEEVT_AUTO_DISARM, 
    QS_QF_TIMEEVT_DISARM_ATTEMPT,
    QS_QF_TIMEEVT_DISARM, 
    QS_QF_TIMEEVT_REARM,  
    QS_QF_TIMEEVT_POST,   
    /* [38] Additional QF records */
    QS_QF_DELETE_REF,     
    QS_QF_CRIT_ENTRY,     
    QS_QF_CRIT_EXIT,      
    QS_QF_ISR_ENTRY,      
    QS_QF_ISR_EXIT,       
    QS_QF_INT_DISABLE,    
    QS_QF_INT_ENABLE,     
    /* [45] Additional Active Object (AO) records */
    QS_QF_ACTIVE_POST_ATTEMPT,
    /* [46] Additional Event Queue (EQ) records */
    QS_QF_EQUEUE_POST_ATTEMPT,
    /* [47] Additional Memory Pool (MP) records */
    QS_QF_MPOOL_GET_ATTEMPT,  
    /* [48] Scheduler (SC) records */
    QS_MUTEX_LOCK,        
    QS_MUTEX_UNLOCK,      
    QS_SCHED_LOCK,        
    QS_SCHED_UNLOCK,      
    QS_SCHED_NEXT,        
    QS_SCHED_IDLE,        
    QS_SCHED_RESUME,      
    /* [55] Additional QEP records */
    QS_QEP_TRAN_HIST,     
    QS_QEP_TRAN_EP,       
    QS_QEP_TRAN_XP,       
    /* [58] Miscellaneous QS records (not maskable) */
    QS_TEST_PAUSED,       
    QS_TEST_PROBE_GET,    
    QS_SIG_DICT,          
    QS_OBJ_DICT,          
    QS_FUN_DICT,          
    QS_USR_DICT,          
    QS_TARGET_INFO,       
    QS_TARGET_DONE,       
    QS_RX_STATUS,         
    QS_QUERY_DATA,        
    QS_PEEK_DATA,         
    QS_ASSERT_FAIL,       
    /* [70] Reserved QS records */
    QS_RESERVED_70,
    QS_RESERVED_71,
    QS_RESERVED_72,
    QS_RESERVED_73,
    QS_RESERVED_74,
    QS_RESERVED_75,
    QS_RESERVED_76,
    QS_RESERVED_77,
    QS_RESERVED_78,
    QS_RESERVED_79,
    QS_RESERVED_80,
    QS_RESERVED_81,
    QS_RESERVED_82,
    QS_RESERVED_83,
    QS_RESERVED_84,
    QS_RESERVED_85,
    QS_RESERVED_86,
    QS_RESERVED_87,
    QS_RESERVED_88,
    QS_RESERVED_89,
    QS_RESERVED_90,
    QS_RESERVED_91,
    QS_RESERVED_92,
    QS_RESERVED_93,
    QS_RESERVED_94,
    QS_RESERVED_95,
    QS_RESERVED_96,
    QS_RESERVED_97,
    QS_RESERVED_98,
    QS_RESERVED_99,
 
    /* [100] Application-specific (User) QS records */
    QS_USER               
};
 
enum QSpyRecordGroups {
    QS_ALL_RECORDS = 0xF0,
    QS_SM_RECORDS,        
    QS_AO_RECORDS,        
    QS_EQ_RECORDS,        
    QS_MP_RECORDS,        
    QS_TE_RECORDS,        
    QS_QF_RECORDS,        
    QS_SC_RECORDS,        
    QS_U0_RECORDS,        
    QS_U1_RECORDS,        
    QS_U2_RECORDS,        
    QS_U3_RECORDS,        
    QS_U4_RECORDS,        
    QS_UA_RECORDS         
};
 
enum QSpyUserRecords {
    QS_USER0 = (enum_t)QS_USER,      
    QS_USER1 = (enum_t)QS_USER0 + 5, 
    QS_USER2 = (enum_t)QS_USER1 + 5, 
    QS_USER3 = (enum_t)QS_USER2 + 5, 
    QS_USER4 = (enum_t)QS_USER3 + 5  
};
 
#ifndef QS_TIME_SIZE
 
    #define QS_TIME_SIZE 4U
#endif
 
#if (QS_TIME_SIZE == 1U)
    typedef uint8_t QSTimeCtr;
    #define QS_TIME_PRE_()      (QS_u8_raw_(QS_onGetTime()))
#elif (QS_TIME_SIZE == 2U)
    typedef uint16_t QSTimeCtr;
    #define QS_TIME_PRE_()      (QS_u16_raw_(QS_onGetTime()))
#elif (QS_TIME_SIZE == 4U)
 
    typedef uint32_t QSTimeCtr;
 
    #define QS_TIME_PRE_()      (QS_u32_raw_(QS_onGetTime()))
#else
    #error "QS_TIME_SIZE defined incorrectly, expected 1, 2, or 4"
#endif
 
 
/****************************************************************************/
/* QS services. */
 
void QS_initBuf(uint8_t sto[], uint_fast16_t stoSize);
 
void QS_filterOn_(uint_fast8_t rec);
 
void QS_filterOff_(uint_fast8_t rec);
 
void QS_beginRec_(uint_fast8_t rec);
 
void QS_endRec_(void);
 
/* unformatted (raw) data elements output ..................................*/
void QS_u8_raw_(uint8_t d);
 
void QS_2u8_raw_(uint8_t d1, uint8_t d2);
 
void QS_u16_raw_(uint16_t d);
 
void QS_u32_raw_(uint32_t d);
 
void QS_str_raw_(char_t const *str);
 
/* formatted data elements output ..........................................*/
void QS_u8_fmt_(uint8_t format, uint8_t d);
 
void QS_u16_fmt_(uint8_t format, uint16_t d);
 
void QS_u32_fmt_(uint8_t format, uint32_t d);
 
void QS_f32_fmt_(uint8_t format, float32_t f);
 
void QS_f64_fmt_(uint8_t format, float64_t d);
 
void QS_obj_raw_(void const * const obj);
 
void QS_str_fmt_(char_t const *str);
 
void QS_mem_fmt_(uint8_t const *blk, uint8_t size);
 
#if (QS_OBJ_PTR_SIZE == 8U) || (QS_FUN_PTR_SIZE == 8U)
 
    void QS_u64_raw_(uint64_t d);
 
    void QS_u64_fmt_(uint8_t format, uint64_t d);
#endif
 
/* QS buffer access *********************************************************/
uint16_t QS_getByte(void);
 
#define QS_EOD ((uint16_t)0xFFFFU)
 
uint8_t const *QS_getBlock(uint16_t *pNbytes);
 
 
/* platform-specific callback functions, need to be implemented by clients */
 
uint8_t QS_onStartup(void const *arg);
 
void QS_onCleanup(void);
 
void QS_onFlush(void);
 
QSTimeCtr QS_onGetTime(void);
 
 
/****************************************************************************/
/* Macros for adding QS instrumentation to the client code */
 
#define QS_INIT(arg_)           (QS_onStartup(arg_))
 
#define QS_EXIT()               (QS_onCleanup())
 
#define QS_FLUSH()   (QS_onFlush())
 
#define QS_FILTER_ON(rec_)      (QS_filterOn_((uint_fast8_t)(rec_)))
 
#define QS_FILTER_OFF(rec_)     (QS_filterOff_((uint_fast8_t)(rec_)))
 
#define QS_FILTER_SM_OBJ(obj_)  (QS_priv_.locFilter[SM_OBJ] = (obj_))
 
#define QS_FILTER_AO_OBJ(obj_)  (QS_priv_.locFilter[AO_OBJ] = (obj_))
 
#define QS_FILTER_MP_OBJ(obj_)  (QS_priv_.locFilter[MP_OBJ] = (obj_))
 
#define QS_FILTER_EQ_OBJ(obj_)  (QS_priv_.locFilter[EQ_OBJ] = (obj_))
 
#define QS_FILTER_TE_OBJ(obj_)  (QS_priv_.locFilter[TE_OBJ] = (obj_))
 
#define QS_FILTER_AP_OBJ(obj_)  (QS_priv_.locFilter[AP_OBJ] = (obj_))
 
 
/****************************************************************************/
/* Macros to generate application-specific (user) QS records */
 
#define QS_BEGIN_NOCRIT(rec_, obj_)                              \
    if ((((uint_fast8_t)QS_priv_.glbFilter[(uint8_t)(rec_) >> 3] \
          & (uint_fast8_t)(1U << ((uint8_t)(rec_) & 7U))) != 0U) \
        && ((QS_priv_.locFilter[AP_OBJ] == (void *)0)            \
           || (QS_priv_.locFilter[AP_OBJ] == (obj_))))           \
    {                                                            \
        QS_beginRec_((uint_fast8_t)(rec_));                      \
        QS_TIME_PRE_(); {
 
#define QS_END_NOCRIT() } \
        QS_endRec_();     \
    }
 
#ifndef QS_REC_DONE
 
    #define QS_REC_DONE() ((void)0)
#endif /* QS_REC_DONE */
 
/* QS-specific critical section */
#ifdef QS_CRIT_ENTRY /* separate QS critical section defined? */
 
#ifndef QS_CRIT_STAT_TYPE
    #define QS_CRIT_STAT_
    #define QS_CRIT_ENTRY_()    QS_CRIT_ENTRY(dummy)
    #define QS_CRIT_EXIT_()     QS_CRIT_EXIT(dummy); QS_REC_DONE()
#else
    #define QS_CRIT_STAT_       QS_CRIT_STAT_TYPE critStat_;
    #define QS_CRIT_ENTRY_()    QS_CRIT_ENTRY(critStat_)
    #define QS_CRIT_EXIT_()     QS_CRIT_EXIT(critStat_); QS_REC_DONE()
#endif /* QS_CRIT_STAT_TYPE */
 
#else /* separate QS critical section not defined--use the QF definition */
 
#define QS_BEGIN(rec_, obj_)                                     \
    if ((((uint_fast8_t)QS_priv_.glbFilter[(uint8_t)(rec_) >> 3] \
        & (uint_fast8_t)(1U << ((uint8_t)(rec_) & 7U))) != 0U)   \
        && ((QS_priv_.locFilter[AP_OBJ] == (void *)0)            \
            || (QS_priv_.locFilter[AP_OBJ] == (obj_))))          \
    {                                                            \
        QS_CRIT_STAT_                                            \
        QS_CRIT_ENTRY_();                                        \
        QS_beginRec_((uint_fast8_t)(rec_));                      \
        QS_TIME_PRE_(); {
 
#define QS_END() }       \
        QS_endRec_();    \
        QS_CRIT_EXIT_(); \
    }
 
enum {
    QS_I8_T,              
    QS_U8_T,              
    QS_I16_T,             
    QS_U16_T,             
    QS_I32_T,             
    QS_U32_T,             
    QS_F32_T,             
    QS_F64_T,             
    QS_STR_T,             
    QS_MEM_T,             
    QS_SIG_T,             
    QS_OBJ_T,             
    QS_FUN_T,             
    QS_I64_T,             
    QS_U64_T,             
    QS_U32_HEX_T          
};
 
#define QS_I8(width_, data_) \
    (QS_u8_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_I8_T, (data_)))
 
#define QS_U8(width_, data_) \
    (QS_u8_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_U8_T, (data_)))
 
#define QS_I16(width_, data_) \
    (QS_u16_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_I16_T, (data_)))
 
#define QS_U16(width_, data_) \
    (QS_u16_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_U16_T, (data_)))
 
#define QS_I32(width_, data_) \
    (QS_u32_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_I32_T, (data_)))
 
#define QS_U32(width_, data_) \
    (QS_u32_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_U32_T, (data_)))
 
#define QS_F32(width_, data_) \
    (QS_f32_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_F32_T, (data_)))
 
#define QS_F64(width_, data_) \
    (QS_f64_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_F64_T, (data_)))
 
#define QS_I64(width_, data_) \
    (QS_u64_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_I64_T, (data_)))
 
#define QS_U64(width_, data_) \
    (QS_u64_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_U64_T, (data_)))
 
#define QS_U32_HEX(width_, data_) \
    (QS_u32_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_U32_HEX_T, (data_)))
 
#define QS_STR(str_)            (QS_str_fmt_((str_)))
 
#define QS_MEM(mem_, size_)     (QS_mem_fmt_((mem_), (size_)))
 
 
#if (QS_OBJ_PTR_SIZE == 1U)
    #define QS_OBJ(obj_)        (QS_u8_fmt_(QS_OBJ_T, (uint8_t)(obj_)))
#elif (QS_OBJ_PTR_SIZE == 2U)
    #define QS_OBJ(obj_)        (QS_u16_fmt_(QS_OBJ_T, (uint16_t)(obj_)))
#elif (QS_OBJ_PTR_SIZE == 4U)
    #define QS_OBJ(obj_)        (QS_u32_fmt_(QS_OBJ_T, (uint32_t)(obj_)))
#elif (QS_OBJ_PTR_SIZE == 8U)
    #define QS_OBJ(obj_)        (QS_u64(QS_OBJ_T, (uint64_t)(obj_)))
#else
 
    #define QS_OBJ(obj_)        (QS_u32_fmt_(QS_OBJ_T, (uint32_t)(obj_)))
#endif
 
 
#if (QS_FUN_PTR_SIZE == 1U)
    #define QS_FUN(fun_)        (QS_u8_fmt_(QS_FUN_T, (uint8_t)(fun_)))
#elif (QS_FUN_PTR_SIZE == 2U)
    #define QS_FUN(fun_)        (QS_u16_fmt_(QS_FUN_T, (uint16_t)(fun_)))
#elif (QS_FUN_PTR_SIZE == 4U)
    #define QS_FUN(fun_)        (QS_u32_fmt_(QS_FUN_T, (uint32_t)(fun_)))
#elif (QS_FUN_PTR_SIZE == 8U)
    #define QS_FUN(fun_)        (QS_u64_fmt_(QS_FUN_T, (uint64_t)(fun_)))
#else
 
    #define QS_FUN(fun_)        (QS_u32_fmt_(QS_FUN_T, (uint32_t)(fun_)))
#endif
 
#if (Q_SIGNAL_SIZE == 1)
 
    #define QS_SIG(sig_, obj_)   \
        QS_u8_fmt_(QS_SIG_T, (sig_)); \
        QS_obj_raw_(obj_)
 
#elif (Q_SIGNAL_SIZE == 2)
 
    #define QS_SIG(sig_, obj_)    \
        QS_u16_fmt_(QS_SIG_T, (sig_)); \
        QS_obj_raw_(obj_)
 
#elif (Q_SIGNAL_SIZE == 4)
 
    #define QS_SIG(sig_, obj_)    \
        QS_u32_fmt_(QS_SIG_T, (sig_)); \
        QS_obj_raw_(obj_)
 
#else
 
    #define QS_SIG(sig_, obj_)    \
        QS_u16_fmt_(QS_SIG_T, (sig_)); \
        QS_obj_raw_(obj_)
 
#endif
 
 
/****************************************************************************/
/* Facilities for QS ciritical section */
 
#ifndef QF_CRIT_STAT_TYPE
 
    #define QS_CRIT_STAT_
 
    #define QS_CRIT_ENTRY_()    QF_CRIT_ENTRY(dummy)
 
    #define QS_CRIT_EXIT_()     QF_CRIT_EXIT(dummy); QS_REC_DONE()
 
#else  /* simple unconditional interrupt disabling used */
    #define QS_CRIT_STAT_       QF_CRIT_STAT_TYPE critStat_;
    #define QS_CRIT_ENTRY_()    QF_CRIT_ENTRY(critStat_)
    #define QS_CRIT_EXIT_()     QF_CRIT_EXIT(critStat_); QS_REC_DONE()
#endif /* simple unconditional interrupt disabling used */
 
#endif /* separate QS critical section not defined */
 
 
/****************************************************************************/
/* Dictionary trace records */
 
#define QS_SIG_DICTIONARY(sig_, obj_) \
    (QS_sig_dict_pre_((sig_), (obj_), #sig_))
 
#define QS_OBJ_DICTIONARY(obj_) \
    (QS_obj_dict_pre_((obj_), #obj_))
 
#define QS_FUN_DICTIONARY(fun_) \
    (QS_fun_dict_pre_((void (*)(void))(fun_), #fun_))
 
#define QS_USR_DICTIONARY(rec_) \
    (QS_usr_dict_pre_((rec_), #rec_))
 
void QS_sig_dict_pre_(enum_t const sig, void const * const obj,
                      char_t const *name);
 
void QS_obj_dict_pre_(void const * const obj,
                      char_t const *name);
 
void QS_fun_dict_pre_(void (* const fun)(void),
                      char_t const *name);
 
void QS_usr_dict_pre_(enum_t const rec,
                      char_t const * const name);
 
 
/****************************************************************************/
/* Miscellaneous pre-formatted trace records used in applications */
 
void QS_ASSERTION(char_t const * const module,
                  int_t const loc,
                  uint32_t delay);
 
void QF_QS_CRIT_ENTRY(void);
 
void QF_QS_CRIT_EXIT(void);
 
void QF_QS_ISR_ENTRY(uint8_t const isrnest, uint8_t const prio);
 
void QF_QS_ISR_EXIT(uint8_t const isrnest, uint8_t const prio);
 
#define QF_QS_ACTION(act_)    (act_)
 
 
/****************************************************************************/
/* QS private data (the TX channel) */
typedef uint_fast16_t QSCtr;  
enum QSpyObjKind {
    SM_OBJ,    
    AO_OBJ,    
    MP_OBJ,    
    EQ_OBJ,    
    TE_OBJ,    
    AP_OBJ,    
    MAX_OBJ
};
 
enum OSpyObjCombnation {
    SM_AO_OBJ = (enum_t)MAX_OBJ 
};
 
typedef struct {
    uint8_t  glbFilter[16];         
    void const *locFilter[MAX_OBJ]; 
    uint8_t *buf;         
    QSCtr    end;         
    QSCtr    head;        
    QSCtr    tail;        
    QSCtr    used;        
    uint8_t  seq;         
    uint8_t  chksum;      
    uint8_t  critNest;    
} QSPrivAttr;
 
extern QSPrivAttr QS_priv_;
 
 
/****************************************************************************/
/* QS receive channel */
 
enum QSpyRxRecords {
    QS_RX_INFO,           
    QS_RX_COMMAND,        
    QS_RX_RESET,          
    QS_RX_TICK,           
    QS_RX_PEEK,           
    QS_RX_POKE,           
    QS_RX_FILL,           
    QS_RX_TEST_SETUP,     
    QS_RX_TEST_TEARDOWN,  
    QS_RX_TEST_PROBE,     
    QS_RX_GLB_FILTER,     
    QS_RX_LOC_FILTER,     
    QS_RX_AO_FILTER,      
    QS_RX_CURR_OBJ,       
    QS_RX_TEST_CONTINUE,  
    QS_RX_QUERY_CURR,     
    QS_RX_EVENT           
};
 
void QS_rxInitBuf(uint8_t sto[], uint16_t stoSize);
 
void QS_rxParse(void);
 
void QS_RX_PUT(uint8_t const b);
 
uint16_t QS_rxGetNfree(void);
 
void QS_onReset(void);
 
void QS_onCommand(uint8_t cmdId,   uint32_t param1,
                  uint32_t param2, uint32_t param3);
 
#define QS_OUTPUT()   (QS_output())
 
#define QS_RX_INPUT() (QS_rx_input())
 
/****************************************************************************/
/* Facilities for use in QUTest only */
#ifdef Q_UTEST
 
    void QS_onTestSetup(void);
 
    void QS_onTestTeardown(void);
 
    void QS_onTestLoop(void);
 
    void QS_onTestEvt(QEvt *e);
 
    void QS_onTestPost(void const *sender, QActive *recipient,
                       QEvt const *e, bool status);
 
    void QS_processTestEvts_(void);
 
    void QS_tickX_(uint_fast8_t const tickRate, void const * const sender);
 
    uint32_t QS_getTestProbe_(void (* const api)(void));
 
    #define QS_TEST_PROBE_DEF(fun_) \
        uint32_t const qs_tp_ = QS_getTestProbe_((void (*)(void))(fun_));
 
    #define QS_TEST_PROBE(code_) \
        if (qs_tp_ != 0U) { code_ }
 
    #define QS_TEST_PROBE_ID(id_, code_) \
        if (qs_tp_ == (uint32_t)(id_)) { code_ }
 
    #define QS_TEST_PAUSE() do {                    \
        QS_beginRec_((uint_fast8_t)QS_TEST_PAUSED); \
        QS_endRec_();                               \
        QS_onTestLoop();                            \
    } while (false)
 
    enum QUTestUserRecords {
        QUTEST_ON_POST = 124
    };
 
    /************************************************************************/
    typedef struct {
        QActive super; /*< inherit QActive */
    } QActiveDummy;
 
    void QActiveDummy_ctor(QActiveDummy * const me);
 
#else /* Q_UTEST not defined */
 
    /* dummy definitions when not building for QUTEST */
    #define QS_TEST_PROBE_DEF(fun_)
    #define QS_TEST_PROBE(code_)
    #define QS_TEST_PROBE_ID(id_, code_)
    #define QS_TEST_PAUSE()  ((void)0)
 
#endif /* Q_UTEST */
 
#endif /* QS_H  */