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] 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] 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] 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] 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] 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] AO records */
    QS_QF_ACTIVE_POST_ATTEMPT,
    /* [46] EQ records */
    QS_QF_EQUEUE_POST_ATTEMPT,
    /* [47] MP records */
    QS_QF_MPOOL_GET_ATTEMPT,  
    /* [48] SC records */
    QS_MUTEX_LOCK,        
    QS_MUTEX_UNLOCK,      
    QS_SCHED_LOCK,        
    QS_SCHED_UNLOCK,      
    QS_SCHED_NEXT,        
    QS_SCHED_IDLE,        
    QS_SCHED_RESUME,      
    /* [55] 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] 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 = QS_USER,       
    QS_USER1 = QS_USER0 + 10, 
    QS_USER2 = QS_USER1 + 10, 
    QS_USER3 = QS_USER2 + 10, 
    QS_USER4 = QS_USER3 + 10  
};

#ifndef QS_TIME_SIZE

    #define QS_TIME_SIZE 4
#endif

#if (QS_TIME_SIZE == 1)
    typedef uint8_t QSTimeCtr;
    #define QS_TIME_()          (QS_u8_(QS_onGetTime()))
#elif (QS_TIME_SIZE == 2)
    typedef uint16_t QSTimeCtr;
    #define QS_TIME_()          (QS_u16_(QS_onGetTime()))
#elif (QS_TIME_SIZE == 4)

    typedef uint32_t QSTimeCtr;

    #define QS_TIME_()          (QS_u32_(QS_onGetTime()))
#else
    #error "QS_TIME_SIZE defined incorrectly, expected 1, 2, or 4"
#endif

#define QS_PTR_AT_(base_, i_) (base_[i_])


/****************************************************************************/
/* 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 data elements output ........................................*/
void QS_u8_(uint8_t d);

void QS_u8u8_(uint8_t d1, uint8_t d2);

void QS_u16_(uint16_t d);

void QS_u32_(uint32_t d);

void QS_str_(char_t const *s);

/* formatted data elements output ..........................................*/
void QS_u8(uint8_t format, uint8_t d);

void QS_u16(uint8_t format, uint16_t d);

void QS_u32(uint8_t format, uint32_t d);

void QS_f32(uint8_t format, float32_t f);

void QS_f64(uint8_t format, float64_t d);

void QS_str(char_t const *s);

void QS_mem(uint8_t const *blk, uint8_t size);

#if (QS_OBJ_PTR_SIZE == 8) || (QS_FUN_PTR_SIZE == 8)

    void QS_u64_(uint64_t d);

    void QS_u64(uint8_t format, uint64_t d);
#endif

void QS_sig_dict(enum_t const sig, void const * const obj,
                 char_t const *name);

void QS_obj_dict(void const * const obj,
                 char_t const *name);

void QS_fun_dict(void (* const fun)(void),
                 char_t const *name);

void QS_usr_dict(enum_t const rec,
                 char_t const * const name);

/* QS buffer access *********************************************************/
uint16_t QS_getByte(void);

#define QS_EOD ((uint16_t)0xFFFF)

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_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 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_) & (uint8_t)7))) \
            != (uint_fast8_t)0) \
        && ((QS_priv_.locFilter[AP_OBJ] == (void *)0) \
           || (QS_priv_.locFilter[AP_OBJ] == (obj_)))) \
    { \
        QS_beginRec((uint_fast8_t)(rec_)); \
        QS_TIME_(); {

#define QS_END_NOCRIT() } \
    QS_END_NOCRIT_()

#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 */

#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 */

#define QS_BEGIN(rec_, obj_) \
    if ((((uint_fast8_t)QS_priv_.glbFilter[(uint8_t)(rec_) >> 3] \
        & (uint_fast8_t)((uint_fast8_t)1 << ((uint8_t)(rec_) & (uint8_t)7))) \
            != (uint_fast8_t)0) \
        && ((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_(); {

#define QS_END() } \
    QS_END_()

/****************************************************************************/

#define QS_BEGIN_(rec_, objFilter_, obj_) \
    if ((((uint_fast8_t)QS_priv_.glbFilter[(uint8_t)(rec_) >> 3] \
        & (uint_fast8_t)((uint_fast8_t)1 << ((uint8_t)(rec_) & (uint8_t)7))) \
            != (uint_fast8_t)0) \
        && (((objFilter_) == (void *)0) \
            || ((objFilter_) == (obj_)))) \
    { \
        QS_CRIT_ENTRY_(); \
        QS_beginRec((uint_fast8_t)(rec_));

#define QS_END_() \
        QS_endRec(); \
        QS_CRIT_EXIT_(); \
    }

#define QS_BEGIN_NOCRIT_(rec_, objFilter_, obj_) \
    if ((((uint_fast8_t)QS_priv_.glbFilter[(uint8_t)(rec_) >> 3] \
        & (uint_fast8_t)((uint_fast8_t)1 << ((uint8_t)(rec_) & (uint8_t)7))) \
             != (uint_fast8_t)0) \
        && (((objFilter_) == (void *)0) \
            || ((objFilter_) == (obj_)))) \
    { \
        QS_beginRec((uint_fast8_t)(rec_));

#define QS_END_NOCRIT_() \
        QS_endRec(); \
    }

#define QS_U8_(data_)           (QS_u8_((uint8_t)(data_)))

#define QS_2U8_(data1_, data2_) (QS_u8u8_((data1_), (data2_)))

#define QS_U16_(data_)          (QS_u16_((uint16_t)(data_)))

#define QS_U32_(data_)          (QS_u32_((uint32_t)(data_)))

#define QS_STR_(msg_)           (QS_str_((msg_)))


#if (Q_SIGNAL_SIZE == 1)

    #define QS_SIG_(sig_)       (QS_u8_(sig_))
#elif (Q_SIGNAL_SIZE == 2)
    #define QS_SIG_(sig_)       (QS_u16_(sig_))
#elif (Q_SIGNAL_SIZE == 4)
    #define QS_SIG_(sig_)       (QS_u32_(sig_))
#endif


#if (QS_OBJ_PTR_SIZE == 1)
    #define QS_OBJ_(obj_)       (QS_u8_((uint8_t)(obj_)))
#elif (QS_OBJ_PTR_SIZE == 2)
    #define QS_OBJ_(obj_)       (QS_u16_((uint16_t)(obj_)))
#elif (QS_OBJ_PTR_SIZE == 4)
    #define QS_OBJ_(obj_)       (QS_u32_((uint32_t)(obj_)))
#elif (QS_OBJ_PTR_SIZE == 8)
    #define QS_OBJ_(obj_)       (QS_u64_((uint64_t)(obj_)))
#else

    #define QS_OBJ_(obj_)       (QS_u32_((uint32_t)(obj_))
#endif


#if (QS_FUN_PTR_SIZE == 1)
    #define QS_FUN_(fun_)       (QS_u8_((uint8_t)(fun_)))
#elif (QS_FUN_PTR_SIZE == 2)
    #define QS_FUN_(fun_)       (QS_u16_((uint16_t)(fun_)))
#elif (QS_FUN_PTR_SIZE == 4)
    #define QS_FUN_(fun_)       (QS_u32_((uint32_t)(fun_)))
#elif (QS_FUN_PTR_SIZE == 8)
    #define QS_FUN_(fun_)       (QS_u64_((uint64_t)(fun_)))
#else

    #define QS_FUN_(fun_)       (QS_u32_((uint32_t)(fun_)))
#endif

/****************************************************************************/
/* Macros for use in the client code */

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((uint8_t)(((width_) << 4)) | (uint8_t)QS_I8_T, (data_)))

#define QS_U8(width_, data_) \
    (QS_u8((uint8_t)(((width_) << 4)) | (uint8_t)QS_U8_T, (data_)))

#define QS_I16(width_, data_) \
    (QS_u16((uint8_t)(((width_) << 4)) | (uint8_t)QS_I16_T, (data_)))

#define QS_U16(width_, data_) \
    (QS_u16((uint8_t)(((width_) << 4)) | (uint8_t)QS_U16_T, (data_)))

#define QS_I32(width_, data_) \
    (QS_u32((uint8_t)(((width_) << 4)) | (uint8_t)QS_I32_T, (data_)))

#define QS_U32(width_, data_) \
    (QS_u32((uint8_t)(((width_) << 4)) | (uint8_t)QS_U32_T, (data_)))

#define QS_F32(width_, data_) \
    (QS_f32((uint8_t)(((width_) << 4)) | (uint8_t)QS_F32_T, (data_)))

#define QS_F64(width_, data_) \
    (QS_f64((uint8_t)(((width_) << 4)) | (uint8_t)QS_F64_T, (data_)))

#define QS_I64(width_, data_) \
    (QS_u64((uint8_t)(((width_) << 4)) | (uint8_t)QS_I64_T, (data_)))

#define QS_U64(width_, data_) \
    (QS_u64((uint8_t)(((width_) << 4)) | (uint8_t)QS_U64_T, (data_)))

#define QS_U32_HEX(width_, data_) \
    (QS_u32((uint8_t)(((width_) << 4)) | (uint8_t)QS_U32_HEX_T, (data_)))

#define QS_STR(str_)            (QS_str((str_)))

#define QS_MEM(mem_, size_)     (QS_mem((mem_), (size_)))


#if (QS_OBJ_PTR_SIZE == 1)
    #define QS_OBJ(obj_)        (QS_u8(QS_OBJ_T, (uint8_t)(obj_)))
#elif (QS_OBJ_PTR_SIZE == 2)
    #define QS_OBJ(obj_)        (QS_u16(QS_OBJ_T, (uint16_t)(obj_)))
#elif (QS_OBJ_PTR_SIZE == 4)
    #define QS_OBJ(obj_)        (QS_u32(QS_OBJ_T, (uint32_t)(obj_)))
#elif (QS_OBJ_PTR_SIZE == 8)
    #define QS_OBJ(obj_)        (QS_u64(QS_OBJ_T, (uint64_t)(obj_)))
#else

    #define QS_OBJ(obj_)        (QS_u32(QS_OBJ_T, (uint32_t)(obj_)))
#endif


#if (QS_FUN_PTR_SIZE == 1)
    #define QS_FUN(fun_)        (QS_u8(QS_FUN_T, (uint8_t)(fun_)))
#elif (QS_FUN_PTR_SIZE == 2)
    #define QS_FUN(fun_)        (QS_u16(QS_FUN_T, (uint16_t)(fun_)))
#elif (QS_FUN_PTR_SIZE == 4)
    #define QS_FUN(fun_)        (QS_u32(QS_FUN_T, (uint32_t)(fun_)))
#elif (QS_FUN_PTR_SIZE == 8)
    #define QS_FUN(fun_)        (QS_u64(QS_FUN_T, (uint64_t)(fun_)))
#else

    #define QS_FUN(fun_)        (QS_u32(QS_FUN_T, (uint32_t)(fun_)))
#endif


#if (Q_SIGNAL_SIZE == 1)
    #define QS_SIG(sig_, obj_) \
        QS_u8(QS_SIG_T, (sig_)); \
        QS_OBJ_(obj_)
#elif (Q_SIGNAL_SIZE == 2)
    #define QS_SIG(sig_, obj_) \
        QS_u16(QS_SIG_T, (sig_)); \
        QS_OBJ_(obj_)
#elif (Q_SIGNAL_SIZE == 4)
    #define QS_SIG(sig_, obj_) \
        QS_u32(QS_SIG_T, (sig_)); \
        QS_OBJ_(obj_)
#else

    #define QS_SIG(sig_, obj_) \
        QS_u16(QS_SIG_T, (sig_)); \
        QS_OBJ_(obj_)
#endif

/****************************************************************************/
/* Dictionary records */

#define QS_SIG_DICTIONARY(sig_, obj_) do { \
    static char_t const sig_name_[] = #sig_; \
    QS_sig_dict((sig_), (obj_), &sig_name_[0]); \
} while (0)

#define QS_OBJ_DICTIONARY(obj_) do { \
    static char_t const obj_name_[] = #obj_; \
    QS_obj_dict((obj_), &obj_name_[0]); \
} while (0)

#define QS_FUN_DICTIONARY(fun_) do { \
    static char_t const fun_name_[] = #fun_; \
    QS_fun_dict((void (*)(void))(fun_), &fun_name_[0]); \
} while (0)

#define QS_USR_DICTIONARY(rec_) do { \
    static char_t const usr_name_[] = #rec_; \
    QS_usr_dict((rec_), &usr_name_[0]); \
} while (0)

#define QS_ASSERTION(module_, loc_, delay_) do { \
    uint32_t volatile delay_ctr_; \
    QS_BEGIN_NOCRIT_(QS_ASSERT_FAIL, (void *)0, (void *)0) \
        QS_TIME_(); \
        QS_U16_((uint16_t)(loc_)); \
        QS_STR_(((module_) != (char_t *)0) ? (module_) : "?"); \
    QS_END_NOCRIT_() \
    QS_onFlush(); \
    for (delay_ctr_ = (delay_); delay_ctr_ > (uint32_t)0; --delay_ctr_) {} \
    QS_onCleanup(); \
} while (0)

#define QS_FLUSH()   (QS_onFlush())

#define QF_QS_CRIT_ENTRY() \
    QS_BEGIN_NOCRIT_(QS_QF_CRIT_ENTRY, (void *)0, (void *)0) \
        QS_TIME_(); \
        QS_U8_(++QS_priv_.critNest); \
    QS_END_NOCRIT_()

#define QF_QS_CRIT_EXIT() \
    QS_BEGIN_NOCRIT_(QS_QF_CRIT_EXIT, (void *)0, (void *)0) \
        QS_TIME_(); \
        QS_U8_(QS_priv_.critNest--); \
    QS_END_NOCRIT_()

#define QF_QS_ISR_ENTRY(isrnest_, prio_) \
    QS_BEGIN_NOCRIT_(QS_QF_ISR_ENTRY, (void *)0, (void *)0) \
        QS_TIME_(); \
        QS_2U8_(isrnest_, prio_); \
    QS_END_NOCRIT_()

#define QF_QS_ISR_EXIT(isrnest_, prio_) \
    QS_BEGIN_NOCRIT_(QS_QF_ISR_EXIT, (void *)0, (void *)0) \
        QS_TIME_(); \
        QS_2U8_(isrnest_, prio_); \
    QS_END_NOCRIT_()

#define QF_QS_ACTION(act_)      (act_)

#define QS_getVersion() (QP_versionStr)


/****************************************************************************/
/* QS private data (the transmit 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 = 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;    
} QSPriv;

extern QSPriv 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);

typedef struct {
    void     *currObj[MAX_OBJ]; 
    uint8_t  *buf;        
    QSCtr     end;        
    QSCtr     head;       
    QSCtr     tail;       
#ifdef Q_UTEST
    QPSet     readySet;   
    bool      inTestLoop; 
#endif
} QSrxPriv;

extern QSrxPriv QS_rxPriv_;

#define QS_RX_PUT(b_) do { \
    if (QS_rxPriv_.head != (QSCtr)0) { \
        if ((QS_rxPriv_.head - QS_rxPriv_.tail) != (QSCtr)1) { \
            QS_PTR_AT_(QS_rxPriv_.buf, QS_rxPriv_.head) = (uint8_t)(b_); \
            --QS_rxPriv_.head; \
        } \
    } \
    else { \
        if (QS_rxPriv_.tail != QS_rxPriv_.end) { \
            QS_PTR_AT_(QS_rxPriv_.buf, 0) = (uint8_t)(b_); \
            QS_rxPriv_.head = QS_rxPriv_.end; \
        } \
    } \
} while (0)

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_ != (uint32_t)0) { 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 (0)

    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  */