qs.h

Go to the documentation of this file.

// Product: QS/C++ platform-independent public interface.
// Last Updated for Version: 4.0.00
// Date of the Last Update:  Apr 06, 2008
//
//                    Q u a n t u m     L e a P s
//                    ---------------------------
//                    innovating embedded systems
//
// Copyright (C) 2002-2008 Quantum Leaps, LLC. All rights reserved.
//
// This software may be distributed and modified under the terms of the GNU
// General Public License version 2 (GPL) as published by the Free Software
// Foundation and appearing in the file GPL.TXT included in the packaging of
// this file. Please note that GPL Section 2[b] requires that all works based
// on this software must also be made publicly available under the terms of
// the GPL ("Copyleft").
//
// Alternatively, this software may be distributed and modified under the
// terms of Quantum Leaps commercial licenses, which expressly supersede
// the GPL and are specifically designed for licensees interested in
// retaining the proprietary status of their code.
//
// Contact information:
// Quantum Leaps Web site:  http://www.quantum-leaps.com
// e-mail:                  info@quantum-leaps.com
#ifndef qs_h
#define qs_h


#ifndef Q_SPY
    #error "Q_SPY must be defined to include qs.h"
#endif


enum QSpyRecords {
    // QEP records
    QS_QEP_STATE_EMPTY,
    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_RESERVED1,
    QS_QEP_RESERVED0,

    // QF records
    QS_QF_ACTIVE_ADD,                
    QS_QF_ACTIVE_REMOVE,         
    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_EQUEUE_INIT,                     
    QS_QF_EQUEUE_POST_FIFO,     
    QS_QF_EQUEUE_POST_LIFO,     
    QS_QF_EQUEUE_GET,              
    QS_QF_EQUEUE_GET_LAST,              
    QS_QF_MPOOL_INIT,                       
    QS_QF_MPOOL_GET,        
    QS_QF_MPOOL_PUT,         
    QS_QF_PUBLISH,       
    QS_QF_RESERVED8,
    QS_QF_NEW,                                         
    QS_QF_GC_ATTEMPT,                          
    QS_QF_GC,                                          
    QS_QF_TICK,                                     
    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,      
    QS_QF_RESERVED7,
    QS_QF_INT_LOCK,                                
    QS_QF_INT_UNLOCK,                            
    QS_QF_ISR_ENTRY,                                   
    QS_QF_ISR_EXIT,                                     
    QS_QF_RESERVED6,
    QS_QF_RESERVED5,
    QS_QF_RESERVED4,
    QS_QF_RESERVED3,
    QS_QF_RESERVED2,
    QS_QF_RESERVED1,
    QS_QF_RESERVED0,

    // QK records
    QS_QK_MUTEX_LOCK,                             
    QS_QK_MUTEX_UNLOCK,                         
    QS_QK_SCHEDULE,      
    QS_QK_RESERVED6,
    QS_QK_RESERVED5,
    QS_QK_RESERVED4,
    QS_QK_RESERVED3,
    QS_QK_RESERVED2,
    QS_QK_RESERVED1,
    QS_QK_RESERVED0,

    // Miscellaneous QS records
    QS_SIG_DICTIONARY,                            
    QS_OBJ_DICTIONARY,                            
    QS_FUN_DICTIONARY,                          
    QS_ASSERT,                                
    QS_RESERVED5,
    QS_RESERVED4,
    QS_RESERVED3,
    QS_RESERVED2,
    QS_RESERVED1,
    QS_RESERVED0,

    // User records
    QS_USER                
};

#define QS_ALL_RECORDS          ((uint8_t)0xFF)

#define QS_EOD                  ((uint16_t)0xFFFF)


#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

#ifndef Q_ROM                      // provide the default if Q_ROM NOT defined
    #define Q_ROM
#endif
#ifndef Q_ROM_VAR              // provide the default if Q_ROM_VAR NOT defined
    #define Q_ROM_VAR
#endif
#ifndef Q_ROM_BYTE            // provide the default if Q_ROM_BYTE NOT defined
    #define Q_ROM_BYTE(rom_var_)   (rom_var_)
#endif


class QS {
public:

    static char const Q_ROM * Q_ROM_VAR getVersion(void);

    static void initBuf(uint8_t sto[], uint32_t stoSize);

    static void filterOn(uint8_t rec);

    static void filterOff(uint8_t rec);

    static void begin(uint8_t rec);

    static void end(void);

    // unformatted data elements output ......................................

    static void u8_(uint8_t d);

    static void u16_(uint16_t d);

    static void u32_(uint32_t d);

    static void str_(char const *s);

    static void str_ROM_(char const Q_ROM * Q_ROM_VAR s);

    // formatted data elements output ........................................

    static void u8(uint8_t format, uint8_t d);

    static void u16(uint8_t format, uint16_t d);

    static void u32(uint8_t format, uint32_t d);

    static void f32(uint8_t format, float d);

    static void f64(uint8_t format, double d);

    static void str(char const *s);

    static void str_ROM(char const Q_ROM * Q_ROM_VAR s);

    static void mem(uint8_t const *blk, uint8_t size);

    // QS buffer access ......................................................

    static uint16_t getByte(void);

    static uint8_t const *getBlock(uint16_t *pNbytes);

// platform-dependent callback functions, need to be implemented by clients
public:

    // platform-specific callback functions, need to be implemented by clients
    static uint8_t onStartup(void const *arg);

    static void onCleanup(void);

    static void onFlush(void);

    static QSTimeCtr onGetTime(void);

// Global and Local QS filters ...............................................
public:
    static uint8_t glbFilter_[32];                
    static void const *smObj_;         
    static void const *aoObj_;       
    static void const *mpObj_;            
    static void const *eqObj_;             
    static void const *teObj_;            
    static void const *apObj_;

// Miscallaneous .............................................................
public:
    static QSTimeCtr volatile tickCtr_;
};


// 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(rec_)

#define QS_FILTER_OFF(rec_)     QS::filterOff(rec_)

#define QS_FILTER_SM_OBJ(obj_)  (QS::smObj_ = (obj_))

#define QS_FILTER_AO_OBJ(obj_)  (QS::aoObj_ = (obj_))

#define QS_FILTER_MP_OBJ(obj_)  (QS::mpObj_ = (obj_))

#define QS_FILTER_EQ_OBJ(obj_)  (QS::eqObj_ = (obj_))

#define QS_FILTER_TE_OBJ(obj_)  (QS::teObj_ = (obj_))

#define QS_FILTER_AP_OBJ(obj_)  (QS_apObj_ = (obj_))


// Macros to generate user QS records

#define QS_BEGIN_NOLOCK(rec_, obj_) \
    if (((QS::glbFilter_[(uint8_t)(rec_) >> 3U] \
          & (1U << ((uint8_t)(rec_) & 7U))) != 0) \
        && ((QS::apObj_ == (void *)0) || (QS::apObj_ == (obj_)))) \
    { \
        QS::begin((uint8_t)(rec_)); \
        QS_TIME_();

#define QS_END_NOLOCK() \
    QS_END_NOLOCK_()

                                    // QS-specific interrupt locking/unlocking
#ifndef QF_INT_KEY_TYPE
    #define QS_INT_LOCK_KEY_

    #define QS_INT_LOCK_()      QF_INT_LOCK(ignore_)

    #define QS_INT_UNLOCK_()    QF_INT_UNLOCK(ignore_)
#else
    #define QS_INT_LOCK_KEY_    QF_INT_KEY_TYPE intLockKey_;
    #define QS_INT_LOCK_()      QF_INT_LOCK(intLockKey_)
    #define QS_INT_UNLOCK_()    QF_INT_UNLOCK(intLockKey_)
#endif

#define QS_BEGIN(rec_, obj_) \
    if (((QS::glbFilter_[(uint8_t)(rec_) >> 3U] \
          & (1U << ((uint8_t)(rec_) & 7U))) != 0U) \
        && ((QS::apObj_ == (void *)0) || (QS::apObj_ == (obj_)))) \
    { \
        QS_INT_LOCK_KEY_ \
        QS_INT_LOCK_(); \
        QS::begin((uint8_t)(rec_)); \
        QS_TIME_();

#define QS_END() \
    QS_END_()


// Macros for use inside other macros or internally in the QP code

#define QS_BEGIN_(rec_, objFilter_, obj_) \
    if (((QS::glbFilter_[(uint8_t)(rec_) >> 3U] \
          & (1U << ((uint8_t)(rec_) & 7U))) != 0U) \
        && (((objFilter_) == (void *)0) || ((objFilter_) == (obj_)))) \
    { \
        QS_INT_LOCK_(); \
        QS::begin((uint8_t)(rec_));

#define QS_END_() \
        QS::end(); \
        QS_INT_UNLOCK_(); \
    }

#define QS_BEGIN_NOLOCK_(rec_, objFilter_, obj_) \
    if (((QS::glbFilter_[(uint8_t)(rec_) >> 3U] \
          & (1U << ((uint8_t)(rec_) & 7U))) != 0U) \
        && (((objFilter_) == (void *)0) || ((objFilter_) == (obj_)))) \
    { \
        QS::begin((uint8_t)(rec_));

#define QS_END_NOLOCK_() \
        QS::end(); \
    }

#define QS_U8_(data_)           QS::u8_(data_)

#define QS_U16_(data_)          QS::u16_(data_)

#define QS_U32_(data_)          QS::u32_(data_)


#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_))
#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_))
#else

    #define QS_FUN_(fun_)       QS::u32_((uint32_t)(fun_))
#endif

#define QS_STR_(msg_)           QS::str_(msg_)

#define QS_STR_ROM_(msg_)       QS::str_ROM_(msg_)

// Macros for use in the client code

enum QSType {
    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                                      
};

#define QS_I8(width_, data_) \
    QS::u8((uint8_t)(((width_) << 4)) | QS_I8_T, (data_))

#define QS_U8(width_, data_) \
    QS::u8((uint8_t)(((width_) << 4)) | QS_U8_T, (data_))

#define QS_I16(width_, data_) \
    QS::u16((uint8_t)(((width_) << 4)) | QS_I16_T, (data_))

#define QS_U16(width_, data_) \
    QS::u16((uint8_t)(((width_) << 4)) | QS_U16_T, (data_))

#define QS_I32(width_, data_) \
    QS::u32((uint8_t)(((width_) << 4)) | QS_I32_T, (data_))

#define QS_U32(width_, data_) \
    QS::u32((uint8_t)(((width_) << 4)) | QS_U32_T, (data_))

#define QS_F32(width_, data_) \
    QS::f32((uint8_t)(((width_) << 4)) | QS_F32_T, (data_))

#define QS_F64(width_, data_) \
    QS::f64((uint8_t)(((width_) << 4)) | QS_F64_T, (data_))

#define QS_STR(str_)            QS::str(str_)

#define QS_STR_ROM(str_)        QS::str_ROM(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_))
#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_))
#else
    #define QS_FUN(fun_)        QS::u32(QS_FUN_T, (uint32_t)(fun_))
#endif


#define QS_SIG_DICTIONARY(sig_, obj_) \
    if (((QS::glbFilter_[(uint8_t)QS_SIG_DICTIONARY >> 3U] \
          & (1U << ((uint8_t)QS_SIG_DICTIONARY & 7U))) != 0U)) \
    { \
        static char const Q_ROM Q_ROM_VAR sig_name__[] = #sig_; \
        QS_INT_LOCK_KEY_ \
        QS_INT_LOCK_(); \
        QS::begin((uint8_t)QS_SIG_DICTIONARY); \
        QS_SIG_(sig_); \
        QS_OBJ_(obj_); \
        QS_STR_ROM_(sig_name__); \
        QS::end(); \
        QS_INT_UNLOCK_(); \
        QS::onFlush(); \
    } else ((void)0)

#define QS_OBJ_DICTIONARY(obj_) \
    if (((QS::glbFilter_[(uint8_t)QS_OBJ_DICTIONARY >> 3U] \
          & (1U << ((uint8_t)QS_OBJ_DICTIONARY & 7U))) != 0U)) \
    { \
        static char const Q_ROM Q_ROM_VAR obj_name__[] = #obj_; \
        QS_INT_LOCK_KEY_ \
        QS_INT_LOCK_(); \
        QS::begin((uint8_t)QS_OBJ_DICTIONARY); \
        QS_OBJ_(obj_); \
        QS_STR_ROM_(obj_name__); \
        QS::end(); \
        QS_INT_UNLOCK_(); \
        QS::onFlush(); \
    } else ((void)0)

#define QS_FUN_DICTIONARY(fun_) \
    if (((QS::glbFilter_[(uint8_t)QS_FUN_DICTIONARY >> 3U] \
          & (1U << ((uint8_t)QS_FUN_DICTIONARY & 7U))) != 0U)) \
    { \
        static char const Q_ROM Q_ROM_VAR fun_name__[] = #fun_; \
        QS_INT_LOCK_KEY_ \
        QS_INT_LOCK_(); \
        QS::begin((uint8_t)QS_FUN_DICTIONARY); \
        QS_FUN_(fun_); \
        QS_STR_ROM_(fun_name__); \
        QS::end(); \
        QS_INT_UNLOCK_(); \
        QS::onFlush(); \
    } else ((void)0)

#define QS_FLUSH()   QS::onFlush()


#define QF_QS_INT_LOCK() \
    QS_BEGIN_NOLOCK_(QS_QF_INT_LOCK, (void *)0, (void *)0); \
        QS_TIME_(); \
        QS_U8_((uint8_t)(++QF_intLockNest_)); \
    QS_END_NOLOCK_()

#define QF_QS_INT_UNLOCK() \
    QS_BEGIN_NOLOCK_(QS_QF_INT_UNLOCK, (void *)0, (void *)0); \
        QS_TIME_(); \
        QS_U8_((uint8_t)(QF_intLockNest_--)); \
    QS_END_NOLOCK_()

#define QF_QS_ISR_ENTRY(isrnest_, prio_) \
    QS_BEGIN_NOLOCK_(QS_QF_ISR_ENTRY, (void *)0, (void *)0); \
        QS_TIME_(); \
        QS_U8_(isrnest_); \
        QS_U8_(prio_); \
    QS_END_NOLOCK_()

#define QF_QS_ISR_EXIT(isrnest_, prio_) \
    QS_BEGIN_NOLOCK_(QS_QF_ISR_EXIT, (void *)0, (void *)0); \
        QS_TIME_(); \
        QS_U8_(isrnest_); \
        QS_U8_(prio_); \
    QS_END_NOLOCK_()

#define QF_QS_ACTION(act_)      (act_)

extern uint8_t QF_intLockNest_;

#endif                                                                 // qs_h

---