QP/C
Defines | Typedefs | Enumerations | Functions | Variables
qs.h File Reference

QS/C platform-independent public interface. More...

Go to the source code of this file.

Defines

#define QS_ALL_RECORDS   ((uint8_t)0xFF)
 Specification of all QS records for QS_FILTER_ON() and QS_FILTER_OFF()
#define QS_TIME_SIZE   4
 The size (in bytes) of the QS time stamp. Valid values: 1, 2, or 4; default 4.
#define QS_TIME_()   (QS_u32_(QS_onGetTime()))
 Internal macro to output time stamp to a QS record.
#define QS_EOD   ((uint16_t)0xFFFF)
 Constant representing End-Of-Data condition returned from the QS_getByte() function.
#define QS_INIT(arg_)   (QS_onStartup(arg_) != (uint8_t)0)
 Initialize the QS facility.
#define QS_EXIT()   (QS_onCleanup())
 Cleanup the QS facility.
#define QS_FILTER_ON(rec_)   (QS_filterOn((uint8_t)(rec_)))
 Global Filter ON for a given record type rec.
#define QS_FILTER_OFF(rec_)   (QS_filterOff((uint8_t)(rec_)))
 Global filter OFF for a given record type rec.
#define QS_FILTER_SM_OBJ(obj_)   (QS_smObj_ = (obj_))
 Local Filter for a given state machine object obj_.
#define QS_FILTER_AO_OBJ(obj_)   (QS_aoObj_ = (obj_))
 Local Filter for a given active object obj_.
#define QS_FILTER_MP_OBJ(obj_)   (QS_mpObj_ = (obj_))
 Local Filter for a given memory pool object obj_.
#define QS_FILTER_EQ_OBJ(obj_)   (QS_eqObj_ = (obj_))
 Local Filter for a given event queue object obj_.
#define QS_FILTER_TE_OBJ(obj_)   (QS_teObj_ = (obj_))
 Local Filter for a given time event object obj_.
#define QS_FILTER_AP_OBJ(obj_)   (QS_apObj_ = (obj_))
 Local Filter for a generic application object obj_.
#define QS_BEGIN_NOCRIT(rec_, obj_)
 Begin a QS user record without entering critical section.
#define QS_END_NOCRIT()
 End a QS user record without exiting critical section.
#define QS_CRIT_STAT_
 This is an internal macro for defining the critical section status type.
#define QS_CRIT_ENTRY_()   QF_CRIT_ENTRY(dummy)
 This is an internal macro for entering a critical section.
#define QS_CRIT_EXIT_()   QF_CRIT_EXIT(dummy)
 This is an internal macro for exiting a critical section.
#define QS_BEGIN(rec_, obj_)
 Begin a user QS record with entering critical section.
#define QS_END()
 End a QS record with exiting critical section.
#define QS_BEGIN_(rec_, objFilter_, obj_)
 Internal QS macro to begin a QS record with entering critical section.
#define QS_END_()
 Internal QS macro to end a QS record with exiting critical section.
#define QS_BEGIN_NOCRIT_(rec_, objFilter_, obj_)
 Internal QS macro to begin a QS record without entering critical section.
#define QS_END_NOCRIT_()
 Internal QS macro to end a QS record without exiting critical section.
#define QS_U8_(data_)   (QS_u8_(data_))
 Internal QS macro to output an unformatted uint8_t data element.
#define QS_U16_(data_)   (QS_u16_(data_))
 Internal QS macro to output an unformatted uint16_t data element.
#define QS_U32_(data_)   (QS_u32_(data_))
 Internal QS macro to output an unformatted uint32_t data element.
#define QS_OBJ_(obj_)   (QS_u32_((uint32_t)(obj_))
 Internal QS macro to output an unformatted object pointer data element.
#define QS_FUN_(fun_)   (QS_u32_((uint32_t)(fun_)))
 Internal QS macro to output an unformatted function pointer data element.
#define QS_STR_(msg_)   (QS_str_(msg_))
 Internal QS macro to output a zero-terminated ASCII string data element.
#define QS_STR_ROM_(msg_)   (QS_str_ROM_(msg_))
 Internal QS macro to output a zero-terminated ASCII string allocated in ROM data element.
#define QS_I8(width_, data_)   (QS_u8((uint8_t)(((width_) << 4)) | (uint8_t)QS_I8_T, (data_)))
 Output formatted int8_t to the QS record.
#define QS_U8(width_, data_)   (QS_u8((uint8_t)(((width_) << 4)) | (uint8_t)QS_U8_T, (data_)))
 Output formatted uint8_t to the QS record.
#define QS_I16(width_, data_)   (QS_u16((uint8_t)(((width_) << 4)) | (uint8_t)QS_I16_T, (data_)))
 Output formatted int16_t to the QS record.
#define QS_U16(width_, data_)   (QS_u16((uint8_t)(((width_) << 4)) | (uint8_t)QS_U16_T, (data_)))
 Output formatted uint16_t to the QS record.
#define QS_I32(width_, data_)   (QS_u32((uint8_t)(((width_) << 4)) | (uint8_t)QS_I32_T, (data_)))
 Output formatted int32_t to the QS record.
#define QS_U32(width_, data_)   (QS_u32((uint8_t)(((width_) << 4)) | (uint8_t)QS_U32_T, (data_)))
 Output formatted uint32_t to the QS record.
#define QS_F32(width_, data_)   (QS_f32((uint8_t)(((width_) << 4)) | (uint8_t)QS_F32_T, (data_)))
 Output formatted 32-bit floating point number to the QS record.
#define QS_F64(width_, data_)   (QS_f64((uint8_t)(((width_) << 4)) | (uint8_t)QS_F64_T, (data_)))
 Output formatted 64-bit floating point number to the QS record.
#define QS_I64(width_, data_)   (QS_u64((uint8_t)(((width_) << 4)) | (uint8_t)QS_I64_T, (data_)))
 Output formatted int64_t to the QS record.
#define QS_U64(width_, data_)   (QS_u64((uint8_t)(((width_) << 4)) | (uint8_t)QS_U64_T, (data_)))
 Output formatted uint64_t to the QS record.
#define QS_U32_HEX(width_, data_)   (QS_u32((uint8_t)(((width_) << 4)) | (uint8_t)QS_U32_HEX_T, (data_)))
 Output formatted uint32_t to the QS record.
#define QS_STR(str_)   (QS_str(str_))
 Output formatted zero-terminated ASCII string to the QS record.
#define QS_STR_ROM(str_)   (QS_str_ROM(str_))
 Output formatted zero-terminated ASCII string from ROM to the QS record.
#define QS_MEM(mem_, size_)   (QS_mem((mem_), (size_)))
 Output formatted memory block of up to 255 bytes to the QS record.
#define QS_OBJ(obj_)   (QS_u32(QS_OBJ_T, (uint32_t)(obj_)))
 Output formatted object pointer to the QS record.
#define QS_FUN(fun_)   (QS_u32(QS_FUN_T, (uint32_t)(fun_)))
 Output formatted function pointer to the QS record.
#define QS_RESET()
 Reset the QS session.
#define QS_SIG_DICTIONARY(sig_, obj_)
 Output signal dictionary record.
#define QS_OBJ_DICTIONARY(obj_)
 Output object dictionary record.
#define QS_FUN_DICTIONARY(fun_)
 Output function dictionary record.
#define QS_USR_DICTIONARY(rec_)
 Output user QS rectord dictionary record.
#define QS_ASSERTION(module_, loc_)
 Output the assertion violation.
#define QS_FLUSH()   (QS_onFlush())
 Flush the QS trace data to the host.
#define QF_QS_CRIT_ENTRY()
 Output the critical section entry.
#define QF_QS_CRIT_EXIT()
 Output the critical section exit.
#define QF_QS_ISR_ENTRY(isrnest_, prio_)
 Output the interrupt entry record.
#define QF_QS_ISR_EXIT(isrnest_, prio_)
 Output the interrupt exit record.
#define QF_QS_ACTION(act_)   (act_)
 Execute an action that is only necessary for QS output.

Typedefs

typedef uint32_t QSTimeCtr
 The type of the QS time stamp.

Enumerations

enum  QSpyRecords {
  QS_QP_RESET, 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, 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_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_TIMEEVT_CTR, QS_QF_CRIT_ENTRY, QS_QF_CRIT_EXIT,
  QS_QF_ISR_ENTRY, QS_QF_ISR_EXIT, QS_QF_INT_DISABLE, QS_QF_INT_ENABLE ,
  QS_QK_MUTEX_LOCK, QS_QK_MUTEX_UNLOCK, QS_QK_SCHEDULE , QS_SIG_DIC,
  QS_OBJ_DIC, QS_FUN_DIC, QS_USR_DIC , QS_ASSERT,
  QS_USER
}
 Quantum Spy record types. More...
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, QS_I64_T, QS_U64_T, QS_U32_HEX_T
}
 Enumerates data formats recognized by QS. More...

Functions

char_t const Q_ROM *Q_ROM_VAR QS_getVersion (void)
 Get the current version of QS.
void QS_initBuf (uint8_t sto[], uint32_t stoSize)
 Initialize the QS data buffer.
void QS_filterOn (uint8_t rec)
 Turn the global Filter on for a given record type rec.
void QS_filterOff (uint8_t rec)
 Turn the global Filter off for a given record type rec.
void QS_begin (uint8_t rec)
 Mark the begin of a QS record rec.
void QS_end (void)
 Mark the end of a QS record rec.
void QS_u8_ (uint8_t d)
 output uint8_t data element without format information
void QS_u16_ (uint16_t d)
 Output uint16_t data element without format information.
void QS_u32_ (uint32_t d)
 Output uint32_t data element without format information.
void QS_str_ (char_t const *s)
 Output zero-terminated ASCII string element without format information.
void QS_str_ROM_ (char_t const Q_ROM *Q_ROM_VAR s)
 Output zero-terminated ASCII string element allocated in ROM without format information.
void QS_u8 (uint8_t format, uint8_t d)
 Output uint8_t data element with format information.
void QS_u16 (uint8_t format, uint16_t d)
 output uint16_t data element with format information
void QS_u32 (uint8_t format, uint32_t d)
 Output uint32_t data element with format information.
void QS_f32 (uint8_t format, float32_t f)
 Output 32-bit floating point data element with format information.
void QS_f64 (uint8_t format, float64_t d)
 Output 64-bit floating point data element with format information.
void QS_str (char_t const *s)
 Output zero-terminated ASCII string element with format information.
void QS_str_ROM (char_t const Q_ROM *Q_ROM_VAR s)
 Output zero-terminated ASCII string element allocated in ROM with format information.
void QS_mem (uint8_t const *blk, uint8_t size)
 Output memory block of up to 255-bytes with format information.
uint16_t QS_getByte (void)
 Byte-oriented interface to the QS data buffer.
uint8_t const * QS_getBlock (uint16_t *pNbytes)
 Block-oriented interface to the QS data buffer.
uint8_t QS_onStartup (void const *arg)
 Callback to startup the QS facility.
void QS_onCleanup (void)
 Callback to cleanup the QS facility.
void QS_onFlush (void)
 Callback to flush the QS trace data to the host.
QSTimeCtr QS_onGetTime (void)
 Callback to obtain a timestamp for a QS record.

Variables

uint8_t QS_glbFilter_ [32]
void const * QS_smObj_
void const * QS_aoObj_
void const * QS_mpObj_
void const * QS_eqObj_
void const * QS_teObj_
void const * QS_apObj_
QSTimeCtr QS_tickCtr_
uint8_t QF_critNest_
 critical section nesting level

Detailed Description

QS/C platform-independent public interface.

This header file must be included directly or indirectly in all modules (*.c files) that use QS/C.

Definition in file qs.h.

Define Documentation

#define QS_BEGIN (   rec_,
  obj_ 
)
Value:
if (((QS_glbFilter_[(uint8_t)(rec_) >> 3] \
          & (uint8_t)(1U << ((uint8_t)(rec_) & (uint8_t)7))) != (uint8_t)0) \
        && ((QS_apObj_ == (void *)0) || (QS_apObj_ == (obj_)))) \
    { \
        QS_CRIT_STAT_ \
        QS_CRIT_ENTRY_(); \
        QS_begin((uint8_t)(rec_)); \
        QS_TIME_(); {

Begin a user QS record with entering critical section.

The following example shows how to build a user QS record using the macros QS_BEGIN, QS_END, and the formatted output macros: QS_U8 and QS_STR. 

enum UserSpyRecords {
    . . .
    QS_DPP_DISPLAY = QS_USER               /* define a user QS record types */
    . . .
};

void displyPhilStat(uint8_t n, char const *stat) {
    . . .

    QS_BEGIN(QS_DPP_DISPLAY);                    /* output a user QS record */
        QS_U8(1, n);
        QS_STR(stat);
    QS_END();
}
Note:
Must always be used in pair with QS_END

Definition at line 691 of file qs.h.

#define QS_BEGIN_ (   rec_,
  objFilter_,
  obj_ 
)
Value:
if (((QS_glbFilter_[(uint8_t)(rec_) >> 3] \
          & (uint8_t)(1U << ((uint8_t)(rec_) & (uint8_t)7))) != (uint8_t)0) \
        && (((objFilter_) == (void *)0) || ((objFilter_) == (obj_)))) \
    { \
        QS_CRIT_ENTRY_(); \
        QS_begin((uint8_t)(rec_));

Internal QS macro to begin a QS record with entering critical section.

Note:
This macro is intended to use only inside QP components and NOT at the application level.
See also:
QS_BEGIN

Definition at line 719 of file qs.h.

Referenced by QEQueue_init(), QFsm_dispatch(), QFsm_init(), QHsm_dispatch(), QHsm_init(), and QMPool_init().

#define QS_BEGIN_NOCRIT_ (   rec_,
  objFilter_,
  obj_ 
)
Value:
if (((QS_glbFilter_[(uint8_t)(rec_) >> 3] \
          & (uint8_t)(1U << ((uint8_t)(rec_) & (uint8_t)7))) != (uint8_t)0) \
        && (((objFilter_) == (void *)0) || ((objFilter_) == (obj_)))) \
    { \
        QS_begin((uint8_t)(rec_));

Internal QS macro to begin a QS record without entering critical section.

Note:
This macro is intended to use only inside QP components and NOT at the application level.
See also:
QS_BEGIN_NOCRIT

Definition at line 744 of file qs.h.

Referenced by QActive_get_(), QActive_postFIFO(), QActive_postLIFO(), QActive_subscribe(), QActive_unsubscribe(), QActive_unsubscribeAll(), QEQueue_get(), QEQueue_postFIFO(), QEQueue_postLIFO(), QF_add_(), QF_gc(), QF_publish(), QF_remove_(), QF_tick(), QK_mutexLock(), QK_mutexUnlock(), QK_sched_(), QK_schedExt_(), QMPool_get(), QMPool_put(), QTimeEvt_arm_(), QTimeEvt_ctr(), QTimeEvt_disarm(), and QTimeEvt_rearm().

#define QS_CRIT_ENTRY_ ( )    QF_CRIT_ENTRY(dummy)

This is an internal macro for entering a critical section.

The purpose of this macro is to enable writing the same code for the case when critical section status type is defined and when it is not. If the macro QF_CRIT_STAT_TYPE is defined, this internal macro invokes QF_CRIT_ENTRY passing the key variable as the parameter. Otherwise QF_CRIT_ENTRY is invoked with a dummy parameter.

See also:
QF_CRIT_ENTRY

Definition at line 664 of file qs.h.

#define QS_CRIT_EXIT_ ( )    QF_CRIT_EXIT(dummy)

This is an internal macro for exiting a critical section.

The purpose of this macro is to enable writing the same code for the case when critical section status type is defined and when it is not. If the macro QF_CRIT_STAT_TYPE is defined, this internal macro invokes QF_CRIT_EXIT passing the key variable as the parameter. Otherwise QF_CRIT_EXIT is invoked with a dummy parameter.

See also:
QF_CRIT_EXIT

Definition at line 675 of file qs.h.

#define QS_CRIT_STAT_

This is an internal macro for defining the critical section status type.

The purpose of this macro is to enable writing the same code for the case when critical section status type is defined and when it is not. If the macro QF_CRIT_STAT_TYPE is defined, this internal macro provides the definition of the critical section status variable. Otherwise this macro is empty.

See also:
QF_CRIT_STAT_TYPE

Definition at line 653 of file qs.h.

Referenced by QEQueue_init(), QFsm_dispatch(), QFsm_init(), QHsm_dispatch(), QHsm_init(), and QMPool_init().

#define QS_END ( )
Value:
} \
    QS_END_()

End a QS record with exiting critical section.

See also:
example for QS_BEGIN
Note:
Must always be used in pair with QS_BEGIN

Definition at line 705 of file qs.h.

#define QS_END_ ( )
Value:
QS_end(); \
        QS_CRIT_EXIT_(); \
    }

Internal QS macro to end a QS record with exiting critical section.

Note:
This macro is intended to use only inside QP components and NOT at the application level.
See also:
QS_END

Definition at line 733 of file qs.h.

Referenced by QEQueue_init(), QFsm_dispatch(), QFsm_init(), QHsm_dispatch(), QHsm_init(), and QMPool_init().

#define QS_END_NOCRIT_ ( )
Value:
QS_end(); \
    }

Internal QS macro to end a QS record without exiting critical section.

Note:
This macro is intended to use only inside QP components and NOT at the application level.
See also:
QS_END_NOCRIT

Definition at line 756 of file qs.h.

Referenced by QActive_get_(), QActive_postFIFO(), QActive_postLIFO(), QActive_subscribe(), QActive_unsubscribe(), QActive_unsubscribeAll(), QEQueue_get(), QEQueue_postFIFO(), QEQueue_postLIFO(), QF_add_(), QF_gc(), QF_publish(), QF_remove_(), QF_tick(), QK_mutexLock(), QK_mutexUnlock(), QK_sched_(), QK_schedExt_(), QMPool_get(), QMPool_put(), QTimeEvt_arm_(), QTimeEvt_ctr(), QTimeEvt_disarm(), and QTimeEvt_rearm().

#define QS_EXIT ( )    (QS_onCleanup())

Cleanup the QS facility.

This macro provides an indirection layer to invoke the QS cleanup routine if #Q_SPY is defined, or do nothing if #Q_SPY is not defined.

See also:
QS_exit()

Definition at line 483 of file qs.h.

#define QS_FILTER_AO_OBJ (   obj_)    (QS_aoObj_ = (obj_))

Local Filter for a given active object obj_.

This macro sets up the active object local filter if #Q_SPY is defined, or does nothing if #Q_SPY is not defined. The argument obj_ is the pointer to the active object that you want to monitor.

The active object filter allows you to filter QS records pertaining only to a given active object. With this filter disabled, QS will output records from all active objects in your application. The object filter is disabled by setting the active object pointer obj_ to NULL.

The active object filter affects the following QS 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, and QS_QF_ACTIVE_GET_LAST.

See also:
Example of using QS filters in QS_FILTER_ON documentation

Definition at line 548 of file qs.h.

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

Local Filter for a generic application object obj_.

This macro sets up the application object local filter if #Q_SPY is defined, or does nothing if #Q_SPY is not defined. The argument obj_ is the pointer to the application object you want to monitor.

The application object filter allows you to filter QS records pertaining only to a given application object. With this filter disabled, QS will output records from all application-records enabled by the global filter. The local filter is disabled by setting the time event pointer obj_ to NULL.

See also:
Example of using QS filters in QS_FILTER_ON documentation

Definition at line 622 of file qs.h.

#define QS_FILTER_EQ_OBJ (   obj_)    (QS_eqObj_ = (obj_))

Local Filter for a given event queue object obj_.

This macro sets up the event queue object local filter if #Q_SPY is defined, or does nothing if #Q_SPY is not defined. The argument obj_ is the pointer to the "raw" thread-safe queue object you want to monitor.

The event queue filter allows you to filter QS records pertaining only to a given event queue. With this filter disabled, QS will output records from all event queues in your application. The object filter is disabled by setting the event queue pointer obj_ to NULL.

The event queue filter affects the following QS records: QS_QF_EQUEUE_INIT, QS_QF_EQUEUE_POST_FIFO, QS_QF_EQUEUE_POST_LIFO, QS_QF_EQUEUE_GET, and QS_QF_EQUEUE_GET_LAST.

See also:
Example of using QS filters in QS_FILTER_ON documentation

Definition at line 586 of file qs.h.

#define QS_FILTER_MP_OBJ (   obj_)    (QS_mpObj_ = (obj_))

Local Filter for a given memory pool object obj_.

This macro sets up the memory pool local object filter if #Q_SPY is defined, or does nothing if #Q_SPY is not defined. The argument obj_ is the pointer to the memory buffer used during the initialization of the event pool with QF_poolInit().

The memory pool filter allows you to filter QS records pertaining only to a given memory pool. With this filter disabled, QS will output records from all memory pools in your application. The object filter is disabled by setting the memory pool pointer obj_ to NULL.

The memory pool filter affects the following QS records: QS_QF_MPOOL_INIT, QS_QF_MPOOL_GET, and QS_QF_MPOOL_PUT.

See also:
Example of using QS filters in QS_FILTER_ON documentation

Definition at line 567 of file qs.h.

#define QS_FILTER_OFF (   rec_)    (QS_filterOff((uint8_t)(rec_)))

Global filter OFF for a given record type rec.

This macro provides an indirection layer to call QS_filterOff() if #Q_SPY is defined, or do nothing if #Q_SPY is not defined.

See also:
Example of using QS filters in QS_FILTER_ON documentation

Definition at line 502 of file qs.h.

#define QS_FILTER_ON (   rec_)    (QS_filterOn((uint8_t)(rec_)))

Global Filter ON for a given record type rec.

This macro provides an indirection layer to call QS_filterOn() if #Q_SPY is defined, or do nothing if #Q_SPY is not defined.

The following example shows how to use QS filters: 

main () {
    . . .

    if (!QS_INIT("1")) {                   /* Initialize QSpy to use UART 1 */
        return -1;                             /* Unable to initialize QSpy */
    }
    QS_FILTER_IN(QS_ALL_RECORDS);     /* start with enabling all QS records */

    QS_FILTER_OUT(QS_QK_INT_LOCK);      /* disable QS output of this record */
    QS_FILTER_OUT(QS_QK_INT_UNLOCK);    /* disable QS output of this record */
    QS_FILTER_OUT(QS_QK_ISR_ENTRY);     /* disable QS output of this record */
    QS_FILTER_OUT(QS_QK_ISR_EXIT);      /* disable QS output of this record */

    QS_FILTER_SM_OBJ(&philo[3]);    /* trace only this state machine object */

    QS_FILTER_AO_OBJ(&philo[3]);           /* trace only this active object */

    QS_FILTER_MP_OBJ(regSizePoolSto);         /* trace only this event pool */

    QS_FILTER_EQ_OBJ(&rawQueue);             /* trace only this event queue */

    QS_FILTER_TE_OBJ(&philo[3].timeEvt);      /* trace only this time event */

    . . .
}

Definition at line 493 of file qs.h.

#define QS_FILTER_SM_OBJ (   obj_)    (QS_smObj_ = (obj_))

Local Filter for a given state machine object obj_.

This macro sets up the state machine object local filter if #Q_SPY is defined, or does nothing if #Q_SPY is not defined. The argument obj_ is the pointer to the state machine object that you want to monitor.

The state machine object filter allows you to filter QS records pertaining only to a given state machine object. With this filter disabled, QS will output records from all state machines in your application. The object filter is disabled by setting the state machine pointer to NULL.

The state machine filter affects the following QS records: QS_QEP_STATE_ENTRY, QS_QEP_STATE_EXIT, QS_QEP_STATE_INIT, QS_QEP_INIT_TRAN, QS_QEP_INTERN_TRAN, QS_QEP_TRAN, and QS_QEP_IGNORED.

Note:
Because active objects are state machines at the same time, the state machine filter (QS_FILTER_SM_OBJ) pertains to active objects as well. However, the state machine filter is more general, because it can be used only for state machines that are not active objects, such as "Orthogonal Components".
See also:
Example of using QS filters in QS_FILTER_ON documentation

Definition at line 528 of file qs.h.

#define QS_FILTER_TE_OBJ (   obj_)    (QS_teObj_ = (obj_))

Local Filter for a given time event object obj_.

This macro sets up the time event object local filter if #Q_SPY is defined, or does nothing if #Q_SPY is not defined. The argument obj_ is the pointer to the time event object you want to monitor.

The time event filter allows you to filter QS records pertaining only to a given time event. With this filter disabled, QS will output records from all time events in your application. The object filter is disabled by setting the time event pointer obj_ to NULL.

The time event filter affects the following QS 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, and ::QS_QF_TIMEEVT_PUBLISH.

See also:
Example of using QS filters in QS_FILTER_ON documentation

Definition at line 606 of file qs.h.

#define QS_FLUSH ( )    (QS_onFlush())

Flush the QS trace data to the host.

This macro invokes the QS_flush() platform-dependent callback function to flush the QS trace buffer to the host. The function typically busy-waits until all the data in the buffer is sent to the host. This is acceptable only in the initial transient.

Definition at line 1134 of file qs.h.

Referenced by QActive_start().

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

Internal QS macro to output an unformatted function pointer data element.

Note:
the size of the pointer depends on the macro #QS_FUN_PTR_SIZE. If the size is not defined the size of pointer is assumed 4-bytes.

Definition at line 817 of file qs.h.

Referenced by QFsm_dispatch(), QFsm_init(), QHsm_dispatch(), and QHsm_init().

#define QS_FUN_DICTIONARY (   fun_)
Value:
do { \
    if (((QS_glbFilter_[(uint8_t)QS_FUN_DIC >> 3] \
      & (uint8_t)(1U << ((uint8_t)QS_FUN_DIC & (uint8_t)7))) != (uint8_t)0)) \
    { \
        static char_t const Q_ROM Q_ROM_VAR fun_name__[] = #fun_; \
        QS_CRIT_STAT_ \
        QS_CRIT_ENTRY_(); \
        QS_begin((uint8_t)QS_FUN_DIC); \
        QS_FUN_(fun_); \
        QS_STR_ROM_(&fun_name__[0]); \
        QS_end(); \
        QS_CRIT_EXIT_(); \
        QS_onFlush(); \
    } \
} while (0)

Output function dictionary record.

A function dictionary record associates the binary address of a function in the target's memory with the human-readable name of the function.

Providing a function dictionary QS record can vastly improve readability of the QS log, because instead of dealing with cryptic machine addresses the QSpy host utility can display human-readable function names.

The example from QS_SIG_DICTIONARY shows the definition of a function dictionary.

Definition at line 1080 of file qs.h.

#define QS_INIT (   arg_)    (QS_onStartup(arg_) != (uint8_t)0)

Initialize the QS facility.

This macro provides an indirection layer to invoke the QS initialization routine if #Q_SPY is defined, or do nothing if #Q_SPY is not defined.

See also:
QS_onStartup(), example of setting up a QS filter in QS_FILTER_ON

Definition at line 475 of file qs.h.

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

Internal QS macro to output an unformatted object pointer data element.

Note:
the size of the pointer depends on the macro #QS_OBJ_PTR_SIZE. If the size is not defined the size of pointer is assumed 4-bytes.

Definition at line 798 of file qs.h.

Referenced by QActive_get_(), QActive_postFIFO(), QActive_postLIFO(), QActive_subscribe(), QActive_unsubscribe(), QActive_unsubscribeAll(), QEQueue_get(), QEQueue_init(), QEQueue_postFIFO(), QEQueue_postLIFO(), QF_add_(), QF_publish(), QF_remove_(), QF_tick(), QFsm_dispatch(), QFsm_init(), QHsm_dispatch(), QHsm_init(), QMPool_get(), QMPool_init(), QMPool_put(), QTimeEvt_arm_(), QTimeEvt_ctr(), QTimeEvt_disarm(), and QTimeEvt_rearm().

#define QS_OBJ_DICTIONARY (   obj_)
Value:
do { \
    if (((QS_glbFilter_[(uint8_t)QS_OBJ_DIC >> 3] \
      & (uint8_t)(1U << ((uint8_t)QS_OBJ_DIC & (uint8_t)7))) != (uint8_t)0)) \
    { \
        static char_t const Q_ROM Q_ROM_VAR obj_name__[] = #obj_; \
        QS_CRIT_STAT_ \
        QS_CRIT_ENTRY_(); \
        QS_begin((uint8_t)QS_OBJ_DIC); \
        QS_OBJ_(obj_); \
        QS_STR_ROM_(&obj_name__[0]); \
        QS_end(); \
        QS_CRIT_EXIT_(); \
        QS_onFlush(); \
    } \
} while (0)

Output object dictionary record.

An object dictionary record associates the binary address of an object in the target's memory with the human-readable name of the object.

Providing an object dictionary QS record can vastly improve readability of the QS log, because instead of dealing with cryptic machine addresses the QSpy host utility can display human-readable object names.

The following example shows the definition of object dictionary entry for the Table active object: 

void tableStart(uint8_t prio,
                QEvent const *qSto[], uint32_t qLen,
                void *stkSto, uint32_t stkSize)
{
    static Table table;

    QS_OBJ_DICTIONARY(table);        /* provide object dictionary for table */

    Table_ctor(&table);
    QActive_start((QActive *)&table, prio,
                  qSto, qLen, stkSto, stkSize,
                  (QEvent *)0);
}

Definition at line 1052 of file qs.h.

#define QS_RESET ( )
Value:
do { \
    if (((QS_glbFilter_[(uint8_t)QS_QP_RESET >> 3] \
      & (uint8_t)(1U << ((uint8_t)QS_QP_RESET & (uint8_t)7))) != (uint8_t)0))\
    { \
        QS_CRIT_STAT_ \
        QS_CRIT_ENTRY_(); \
        QS_begin((uint8_t)QS_QP_RESET); \
        QS_end(); \
        QS_CRIT_EXIT_(); \
        QS_onFlush(); \
    } \
} while (0)

Reset the QS session.

This trace record should be generated at the beginning of the QS session. It informs the QSPY host application that the new session has been started.

Definition at line 969 of file qs.h.

#define QS_SIG_DICTIONARY (   sig_,
  obj_ 
)
Value:
do { \
    if (((QS_glbFilter_[(uint8_t)QS_SIG_DIC >> 3] \
      & (uint8_t)(1U << ((uint8_t)QS_SIG_DIC & (uint8_t)7))) != (uint8_t)0)) \
    { \
        static char_t const Q_ROM Q_ROM_VAR sig_name__[] = #sig_; \
        QS_CRIT_STAT_ \
        QS_CRIT_ENTRY_(); \
        QS_begin((uint8_t)QS_SIG_DIC); \
        QS_SIG_((QSignal)(sig_)); \
        QS_OBJ_(obj_); \
        QS_STR_ROM_(&sig_name__[0]); \
        QS_end(); \
        QS_CRIT_EXIT_(); \
        QS_onFlush(); \
    } \
} while (0)

Output signal dictionary record.

A signal dictionary record associates the numerical value of the signal and the binary address of the state machine that consumes that signal with the human-readable name of the signal.

Providing a signal dictionary QS record can vastly improve readability of the QS log, because instead of dealing with cryptic machine addresses the QSpy host utility can display human-readable names.

A signal dictionary entry is associated with both the signal value sig_ and the state machine obj_, because signals are required to be unique only within a given state machine and therefore the same numerical values can represent different signals in different state machines.

For the "global" signals that have the same meaning in all state machines (such as globally published signals), you can specify a signal dictionary entry with the obj_ parameter set to NULL.

The following example shows the definition of signal dictionary entries in the initial transition of the Table active object. Please note that signals HUNGRY_SIG and DONE_SIG are associated with the Table state machine only ("me" obj_ pointer). The EAT_SIG signal, on the other hand, is global (0 obj_ pointer): 

QState Table_initial(Table *me, QEvent const *e) {
    uint8_t n;
    (void)e;                               /* suppress the compiler warning */

    QS_SIG_DICTIONARY(HUNGRY_SIG, me);/* output signal dictionary QS record */
    QS_SIG_DICTIONARY(DONE_SIG, me);  /* output signal dictionary QS record */
    QS_SIG_DICTIONARY(EAT_SIG, 0);    /* output signal dictionary QS record */

    QS_FUN_DICTIONARY(Table_serving);

    QActive_subscribe((QActive *)me, HUNGRY_SIG);
    QActive_subscribe((QActive *)me, DONE_SIG);
    QActive_subscribe((QActive *)me, TERMINATE_SIG);

    for (n = 0; n < N; ++n) {
        me->fork[n] = FREE;
        me->isHungry[n] = 0;
    }
    return Q_TRAN(&Table_serving);
}
Note:
The QSpy log utility must capture the signal dictionary record in order to use the human-readable information. You need to connect to the target before the dictionary entries have been transmitted.

The following QSpy log example shows the signal dictionary records generated from the Table initial transition and subsequent records that show human-readable names of the signals: 

qspy -fqs.bin -S2 -Q2 -P4 -p4 -T4    
QSpy 1.1.03
Thu Nov 17 09:56:10 2005
-f qs.bin
-S 2
-Q 2
-P 4
-p 4
-T 4
. . .      . . .
           Obj Dic: 00419048->table
           EQ.INIT: Obj=00419050 Len= 5
0000000000 AO.ADD : Active=table Prio=51
           Fun Dic: 00401CEE->Table_serving
           Sig Dic: 00000004,Obj=00419048 ->HUNGRY_SIG
           Sig Dic: 00000005,Obj=00419048 ->DONE_SIG
           Sig Dic: 00000006,Obj=00000000 ->EAT_SIG
0000000000 AO.SUB : Active=table Sig=HUNGRY_SIG
0000000000 AO.SUB : Active=table Sig=DONE_SIG
0000000000 AO.SUB : Active=table Sig=00000007,Obj=00419048
           Q_INIT : Obj=table Source=00403CE0 Target=Table_serving
0000000000 ==>Init: Obj=table New=Table_serving
. . .      . . .

// the Philosophers become hungry...


0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
           Queue(nUsed=  1, nMax=  1)
0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
           Queue(nUsed=  2, nMax=  2)
           Q_ENTRY: Obj=philo[2] State=Philosopher_hungry
0000000007 AO.GET : Active= table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
           Queue(nUsed=  2)
0000000007 AO.FIFO: Obj=table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
           Queue(nUsed=  2, nMax=  3)
           Q_ENTRY: Obj=philo[4] State=Philosopher_hungry
           Q_ENTRY: Obj=philo[1] State=Philosopher_hungry
           Q_ENTRY: Obj=philo[3] State=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[2] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[4] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[3] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[1] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
           Q_ENTRY: Obj=philo[0] State=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[0] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
           
// user record output           
0000000007 User070: 2 hungry

// Table grants permissions to eat   
0000000007 NEW    : Evt(Sig=EAT_SIG, size=    6)
0000000007 MP.GET : Obj=00418E18 nFree=   5 nMin=   5
0000000007 AO.FIFO: Obj=philo[4] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=philo[3] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=philo[2] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=philo[1] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=philo[0] Evt(Sig=EAT_SIG, Pool=1, Ref= 0)
           Queue(nUsed=  0, nMax=  0)
0000000007 PUBLISH: Evt(Sig=EAT_SIG, Pool=1, Ref= 5) nSubsr=  5
0000000007 AO.GETL: Active= philo[4] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[2] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[3] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[1] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[0] Evt(Sig=EAT_SIG, Pool=1, Ref= 5)
. . .      . . .

The following QSpy log example shows the same sequence of records, but with dictionary records removed. The human-readable signal names are not available. 

qspy -fqs0.bin -S2 -Q2 -P4 -p4 -T4    
QSpy 1.1.03
Thu Nov 17 10:10:22 2005
-f qs0.bin
-S 2
-Q 2
-P 4
-p 4
-T 4
. . .      . . .
           Obj Dic: 00419048->table
           EQ.INIT: Obj=00419050 Len= 5
0000000000 AO.ADD : Active=table Prio=51

// the signal dictionary entries removed from the binary QS log
*** Dropped   4 records

0000000000 AO.SUB : Active=table Sig=00000004,Obj=00419048
0000000000 AO.SUB : Active=table Sig=00000005,Obj=00419048
0000000000 AO.SUB : Active=table Sig=00000007,Obj=00419048
           Q_INIT : Obj=table Source=00403CE0 Target=00403CE0
0000000000 ==>Init: Obj=table New=00401CEE
. . .      . . .

// the Philosophers become hungry...


0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
           Queue(nUsed=  1, nMax=  1)
0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
           Queue(nUsed=  2, nMax=  2)
           Q_ENTRY: Obj=philo[2] State=Philosopher_hungry
0000000007 AO.GET : Active= table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
           Queue(nUsed=  2)
0000000007 AO.FIFO: Obj=table Evt(Sig=00000004,Obj=00419048, Pool=1, Ref= 1)
           Queue(nUsed=  2, nMax=  3)
           Q_ENTRY: Obj=philo[4] State=Philosopher_hungry
           Q_ENTRY: Obj=philo[1] State=Philosopher_hungry
           Q_ENTRY: Obj=philo[3] State=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[2] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[4] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[3] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[1] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
           Q_ENTRY: Obj=philo[0] State=Philosopher_hungry
0000000007 ==>Tran: Obj=philo[0] Sig=TIMEOUT_SIG Source=Philosopher_thinking
           New=Philosopher_hungry
           
// user record output           
0000000007 User070: 2 hungry   

// Table grants permissions to eat   
0000000007 NEW    : Evt(Sig=00000006,Obj=00000000, size=    6)
0000000007 MP.GET : Obj=00418E18 nFree=   5 nMin=   5
0000000007 AO.FIFO: Obj=philo[4] Evt(Sig=00000006,Obj=00419000, Pool=1, Ref= 0) 
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=philo[3] Evt(Sig=00000006,Obj=00418FBC, Pool=1, Ref= 0)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=philo[2] Evt(Sig=00000006,Obj=00418F78, Pool=1, Ref= 0)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=philo[1] Evt(Sig=00000006,Obj=00418F34, Pool=1, Ref= 0)
           Queue(nUsed=  0, nMax=  0)
0000000007 AO.FIFO: Obj=philo[0] Evt(Sig=00000006,Obj=00418EF0, Pool=1, Ref= 0)
           Queue(nUsed=  0, nMax=  0)
0000000007 PUBLISH: Evt(Sig=00000006,Obj=00000000, Pool=1, Ref= 5) nSubsr=  5
0000000007 AO.GETL: Active= philo[4] Evt(Sig=00000006,Obj=00419000, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[2] Evt(Sig=00000006,Obj=00418F78, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[3] Evt(Sig=00000006,Obj=00418FBC, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[1] Evt(Sig=00000006,Obj=00418F34, Pool=1, Ref= 5)
0000000007 AO.GETL: Active= philo[0] Evt(Sig=00000006,Obj=00418EF0, Pool=1, Ref= 5)
. . .      . . .

Definition at line 1022 of file qs.h.

#define QS_TIME_SIZE   4

The size (in bytes) of the QS time stamp. Valid values: 1, 2, or 4; default 4.

This macro can be defined in the QS port file (qs_port.h) to configure the QSTimeCtr type. Here the macro is not defined so the default of 4 byte is chosen.

Definition at line 166 of file qs.h.

#define QS_USR_DICTIONARY (   rec_)
Value:
do { \
    if (((QS_glbFilter_[(uint8_t)QS_USR_DIC >> 3] \
      & (uint8_t)(1U << ((uint8_t)QS_USR_DIC & (uint8_t)7))) != (uint8_t)0)) \
    { \
        static char_t const Q_ROM Q_ROM_VAR usr_name__[] = #rec_; \
        QS_CRIT_STAT_ \
        QS_CRIT_ENTRY_(); \
        QS_begin((uint8_t)QS_USR_DIC); \
        QS_U8_((uint8_t)(rec_)); \
        QS_STR_ROM_(&usr_name__[0]); \
        QS_end(); \
        QS_CRIT_EXIT_(); \
        QS_onFlush(); \
    } \
} while (0)

Output user QS rectord dictionary record.

A user QS record dictionary record associates the numerical value of a user record with the human-readable identifier.

Definition at line 1101 of file qs.h.

Typedef Documentation

typedef uint32_t QSTimeCtr

The type of the QS time stamp.

This type determines the dynamic range of QS time stamps

Definition at line 180 of file qs.h.

Enumeration Type Documentation

enum QSpyRecords

Quantum Spy record types.

This enumeration specifies the record types used in the QP components. You can specify your own record types starting from QS_USER offset. Currently, the maximum of all records cannot exceed 256.

See also:
QS_filterIn()/QS_FILTER_ON and QS_filterOut()/QS_FILTER_OFF
Enumerator:
QS_QP_RESET 

reset the QP (start of a new QS session)

QS_QEP_STATE_ENTRY 

a state was entered

QS_QEP_STATE_EXIT 

a state was exited

QS_QEP_STATE_INIT 

an intial transition was taken in a state

QS_QEP_INIT_TRAN 

the top-most initial transition was taken

QS_QEP_INTERN_TRAN 

an internal transition was taken

QS_QEP_TRAN 

a regular transition was taken

QS_QEP_IGNORED 

an event was ignored (silently discarded)

QS_QEP_DISPATCH 

an event was dispatched (begin of RTC step)

QS_QEP_UNHANDLED 

an event was unhandled due to a guard

QS_QF_ACTIVE_ADD 

an AO has been added to QF (started)

QS_QF_ACTIVE_REMOVE 

an AO has been removed from QF (stopped)

QS_QF_ACTIVE_SUBSCRIBE 

an AO subscribed to an event

QS_QF_ACTIVE_UNSUBSCRIBE 

an AO unsubscribed to an event

QS_QF_ACTIVE_POST_FIFO 

an event was posted (FIFO) directly to AO

QS_QF_ACTIVE_POST_LIFO 

an event was posted (LIFO) directly to AO

QS_QF_ACTIVE_GET 

AO got an event and its queue is still not empty

QS_QF_ACTIVE_GET_LAST 

AO got an event and its queue is empty

QS_QF_EQUEUE_INIT 

an event queue was initialized

QS_QF_EQUEUE_POST_FIFO 

an event was posted (FIFO) to a raw queue

QS_QF_EQUEUE_POST_LIFO 

an event was posted (LIFO) to a raw queue

QS_QF_EQUEUE_GET 

get an event and queue still not empty

QS_QF_EQUEUE_GET_LAST 

get the last event from the queue

QS_QF_MPOOL_INIT 

a memory pool was initialized

QS_QF_MPOOL_GET 

a memory block was removed from a memory pool

QS_QF_MPOOL_PUT 

a memory block was returned to a memory pool

QS_QF_PUBLISH 

an event was published

QS_QF_NEW 

new event creation

QS_QF_GC_ATTEMPT 

garbage collection attempt

QS_QF_GC 

garbage collection

QS_QF_TICK 

QF_tick() was called

QS_QF_TIMEEVT_ARM 

a time event was armed

QS_QF_TIMEEVT_AUTO_DISARM 

a time event expired and was disarmed

QS_QF_TIMEEVT_DISARM_ATTEMPT 

attempt to disarm a disarmed QTimeEvt

QS_QF_TIMEEVT_DISARM 

true disarming of an armed time event

QS_QF_TIMEEVT_REARM 

rearming of a time event

QS_QF_TIMEEVT_POST 

a time event posted itself directly to an AO

QS_QF_TIMEEVT_CTR 

a time event counter was requested

QS_QF_CRIT_ENTRY 

critical section was entered

QS_QF_CRIT_EXIT 

critical section was exited

QS_QF_ISR_ENTRY 

an ISR was entered

QS_QF_ISR_EXIT 

an ISR was exited

QS_QF_INT_DISABLE 

interrupts were disabled

QS_QF_INT_ENABLE 

interrupts were enabled

QS_QK_MUTEX_LOCK 

the QK mutex was locked

QS_QK_MUTEX_UNLOCK 

the QK mutex was unlocked

QS_QK_SCHEDULE 

the QK scheduled a new task to execute

QS_SIG_DIC 

signal dictionary entry

QS_OBJ_DIC 

object dictionary entry

QS_FUN_DIC 

function dictionary entry

QS_USR_DIC 

user QS record dictionary entry

QS_ASSERT 

assertion fired in the code

QS_USER 

the first record available for user QS records

Definition at line 59 of file qs.h.

enum QSType

Enumerates data formats recognized by QS.

QS uses this enumeration is used only internally for the formatted user data elements.

Enumerator:
QS_I8_T 

signed 8-bit integer format

QS_U8_T 

unsigned 8-bit integer format

QS_I16_T 

signed 16-bit integer format

QS_U16_T 

unsigned 16-bit integer format

QS_I32_T 

signed 32-bit integer format

QS_U32_T 

unsigned 32-bit integer format

QS_F32_T 

32-bit floating point format

QS_F64_T 

64-bit floating point format

QS_STR_T 

zero-terminated ASCII string format

QS_MEM_T 

up to 255-bytes memory block format

QS_SIG_T 

event signal format

QS_OBJ_T 

object pointer format

QS_FUN_T 

function pointer format

QS_I64_T 

signed 64-bit integer format

QS_U64_T 

unsigned 64-bit integer format

QS_U32_HEX_T 

unsigned 32-bit integer in hex format

Definition at line 840 of file qs.h.

Function Documentation

void QS_begin ( uint8_t  rec)

Mark the begin of a QS record rec.

This function must be called at the beginning of each QS record. This function should be called indirectly through the macro QS_BEGIN, or QS_BEGIN_NOCRIT, depending if it's called in a normal code or from a critical section.

Definition at line 101 of file qs.c.

References QS_chksum_, QS_INSERT_ESC_BYTE, and QS_seq_.

void QS_end ( void  )

Mark the end of a QS record rec.

This function must be called at the end of each QS record. This function should be called indirectly through the macro QS_END, or QS_END_NOCRIT, depending if it's called in a normal code or from a critical section.

Definition at line 108 of file qs.c.

References QS_end_, QS_FRAME, QS_head_, QS_INSERT_BYTE, QS_INSERT_CHKSUM_BYTE, QS_tail_, and QS_used_.

void QS_f32 ( uint8_t  format,
float32_t  f 
)

Output 32-bit floating point data element with format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 44 of file qs_f32.c.

References QS_INSERT_ESC_BYTE.

void QS_f64 ( uint8_t  format,
float64_t  d 
)

Output 64-bit floating point data element with format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 44 of file qs_f64.c.

References QS_INSERT_ESC_BYTE.

void QS_filterOff ( uint8_t  rec)

Turn the global Filter off for a given record type rec.

This function sets up the QS filter to disable the record type rec. The argument QS_ALL_RECORDS specifies to suppress all records. This function should be called indirectly through the macro QS_FILTER_OFF.

Note:
Filtering records based on the record-type is only the first layer of filtering. The second layer is based on the object-type. Both filter layers must be enabled for the QS record to be inserted into the QS buffer.
See also:

Definition at line 88 of file qs.c.

References QS_ALL_RECORDS, and QS_glbFilter_.

void QS_filterOn ( uint8_t  rec)

Turn the global Filter on for a given record type rec.

This function sets up the QS filter to enable the record type rec. The argument QS_ALL_RECORDS specifies to filter-in all records. This function should be called indirectly through the macro QS_FILTER_ON.

Note:
Filtering based on the record-type is only the first layer of filtering. The second layer is based on the object-type. Both filter layers must be enabled for the QS record to be inserted into the QS buffer.
See also:
QS_filterOff(), QS_FILTER_SM_OBJ, QS_FILTER_AO_OBJ, QS_FILTER_MP_OBJ, QS_FILTER_EQ_OBJ, and QS_FILTER_TE_OBJ.

Definition at line 76 of file qs.c.

References QS_ALL_RECORDS, and QS_glbFilter_.

uint8_t const* QS_getBlock ( uint16_t *  pNbytes)

Block-oriented interface to the QS data buffer.

This function delivers a contiguous block of data from the QS data buffer. The function returns the pointer to the beginning of the block, and writes the number of bytes in the block to the location pointed to by pNbytes. The argument pNbytes is also used as input to provide the maximum size of the data block that the caller can accept.

If no bytes are available in the QS buffer when the function is called, the function returns a NULL pointer and sets the value pointed to by pNbytes to zero.

Note:
Only the NULL return from QS_getBlock() indicates that the QS buffer is empty at the time of the call. The non-NULL return often means that the block is at the end of the buffer and you need to call QS_getBlock() again to obtain the rest of the data that "wrapped around" to the beginning of the QS data buffer.
QS_getBlock() is NOT protected with a critical section.

Definition at line 45 of file qs_blk.c.

References QS_end_, QS_PTR_AT_, QS_tail_, and QS_used_.

uint16_t QS_getByte ( void  )

Byte-oriented interface to the QS data buffer.

This function delivers one byte at a time from the QS data buffer. The function returns the byte in the least-significant 8-bits of the 16-bit return value if the byte is available. If no more data is available at the time, the function returns QS_EOD (End-Of-Data).

Note:
QS_getByte() is NOT protected with a critical section.

Definition at line 44 of file qs_byte.c.

References QS_end_, QS_EOD, QS_PTR_AT_, QS_tail_, and QS_used_.

char_t const Q_ROM* Q_ROM_VAR QS_getVersion ( void  )

Get the current version of QS.

Returns:
version of the QS as a constant 6-character string of the form x.y.zz, where x is a 1-digit major version number, y is a 1-digit minor version number, and zz is a 2-digit release number.

Definition at line 58 of file qs.c.

References QP_VERSION.

void QS_initBuf ( uint8_t  sto[],
uint32_t  stoSize 
)

Initialize the QS data buffer.

This function should be called from QS_onStartup() to provide QS with the data buffer. The first argument sto[] is the address of the memory block, and the second argument stoSize is the size of this block in bytes. Currently the size of the QS buffer cannot exceed 64KB.

QS can work with quite small data buffers, but you will start losing data if the buffer is too small for the bursts of logging activity. The right size of the buffer depends on the data production rate and the data output rate. QS offers flexible filtering to reduce the data production rate.

Note:
If the data output rate cannot keep up with the production rate, QS will start overwriting the older data with newer data. This is consistent with the "last-is-best" QS policy. The record sequence counters and checksums on each record allow to easily detect data loss.

Definition at line 71 of file qs.c.

References QS_end_, and QS_ring_.

void QS_mem ( uint8_t const *  blk,
uint8_t  size 
)

Output memory block of up to 255-bytes with format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 44 of file qs_mem.c.

References QS_chksum_, QS_INSERT_BYTE, QS_INSERT_ESC_BYTE, QS_MEM_T, and QS_PTR_INC_.

void QS_onCleanup ( void  )

Callback to cleanup the QS facility.

This is a platform-dependent "callback" function invoked through the macro QS_EXIT. You need to implement this function in your application. The main purpose of this function is to close the QS output channel, if necessary.

void QS_onFlush ( void  )

Callback to flush the QS trace data to the host.

This is a platform-dependent "callback" function to flush the QS trace buffer to the host. The function typically busy-waits until all the data in the buffer is sent to the host. This is acceptable only in the initial transient.

QSTimeCtr QS_onGetTime ( void  )

Callback to obtain a timestamp for a QS record.

This is a platform-dependent "callback" function invoked from the macro QS_TIME_ to add the time stamp to a QS record.

Note:
Some of the pre-defined QS records from QP do not output the time stamp. However, ALL user records do output the time stamp.
QS_onGetTime() is called in a critical section and should not exit the critical section.

The following example shows using a system call to implement QS time stamping: 

#ifdef Q_SPY

QSTimeCtr QS_onGetTime(void) {
    return (QSTimeCtr)clock();
}

. . .

#endif /* Q_SPY */
uint8_t QS_onStartup ( void const *  arg)

Callback to startup the QS facility.

This is a platform-dependent "callback" function invoked through the macro QS_INIT. You need to implement this function in your application. At a minimum, the function must configure the QS buffer by calling QS_initBuf(). Typically, you will also want to open/configure the QS output channel, such as a serial port, or a data file. The void* argument arg can be used to pass parameter(s) needed to configure the output channel.

The function returns TRUE (1) if the QS initialization was successful, or FALSE (0) if it failed.

The following example illustrates an implementation of QS_onStartup(): 

#ifdef Q_SPY

uint8_t QS_onStartup(void const *arg) {
    static uint8_t qsBuf[4*1024];                 /* buffer for Quantum Spy */

    QS_initBuf(qsBuf, sizeof(qsBuf));         /* configure the Q-Spy buffer */

    /* configure UART 0/1 for QSPY output ... */
    if (*(char const *)arg == '0') {                          /* use UART 0 */
        /* configure UART 0 for QSPY output ... */
        . . .
        return (uint8_t)1;                   /* UART 0 successfully opened */
    }
    else {                                                    /* use UART 1 */
        /* configure UART 1 for QSPY output ... */
        . . .
        return (uint8_t)1;                   /* UART 1 successfully opened */
    }
}

. . .

#endif /* Q_SPY */
void QS_str ( char_t const *  s)

Output zero-terminated ASCII string element with format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 44 of file qs_str.c.

References QS_chksum_, QS_INSERT_BYTE, QS_PTR_INC_, and QS_STR_T.

void QS_str_ ( char_t const *  s)

Output zero-terminated ASCII string element without format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 74 of file qs_.c.

References QS_chksum_, QS_INSERT_BYTE, and QS_PTR_INC_.

void QS_str_ROM ( char_t const Q_ROM *Q_ROM_VAR  s)

Output zero-terminated ASCII string element allocated in ROM with format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 56 of file qs_str.c.

References QS_chksum_, QS_INSERT_BYTE, QS_PTR_INC_, and QS_STR_T.

void QS_str_ROM_ ( char_t const Q_ROM *Q_ROM_VAR  s)

Output zero-terminated ASCII string element allocated in ROM without format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 86 of file qs_.c.

References QS_chksum_, QS_INSERT_BYTE, and QS_PTR_INC_.

void QS_u16 ( uint8_t  format,
uint16_t  d 
)

output uint16_t data element with format information

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 122 of file qs.c.

References QS_INSERT_ESC_BYTE.

void QS_u16_ ( uint16_t  d)

Output uint16_t data element without format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 58 of file qs_.c.

References QS_INSERT_ESC_BYTE.

void QS_u32 ( uint8_t  format,
uint32_t  d 
)

Output uint32_t data element with format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 129 of file qs.c.

References QS_INSERT_ESC_BYTE.

void QS_u32_ ( uint32_t  d)

Output uint32_t data element without format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 64 of file qs_.c.

References QS_INSERT_ESC_BYTE.

void QS_u8 ( uint8_t  format,
uint8_t  d 
)

Output uint8_t data element with format information.

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 117 of file qs.c.

References QS_INSERT_ESC_BYTE.

void QS_u8_ ( uint8_t  d)

output uint8_t data element without format information

Note:
This function is only to be used through macros, never in the client code directly.

Definition at line 54 of file qs_.c.

References QS_INSERT_ESC_BYTE.

Variable Documentation

uint8_t QF_critNest_

critical section nesting level

Note:
Not to be used by Clients directly, only in ports of QF
void const* QS_aoObj_

active object for QF local filter

Definition at line 45 of file qs_.c.

Referenced by QActive_get_(), QActive_postFIFO(), QActive_postLIFO(), QActive_subscribe(), QActive_unsubscribe(), QActive_unsubscribeAll(), QF_add_(), QF_remove_(), QK_sched_(), and QK_schedExt_().

void const* QS_apObj_

generic object Application local filter

Definition at line 49 of file qs_.c.

void const* QS_eqObj_

raw queue for QF local filter

Definition at line 47 of file qs_.c.

Referenced by QEQueue_get(), QEQueue_init(), QEQueue_postFIFO(), and QEQueue_postLIFO().

uint8_t QS_glbFilter_[32]

global on/off QS filter

Definition at line 45 of file qs.c.

Referenced by QS_filterOff(), and QS_filterOn().

void const* QS_mpObj_

event pool for QF local filter

Definition at line 46 of file qs_.c.

Referenced by QMPool_get(), QMPool_init(), and QMPool_put().

void const* QS_smObj_

state machine for QEP local filter

Definition at line 44 of file qs_.c.

Referenced by QFsm_dispatch(), QFsm_init(), QHsm_dispatch(), and QHsm_init().

void const* QS_teObj_

time event for QF local filter

Definition at line 48 of file qs_.c.

Referenced by QF_tick(), QTimeEvt_arm_(), QTimeEvt_ctr(), QTimeEvt_disarm(), and QTimeEvt_rearm().

QSTimeCtr QS_tickCtr_

tick counter for the QS_QF_TICK record

Definition at line 51 of file qs_.c.

Referenced by QF_tick().

Generated on Fri Feb 8 2013 10:56:19 for QP/C by   doxygen 1.7.6.1