QP/C: qs.h Source File

00001 /*****************************************************************************
00002 * Product:  QS/C platform-independent public interface.
00003 * Last Updated for Version: 4.1.00
00004 * Date of the Last Update:  Oct 09, 2009
00005 *
00006 *                    Q u a n t u m     L e a P s
00007 *                    ---------------------------
00008 *                    innovating embedded systems
00009 *
00010 * Copyright (C) 2002-2009 Quantum Leaps, LLC. All rights reserved.
00011 *
00012 * This software may be distributed and modified under the terms of the GNU
00013 * General Public License version 2 (GPL) as published by the Free Software
00014 * Foundation and appearing in the file GPL.TXT included in the packaging of
00015 * this file. Please note that GPL Section 2[b] requires that all works based
00016 * on this software must also be made publicly available under the terms of
00017 * the GPL ("Copyleft").
00018 *
00019 * Alternatively, this software may be distributed and modified under the
00020 * terms of Quantum Leaps commercial licenses, which expressly supersede
00021 * the GPL and are specifically designed for licensees interested in
00022 * retaining the proprietary status of their code.
00023 *
00024 * Contact information:
00025 * Quantum Leaps Web site:  http://www.quantum-leaps.com
00026 * e-mail:                  info@quantum-leaps.com
00027 *****************************************************************************/
00028 #ifndef qs_h
00029 #define qs_h
00030 
00040 #ifndef Q_SPY
00041     #error "Q_SPY must be defined to include qs.h"
00042 #endif
00043 
00044 /****************************************************************************/
00052 enum QSpyRecords {
00053     /* QEP records */
00054     QS_QEP_STATE_EMPTY,
00055     QS_QEP_STATE_ENTRY,                            
00056     QS_QEP_STATE_EXIT,                              
00057     QS_QEP_STATE_INIT,       
00058     QS_QEP_INIT_TRAN,        
00059     QS_QEP_INTERN_TRAN,               
00060     QS_QEP_TRAN,                        
00061     QS_QEP_IGNORED,          
00062     QS_QEP_DISPATCH,       
00063     QS_QEP_RESERVED0,
00064 
00065     /* QF records */
00066     QS_QF_ACTIVE_ADD,             
00067     QS_QF_ACTIVE_REMOVE,      
00068     QS_QF_ACTIVE_SUBSCRIBE,               
00069     QS_QF_ACTIVE_UNSUBSCRIBE,           
00070     QS_QF_ACTIVE_POST_FIFO,  
00071     QS_QF_ACTIVE_POST_LIFO,  
00072     QS_QF_ACTIVE_GET, 
00073     QS_QF_ACTIVE_GET_LAST,      
00074     QS_QF_EQUEUE_INIT,                  
00075     QS_QF_EQUEUE_POST_FIFO,  
00076     QS_QF_EQUEUE_POST_LIFO,  
00077     QS_QF_EQUEUE_GET,           
00078     QS_QF_EQUEUE_GET_LAST,           
00079     QS_QF_MPOOL_INIT,                    
00080     QS_QF_MPOOL_GET,     
00081     QS_QF_MPOOL_PUT,      
00082     QS_QF_PUBLISH,                              
00083     QS_QF_RESERVED8,
00084     QS_QF_NEW,                                      
00085     QS_QF_GC_ATTEMPT,                       
00086     QS_QF_GC,                                       
00087     QS_QF_TICK,                                   
00088     QS_QF_TIMEEVT_ARM,                          
00089     QS_QF_TIMEEVT_AUTO_DISARM,   
00090     QS_QF_TIMEEVT_DISARM_ATTEMPT,
00091     QS_QF_TIMEEVT_DISARM,        
00092     QS_QF_TIMEEVT_REARM,                      
00093     QS_QF_TIMEEVT_POST,   
00094     QS_QF_RESERVED7,
00095     QS_QF_INT_LOCK,                             
00096     QS_QF_INT_UNLOCK,                         
00097     QS_QF_ISR_ENTRY,                                
00098     QS_QF_ISR_EXIT,                                  
00099     QS_QF_RESERVED6,
00100     QS_QF_RESERVED5,
00101     QS_QF_RESERVED4,
00102     QS_QF_RESERVED3,
00103     QS_QF_RESERVED2,
00104     QS_QF_RESERVED1,
00105     QS_QF_RESERVED0,
00106 
00107     /* QK records */
00108     QS_QK_MUTEX_LOCK,                          
00109     QS_QK_MUTEX_UNLOCK,                      
00110     QS_QK_SCHEDULE,             
00111     QS_QK_RESERVED6,
00112     QS_QK_RESERVED5,
00113     QS_QK_RESERVED4,
00114     QS_QK_RESERVED3,
00115     QS_QK_RESERVED2,
00116     QS_QK_RESERVED1,
00117     QS_QK_RESERVED0,
00118 
00119     /* Miscellaneous QS records */
00120     QS_SIG_DICTIONARY,                         
00121     QS_OBJ_DICTIONARY,                         
00122     QS_FUN_DICTIONARY,                       
00123     QS_ASSERT,                             
00124     QS_RESERVED5,
00125     QS_RESERVED4,
00126     QS_RESERVED3,
00127     QS_RESERVED2,
00128     QS_RESERVED1,
00129     QS_RESERVED0,
00130 
00131     /* User records */
00132     QS_USER             
00133 };
00134 
00135 /* Global and Local QS filters .............................................*/
00136 extern uint8_t QS_glbFilter_[32];              
00137 extern void const *QS_smObj_;       
00138 extern void const *QS_aoObj_;        
00139 extern void const *QS_mpObj_;          
00140 extern void const *QS_eqObj_;           
00141 extern void const *QS_teObj_;          
00142 extern void const *QS_apObj_; 
00147 #define QS_ALL_RECORDS          ((uint8_t)0xFF)
00148 
00149 #ifndef QS_TIME_SIZE
00150 
00158     #define QS_TIME_SIZE 4
00159 #endif
00160 
00161 #if (QS_TIME_SIZE == 1)
00162     typedef uint8_t QSTimeCtr;
00163     #define QS_TIME_()          QS_u8_(QS_onGetTime())
00164 #elif (QS_TIME_SIZE == 2)
00165     typedef uint16_t QSTimeCtr;
00166     #define QS_TIME_()          QS_u16_(QS_onGetTime())
00167 #elif (QS_TIME_SIZE == 4)
00168 
00172     typedef uint32_t QSTimeCtr;
00175     #define QS_TIME_()          QS_u32_(QS_onGetTime())
00176 #else
00177     #error "QS_TIME_SIZE defined incorrectly, expected 1, 2, or 4"
00178 #endif
00179 
00181 extern QSTimeCtr volatile QS_tickCtr_;
00182 
00183 #ifndef Q_ROM                   /* provide the default if Q_ROM NOT defined */
00184     #define Q_ROM
00185 #endif
00186 #ifndef Q_ROM_VAR           /* provide the default if Q_ROM_VAR NOT defined */
00187     #define Q_ROM_VAR
00188 #endif
00189 #ifndef Q_ROM_BYTE         /* provide the default if Q_ROM_BYTE NOT defined */
00190     #define Q_ROM_BYTE(rom_var_)   (rom_var_)
00191 #endif
00192 
00193 /*****************************************************************************
00194 * QS services.
00195 */
00196 /* public methods */
00203 char const Q_ROM * Q_ROM_VAR QS_getVersion(void);
00204 
00223 void QS_initBuf(uint8_t sto[], uint32_t stoSize);
00224 
00237 void QS_filterOn(uint8_t rec);
00238 
00250 void QS_filterOff(uint8_t rec);
00251 
00259 void QS_begin(uint8_t rec);
00260 
00268 void QS_end(void);
00269 
00270 /* unformatted data elements output ........................................*/
00275 void QS_u8_(uint8_t d);
00276 
00281 void QS_u16_(uint16_t d);
00282 
00287 void QS_u32_(uint32_t d);
00288 
00294 void QS_str_(char const *s);
00295 
00301 void QS_str_ROM_(char const Q_ROM * Q_ROM_VAR s);
00302 
00303 /* formatted data elements output ..........................................*/
00308 void QS_u8(uint8_t format, uint8_t d);
00309 
00314 void QS_u16(uint8_t format, uint16_t d);
00315 
00320 void QS_u32(uint8_t format, uint32_t d);
00321 
00326 void QS_f32(uint8_t format, float d);
00327 
00332 void QS_f64(uint8_t format, double d);
00333 
00338 void QS_str(char const *s);
00339 
00345 void QS_str_ROM(char const Q_ROM * Q_ROM_VAR s);
00346 
00351 void QS_mem(uint8_t const *blk, uint8_t size);
00352 
00353 /* QS buffer access ........................................................*/
00363 uint16_t QS_getByte(void);
00364 
00368 #define QS_EOD ((uint16_t)0xFFFF)
00369 
00390 uint8_t const *QS_getBlock(uint16_t *pNbytes);
00391 
00392 /* platform-specific callback functions, need to be implemented by clients  */
00408 uint8_t QS_onStartup(void const *arg);
00409 
00417 void QS_onCleanup(void);
00418 
00426 void QS_onFlush(void);
00427 
00442 QSTimeCtr QS_onGetTime(void);
00443 
00444 /* Macros for adding QS instrumentation to the client code .................*/
00445 
00452 #define QS_INIT(arg_)           QS_onStartup(arg_)
00453 
00460 #define QS_EXIT()               QS_onCleanup()
00461 
00470 #define QS_FILTER_ON(rec_)      QS_filterOn(rec_)
00471 
00479 #define QS_FILTER_OFF(rec_)     QS_filterOff(rec_)
00480 
00505 #define QS_FILTER_SM_OBJ(obj_)  (QS_smObj_ = (obj_))
00506 
00525 #define QS_FILTER_AO_OBJ(obj_)  (QS_aoObj_ = (obj_))
00526 
00544 #define QS_FILTER_MP_OBJ(obj_)  (QS_mpObj_ = (obj_))
00545 
00563 #define QS_FILTER_EQ_OBJ(obj_)  (QS_eqObj_ = (obj_))
00564 
00583 #define QS_FILTER_TE_OBJ(obj_)  (QS_teObj_ = (obj_))
00584 
00599 #define QS_FILTER_AP_OBJ(obj_)  (QS_apObj_ = (obj_))
00600 
00601 /* Macros to generate user QS records ......................................*/
00602 
00605 #define QS_BEGIN_NOLOCK(rec_, obj_) \
00606     if (((QS_glbFilter_[(uint8_t)(rec_) >> 3U] \
00607           & (1U << ((uint8_t)(rec_) & 7U))) != 0U) \
00608         && ((QS_apObj_ == (void *)0) || (QS_apObj_ == (obj_)))) \
00609     { \
00610         QS_begin((uint8_t)(rec_)); \
00611         QS_TIME_(); {
00612 
00615 #define QS_END_NOLOCK() } \
00616     QS_END_NOLOCK_()
00617 
00618                                  /* QS-specific interrupt locking/unlocking */
00619 #ifndef QF_INT_KEY_TYPE
00620 
00628     #define QS_INT_LOCK_KEY_
00629 
00639     #define QS_INT_LOCK_()      QF_INT_LOCK(dummy)
00640 
00650     #define QS_INT_UNLOCK_()    QF_INT_UNLOCK(dummy)
00651 #else
00652     #define QS_INT_LOCK_KEY_    QF_INT_KEY_TYPE intLockKey_;
00653     #define QS_INT_LOCK_()      QF_INT_LOCK(intLockKey_)
00654     #define QS_INT_UNLOCK_()    QF_INT_UNLOCK(intLockKey_)
00655 #endif
00656 
00665 #define QS_BEGIN(rec_, obj_) \
00666     if (((QS_glbFilter_[(uint8_t)(rec_) >> 3U] \
00667           & (1U << ((uint8_t)(rec_) & 7U))) != 0U) \
00668         && ((QS_apObj_ == (void *)0) || (QS_apObj_ == (obj_)))) \
00669     { \
00670         QS_INT_LOCK_KEY_ \
00671         QS_INT_LOCK_(); \
00672         QS_begin((uint8_t)(rec_)); \
00673         QS_TIME_(); {
00674 
00679 #define QS_END() } \
00680     QS_END_()
00681 
00682 
00683 /*****************************************************************************
00684 * Macros for use inside other macros or internally in the QP code
00685 */
00686 
00691 #define QS_BEGIN_(rec_, objFilter_, obj_) \
00692     if (((QS_glbFilter_[(uint8_t)(rec_) >> 3U] \
00693           & (1U << ((uint8_t)(rec_) & 7U))) != 0U) \
00694         && (((objFilter_) == (void *)0) || ((objFilter_) == (obj_)))) \
00695     { \
00696         QS_INT_LOCK_(); \
00697         QS_begin((uint8_t)(rec_));
00698 
00703 #define QS_END_() \
00704         QS_end(); \
00705         QS_INT_UNLOCK_(); \
00706     }
00707 
00713 #define QS_BEGIN_NOLOCK_(rec_, objFilter_, obj_) \
00714     if (((QS_glbFilter_[(uint8_t)(rec_) >> 3U] \
00715           & (1U << ((uint8_t)(rec_) & 7U))) != 0U) \
00716         && (((objFilter_) == (void *)0) || ((objFilter_) == (obj_)))) \
00717     { \
00718         QS_begin((uint8_t)(rec_));
00719 
00725 #define QS_END_NOLOCK_() \
00726         QS_end(); \
00727     }
00728 
00730 #define QS_U8_(data_)           QS_u8_(data_)
00731 
00733 #define QS_U16_(data_)          QS_u16_(data_)
00734 
00736 #define QS_U32_(data_)          QS_u32_(data_)
00737 
00738 
00739 #if (QS_OBJ_PTR_SIZE == 1)
00740     #define QS_OBJ_(obj_)       QS_u8_((uint8_t)(obj_))
00741 #elif (QS_OBJ_PTR_SIZE == 2)
00742     #define QS_OBJ_(obj_)       QS_u16_((uint16_t)(obj_))
00743 #elif (QS_OBJ_PTR_SIZE == 4)
00744     #define QS_OBJ_(obj_)       QS_u32_((uint32_t)(obj_))
00745 #else
00746 
00752     #define QS_OBJ_(obj_)       QS_u32_((uint32_t)(obj_))
00753 #endif
00754 
00755 
00756 #if (QS_FUN_PTR_SIZE == 1)
00757     #define QS_FUN_(fun_)       QS_u8_((uint8_t)(fun_))
00758 #elif (QS_FUN_PTR_SIZE == 2)
00759     #define QS_FUN_(fun_)       QS_u16_((uint16_t)(fun_))
00760 #elif (QS_FUN_PTR_SIZE == 4)
00761     #define QS_FUN_(fun_)       QS_u32_((uint32_t)(fun_))
00762 #else
00763 
00769     #define QS_FUN_(fun_)       QS_u32_((uint32_t)(fun_))
00770 #endif
00771 
00772 
00776 #define QS_STR_(msg_)           QS_str_(msg_)
00777 
00781 #define QS_STR_ROM_(msg_)       QS_str_ROM_(msg_)
00782 
00783 /*****************************************************************************
00784 * Macros for use in the client code
00785 */
00786 
00792 enum QSType {
00793     QS_I8_T,                               
00794     QS_U8_T,                             
00795     QS_I16_T,                             
00796     QS_U16_T,                           
00797     QS_I32_T,                             
00798     QS_U32_T,                           
00799     QS_F32_T,                             
00800     QS_F64_T,                             
00801     QS_STR_T,                      
00802     QS_MEM_T,                      
00803     QS_SIG_T,                                      
00804     QS_OBJ_T,                                    
00805     QS_FUN_T                                   
00806 };
00807 
00809 #define QS_I8(width_, data_) \
00810     QS_u8((uint8_t)(((width_) << 4)) | QS_I8_T, (data_))
00811 
00813 #define QS_U8(width_, data_) \
00814     QS_u8((uint8_t)(((width_) << 4)) | QS_U8_T, (data_))
00815 
00817 #define QS_I16(width_, data_) \
00818     QS_u16((uint8_t)(((width_) << 4)) | QS_I16_T, (data_))
00819 
00821 #define QS_U16(width_, data_) \
00822     QS_u16((uint8_t)(((width_) << 4)) | QS_U16_T, (data_))
00823 
00825 #define QS_I32(width_, data_) \
00826     QS_u32((uint8_t)(((width_) << 4)) | QS_I32_T, (data_))
00827 
00829 #define QS_U32(width_, data_) \
00830     QS_u32((uint8_t)(((width_) << 4)) | QS_U32_T, (data_))
00831 
00833 #define QS_F32(width_, data_) \
00834     QS_f32((uint8_t)(((width_) << 4)) | QS_F32_T, (data_))
00835 
00837 #define QS_F64(width_, data_) \
00838     QS_f64((uint8_t)(((width_) << 4)) | QS_F64_T, (data_))
00839 
00841 #define QS_STR(str_)            QS_str(str_)
00842 
00846 #define QS_STR_ROM(str_)        QS_str_ROM(str_)
00847 
00851 #define QS_MEM(mem_, size_)     QS_mem((mem_), (size_))
00852 
00853 
00854 #if (QS_OBJ_PTR_SIZE == 1)
00855     #define QS_OBJ(obj_)        QS_u8(QS_OBJ_T, (uint8_t)(obj_))
00856 #elif (QS_OBJ_PTR_SIZE == 2)
00857     #define QS_OBJ(obj_)        QS_u16(QS_OBJ_T, (uint16_t)(obj_))
00858 #elif (QS_OBJ_PTR_SIZE == 4)
00859     #define QS_OBJ(obj_)        QS_u32(QS_OBJ_T, (uint32_t)(obj_))
00860 #else
00861 
00862     #define QS_OBJ(obj_)        QS_u32(QS_OBJ_T, (uint32_t)(obj_))
00863 #endif
00864 
00865 
00866 #if (QS_FUN_PTR_SIZE == 1)
00867     #define QS_FUN(fun_)        QS_u8(QS_FUN_T, (uint8_t)(fun_))
00868 #elif (QS_FUN_PTR_SIZE == 2)
00869     #define QS_FUN(fun_)        QS_u16(QS_FUN_T, (uint16_t)(fun_))
00870 #elif (QS_FUN_PTR_SIZE == 4)
00871     #define QS_FUN(fun_)        QS_u32(QS_FUN_T, (uint32_t)(fun_))
00872 #else
00873 
00874     #define QS_FUN(fun_)        QS_u32(QS_FUN_T, (uint32_t)(fun_))
00875 #endif
00876 
00877 
00878 #if (Q_SIGNAL_SIZE == 1)
00879 
00883     #define QS_SIG(sig_, obj_) \
00884         QS_u8(QS_SIG_T, (sig_)); \
00885         QS_OBJ_(obj_)
00886 #elif (Q_SIGNAL_SIZE == 2)
00887     #define QS_SIG(sig_, obj_) \
00888         QS_u16(QS_SIG_T, (sig_)); \
00889         QS_OBJ_(obj_)
00890 #elif (Q_SIGNAL_SIZE == 4)
00891     #define QS_SIG(sig_, obj_) \
00892         QS_u32(QS_SIG_T, (sig_)); \
00893         QS_OBJ_(obj_)
00894 #endif
00895 
00936 #define QS_SIG_DICTIONARY(sig_, obj_) \
00937     if (((QS_glbFilter_[(uint8_t)QS_SIG_DICTIONARY >> 3U] \
00938           & (1U << ((uint8_t)QS_SIG_DICTIONARY & 7U))) != 0U)) \
00939     { \
00940         static char const Q_ROM Q_ROM_VAR sig_name__[] = #sig_; \
00941         QS_INT_LOCK_KEY_ \
00942         QS_INT_LOCK_(); \
00943         QS_begin((uint8_t)QS_SIG_DICTIONARY); \
00944         QS_SIG_(sig_); \
00945         QS_OBJ_(obj_); \
00946         QS_STR_ROM_(sig_name__); \
00947         QS_end(); \
00948         QS_INT_UNLOCK_(); \
00949         QS_onFlush(); \
00950     } else ((void)0)
00951 
00965 #define QS_OBJ_DICTIONARY(obj_) \
00966     if (((QS_glbFilter_[(uint8_t)QS_OBJ_DICTIONARY >> 3U] \
00967           & (1U << ((uint8_t)QS_OBJ_DICTIONARY & 7U))) != 0U)) \
00968     { \
00969         static char const Q_ROM Q_ROM_VAR obj_name__[] = #obj_; \
00970         QS_INT_LOCK_KEY_ \
00971         QS_INT_LOCK_(); \
00972         QS_begin((uint8_t)QS_OBJ_DICTIONARY); \
00973         QS_OBJ_(obj_); \
00974         QS_STR_ROM_(obj_name__); \
00975         QS_end(); \
00976         QS_INT_UNLOCK_(); \
00977         QS_onFlush(); \
00978     } else ((void)0)
00979 
00992 #define QS_FUN_DICTIONARY(fun_) \
00993     if (((QS_glbFilter_[(uint8_t)QS_FUN_DICTIONARY >> 3U] \
00994           & (1U << ((uint8_t)QS_FUN_DICTIONARY & 7U))) != 0U)) \
00995     { \
00996         static char const Q_ROM Q_ROM_VAR fun_name__[] = #fun_; \
00997         QS_INT_LOCK_KEY_ \
00998         QS_INT_LOCK_(); \
00999         QS_begin((uint8_t)QS_FUN_DICTIONARY); \
01000         QS_FUN_(fun_); \
01001         QS_STR_ROM_(fun_name__); \
01002         QS_end(); \
01003         QS_INT_UNLOCK_(); \
01004         QS_onFlush(); \
01005     } else ((void)0)
01006 
01007 
01015 #define QS_FLUSH()   QS_onFlush()
01016 
01018 #define QF_QS_INT_LOCK() \
01019     QS_BEGIN_NOLOCK_(QS_QF_INT_LOCK, (void *)0, (void *)0); \
01020         QS_TIME_(); \
01021         QS_U8_((uint8_t)(++QF_intLockNest_)); \
01022     QS_END_NOLOCK_()
01023 
01025 #define QF_QS_INT_UNLOCK() \
01026     QS_BEGIN_NOLOCK_(QS_QF_INT_UNLOCK, (void *)0, (void *)0); \
01027         QS_TIME_(); \
01028         QS_U8_((uint8_t)(QF_intLockNest_--)); \
01029     QS_END_NOLOCK_()
01030 
01032 #define QF_QS_ISR_ENTRY(isrnest_, prio_) \
01033     QS_BEGIN_NOLOCK_(QS_QF_ISR_ENTRY, (void *)0, (void *)0); \
01034         QS_TIME_(); \
01035         QS_U8_(isrnest_); \
01036         QS_U8_(prio_); \
01037     QS_END_NOLOCK_()
01038 
01040 #define QF_QS_ISR_EXIT(isrnest_, prio_) \
01041     QS_BEGIN_NOLOCK_(QS_QF_ISR_EXIT, (void *)0, (void *)0); \
01042         QS_TIME_(); \
01043         QS_U8_(isrnest_); \
01044         QS_U8_(prio_); \
01045     QS_END_NOLOCK_()
01046 
01048 #define QF_QS_ACTION(act_)      (act_)
01049 
01054 extern uint8_t QF_intLockNest_;
01055 
01056 #endif                                                             /* qs_h  */
01057