QP/C  6.0.2
qs.h File Reference

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

Go to the source code of this file.

Data Structures

struct  QSPriv
 Private QS data to keep track of the filters and the trace buffer. More...
 
struct  QSrxPriv
 Private QS-RX data to keep track of the lock-free buffer. More...
 

Macros

#define QS_TIME_SIZE   4
 The size (in bytes) of the QS time stamp. More...
 
#define QS_TIME_()   (QS_u32_(QS_onGetTime()))
 Internal macro to output time stamp to a QS record.
 
#define QS_PTR_AT_(base_, i_)   (base_[i_])
 access element at index i_ from the base pointer base_ More...
 
#define QS_EOD   ((uint16_t)0xFFFF)
 Constant for End-Of-Data condition returned from QS_getByte()
 
#define QS_INIT(arg_)   (QS_onStartup(arg_))
 Initialize the QS facility. More...
 
#define QS_EXIT()   (QS_onCleanup())
 Cleanup the QS facility. More...
 
#define QS_FILTER_ON(rec_)   (QS_filterOn((uint_fast8_t)(rec_)))
 Global Filter ON for a given record type rec. More...
 
#define QS_FILTER_OFF(rec_)   (QS_filterOff((uint_fast8_t)(rec_)))
 Global filter OFF for a given record type rec. More...
 
#define QS_FILTER_SM_OBJ(obj_)   (QS_priv_.locFilter[SM_OBJ] = (obj_))
 Local Filter for a given state machine object obj_. More...
 
#define QS_FILTER_AO_OBJ(obj_)   (QS_priv_.locFilter[AO_OBJ] = (obj_))
 Local Filter for a given active object obj_. More...
 
#define QS_FILTER_MP_OBJ(obj_)   (QS_priv_.locFilter[MP_OBJ] = (obj_))
 Local Filter for a given memory pool object obj_. More...
 
#define QS_FILTER_EQ_OBJ(obj_)   (QS_priv_.locFilter[EQ_OBJ] = (obj_))
 Local Filter for a given event queue object obj_. More...
 
#define QS_FILTER_TE_OBJ(obj_)   (QS_priv_.locFilter[TE_OBJ] = (obj_))
 Local Filter for a given time event object obj_. More...
 
#define QS_FILTER_AP_OBJ(obj_)   (QS_priv_.locFilter[AP_OBJ] = (obj_))
 Local Filter for a generic application object obj_. More...
 
#define QS_BEGIN_NOCRIT(rec_, obj_)
 Begin a QS user record without entering critical section. More...
 
#define QS_END_NOCRIT()
 End a QS user record without exiting critical section. More...
 
#define QS_REC_DONE()   ((void)0)
 macro to hook up user code when a QS record is produced
 
#define QS_CRIT_STAT_
 This is an internal macro for defining the critical section status type. More...
 
#define QS_CRIT_ENTRY_()   QF_CRIT_ENTRY(dummy)
 This is an internal macro for entering a critical section. More...
 
#define QS_CRIT_EXIT_()   QF_CRIT_EXIT(dummy); QS_REC_DONE()
 This is an internal macro for exiting a critical section. More...
 
#define QS_BEGIN(rec_, obj_)
 Begin a user QS record with entering critical section. More...
 
#define QS_END()
 End a QS record with exiting critical section. More...
 
#define QS_BEGIN_(rec_, objFilter_, obj_)
 Internal QS macro to begin a QS record with entering critical section. More...
 
#define QS_END_()
 Internal QS macro to end a QS record with exiting critical section. More...
 
#define QS_BEGIN_NOCRIT_(rec_, objFilter_, obj_)
 Internal macro to begin a QS record without entering critical section. More...
 
#define QS_END_NOCRIT_()
 Internal QS macro to end a QS record without exiting critical section. More...
 
#define QS_U8_(data_)   (QS_u8_((uint8_t)(data_)))
 Internal QS macro to output an unformatted uint8_t data element.
 
#define QS_2U8_(data1_, data2_)   (QS_u8u8_((data1_), (data2_)))
 Internal QS macro to output 2 unformatted uint8_t data elements.
 
#define QS_U16_(data_)   (QS_u16_((uint16_t)(data_)))
 Internal QS macro to output an unformatted uint16_t data element.
 
#define QS_U32_(data_)   (QS_u32_((uint32_t)(data_)))
 Internal QS macro to output an unformatted uint32_t data element.
 
#define QS_OBJ_(obj_)   (QS_u32_((uint32_t)(obj_))
 Internal macro to output an unformatted object pointer data element. More...
 
#define QS_FUN_(fun_)   (QS_u32_((uint32_t)(fun_)))
 Internal macro to output an unformatted function pointer. More...
 
#define QS_STR_(msg_)   (QS_str_((msg_)))
 Internal QS macro to output a zero-terminated ASCII string 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_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_SIG_DICTIONARY(sig_, obj_)
 Output signal dictionary record. More...
 
#define QS_OBJ_DICTIONARY(obj_)
 Output object dictionary record. More...
 
#define QS_FUN_DICTIONARY(fun_)
 Output function dictionary record. More...
 
#define QS_USR_DICTIONARY(rec_)
 Output user QS-record dictionary record. More...
 
#define QS_ASSERTION(module_, loc_, delay_)
 Output the assertion failure trace record. More...
 
#define QS_FLUSH()   (QS_onFlush())
 Flush the QS trace data to the host. More...
 
#define QF_QS_CRIT_ENTRY()
 Output the critical section entry. More...
 
#define QF_QS_CRIT_EXIT()
 Output the critical section exit. More...
 
#define QF_QS_ISR_ENTRY(isrnest_, prio_)
 Output the interrupt entry record. More...
 
#define QF_QS_ISR_EXIT(isrnest_, prio_)
 Output the interrupt exit record. More...
 
#define QF_QS_ACTION(act_)   (act_)
 Execute an action that is only necessary for QS output.
 
#define QS_getVersion()   (QP_versionStr)
 get the current QS version number string of the form "X.Y.Z"
 
#define QS_RX_PUT(b_)
 put one byte into the QS RX lock-free buffer More...
 
#define QS_TEST_PROBE_DEF(fun_)   uint32_t const qs_tp_ = QS_getTestProbe_((void (*)(void))(fun_));
 QS macro to define the Test-Probe for a given fun_.
 
#define QS_TEST_PROBE(code_)   if (qs_tp_ != (uint32_t)0) { code_ }
 QS macro to apply a Test-Probe.
 
#define QS_TEST_PROBE_ID(id_, code_)   if (qs_tp_ == (uint32_t)(id_)) { code_ }
 QS macro to apply a Test-Probe.
 
#define QS_TEST_PAUSE()
 QS macro to pause test execution and enter the test event loop. More...
 

Typedefs

typedef uint32_t QSTimeCtr
 The type of the QS time stamp. More...
 
typedef uint_fast16_t QSCtr
 QS ring buffer counter and offset type.
 

Enumerations

enum  QSpyRecords {
  QS_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_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_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_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_QF_ACTIVE_POST_ATTEMPT, QS_QF_EQUEUE_POST_ATTEMPT, QS_QF_MPOOL_GET_ATTEMPT,
  QS_MUTEX_LOCK, QS_MUTEX_UNLOCK, QS_SCHED_LOCK, QS_SCHED_UNLOCK,
  QS_SCHED_NEXT, QS_SCHED_IDLE, QS_SCHED_RESUME, QS_QEP_TRAN_HIST,
  QS_QEP_TRAN_EP, QS_QEP_TRAN_XP, 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_MSC_RESERVED1,
  QS_PEEK_DATA, QS_ASSERT_FAIL, QS_USER
}
 Quantum Spy record types. More...
 
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
}
 QS record groups for QS_FILTER_ON() and QS_FILTER_OFF() More...
 
enum  QSpyUserRecords { QS_USER0 = QS_USER, QS_USER1 = QS_USER0 + 10, QS_USER2 = QS_USER1 + 10, QS_USER3 = QS_USER2 + 10 }
 QS user record group offsets. More...
 
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
}
 Enumerates data formats recognized by QS. More...
 
enum  QSpyObjKind {
  SM_OBJ, AO_OBJ, MP_OBJ, EQ_OBJ,
  TE_OBJ, AP_OBJ, MAX_OBJ
}
 Kinds of objects used in QS. More...
 
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_RESERVED1,
  QS_RX_EVENT
}
 Quantum Spy Receive (RX) record types: More...
 

Functions

void QS_initBuf (uint8_t sto[], uint_fast16_t stoSize)
 Initialize the QS data buffer. More...
 
void QS_filterOn (uint_fast8_t rec)
 Turn the global Filter on for a given record type rec. More...
 
void QS_filterOff (uint_fast8_t rec)
 Turn the global Filter off for a given record type rec. More...
 
void QS_beginRec (uint_fast8_t rec)
 Mark the begin of a QS record rec. More...
 
void QS_endRec (void)
 Mark the end of a QS record rec. More...
 
void QS_u8_ (uint8_t d)
 output uint8_t data element without format information More...
 
void QS_u8u8_ (uint8_t d1, uint8_t d2)
 output two uint8_t data elements without format information More...
 
void QS_u16_ (uint16_t d)
 Output uint16_t data element without format information. More...
 
void QS_u32_ (uint32_t d)
 Output uint32_t data element without format information. More...
 
void QS_str_ (char_t const *s)
 Output zero-terminated ASCII string element without format information. More...
 
void QS_u8 (uint8_t format, uint8_t d)
 Output uint8_t data element with format information. More...
 
void QS_u16 (uint8_t format, uint16_t d)
 output uint16_t data element with format information More...
 
void QS_u32 (uint8_t format, uint32_t d)
 Output uint32_t data element with format information. More...
 
void QS_f32 (uint8_t format, float32_t f)
 Output 32-bit floating point data element with format information. More...
 
void QS_f64 (uint8_t format, float64_t d)
 Output 64-bit floating point data element with format information. More...
 
void QS_str (char_t const *s)
 Output zero-terminated ASCII string element with format information. More...
 
void QS_mem (uint8_t const *blk, uint8_t size)
 Output memory block of up to 255-bytes with format information. More...
 
void QS_sig_dict (enum_t const sig, void const *const obj, char_t const *name)
 Output signal dictionary record. More...
 
void QS_obj_dict (void const *const obj, char_t const *name)
 Output object dictionary record. More...
 
void QS_fun_dict (void(*const fun)(void), char_t const *name)
 Output function dictionary record. More...
 
void QS_usr_dict (enum_t const rec, char_t const *const name)
 Output user dictionary record. More...
 
uint16_t QS_getByte (void)
 Byte-oriented interface to the QS data buffer. More...
 
uint8_t const * QS_getBlock (uint16_t *pNbytes)
 Block-oriented interface to the QS data buffer. More...
 
uint8_t QS_onStartup (void const *arg)
 Callback to startup the QS facility. More...
 
void QS_onCleanup (void)
 Callback to cleanup the QS facility. More...
 
void QS_onFlush (void)
 Callback to flush the QS trace data to the host. More...
 
QSTimeCtr QS_onGetTime (void)
 Callback to obtain a timestamp for a QS record. More...
 
void QS_rxInitBuf (uint8_t sto[], uint16_t stoSize)
 Initialize the QS RX data buffer. More...
 
void QS_rxParse (void)
 Parse all bytes present in the QS RX data buffer.
 
uint16_t QS_rxGetNfree (void)
 Obtain the number of free bytes in the QS RX data buffer. More...
 
void QS_onReset (void)
 callback function to reset the Target (to be implemented in the BSP)
 
void QS_onCommand (uint8_t cmdId, uint32_t param1, uint32_t param2, uint32_t param3)
 callback function to execute user commands (to be implemented in BSP)
 
void QS_onTestSetup (void)
 callback to setup a unit test inside the Target
 
void QS_onTestTeardown (void)
 callback to teardown after a unit test inside the Target
 
void QS_onTestLoop (void)
 callback to run the test loop
 
void QS_onTestEvt (QEvt *e)
 callback to "massage" the test event, if neccessary
 
uint32_t QS_getTestProbe_ (void(*const api)(void))
 QS internal function to get the Test-Probe for a given API. More...
 

Variables

QSPriv QS_priv_
 
QSrxPriv QS_rxPriv_
 

Detailed Description

QS/C platform-independent public interface.

Definition in file qs.h.


Data Structure Documentation

◆ QSPriv

struct QSPriv

Private QS data to keep track of the filters and the trace buffer.

Definition at line 1067 of file qs.h.

Data Fields
uint8_t glbFilter[16] global on/off QS filter
void const * locFilter[MAX_OBJ] local QS filters
uint8_t * buf pointer to the start of the ring buffer
QSCtr end offset of the end of the ring buffer
QSCtr head offset to where next byte will be inserted
QSCtr tail offset of where next byte will be extracted
QSCtr used number of bytes currently in the ring buffer
uint8_t seq the record sequence number
uint8_t chksum the checksum of the current record
uint8_t critNest critical section nesting level

◆ QSrxPriv

struct QSrxPriv

Private QS-RX data to keep track of the lock-free buffer.

Definition at line 1119 of file qs.h.

Data Fields
void * currObj[MAX_OBJ] current objects
uint8_t * buf pointer to the start of the ring buffer
QSCtr end offset of the end of the ring buffer
QSCtr head offset to where next byte will be inserted
QSCtr tail offset of where next byte will be extracted
bool inTestLoop QUTest event loop is running.

Macro Definition Documentation

◆ QS_TIME_SIZE

#define QS_TIME_SIZE   4

The size (in bytes) of the QS time stamp.

Valid values: 1, 2, or 4; default 4.

Description
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 189 of file qs.h.

◆ QS_PTR_AT_

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

access element at index i_ from the base pointer base_

Description
Note
This macro encapsulates MISRA-C 2004 Rule 17.4(req) (pointer arithmetic other than array indexing).

Definition at line 216 of file qs.h.

◆ QS_INIT

#define QS_INIT (   arg_)    (QS_onStartup(arg_))

Initialize the QS facility.

Description
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 380 of file qs.h.

◆ QS_EXIT

#define QS_EXIT ( )    (QS_onCleanup())

Cleanup the QS facility.

Description
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 389 of file qs.h.

◆ QS_FILTER_ON

#define QS_FILTER_ON (   rec_)    (QS_filterOn((uint_fast8_t)(rec_)))

Global Filter ON for a given record type rec.

Description
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:

int main() {
. . .
if (!QS_INIT("1")) { /* Initialize QSpy to use UART 1 */
return -1; /* Unable to initialize QSpy */
}
QS_FILTER_ON(QS_ALL_RECORDS); /* start with enabling all QS records */
/* selectively disable the records... */
// QS_FILTER_OFF(QS_QEP_STATE_ENTRY);
// QS_FILTER_OFF(QS_QEP_STATE_EXIT);
// QS_FILTER_OFF(QS_QEP_STATE_INIT);
// QS_FILTER_OFF(QS_QEP_TRAN_HIST);
// QS_FILTER_OFF(QS_QEP_INTERN_TRAN);
// QS_FILTER_OFF(QS_QEP_TRAN);
// QS_FILTER_OFF(QS_QEP_IGNORED);
// QS_FILTER_OFF(QS_QF_ACTIVE_ADD);
// QS_FILTER_OFF(QS_QF_ACTIVE_REMOVE);
// QS_FILTER_OFF(QS_QF_ACTIVE_SUBSCRIBE);
// QS_FILTER_OFF(QS_QF_ACTIVE_UNSUBSCRIBE);
// QS_FILTER_OFF(QS_QF_ACTIVE_POST_FIFO);
// QS_FILTER_OFF(QS_QF_ACTIVE_POST_LIFO);
// QS_FILTER_OFF(QS_QF_ACTIVE_GET);
// QS_FILTER_OFF(QS_QF_ACTIVE_GET_LAST);
// QS_FILTER_OFF(QS_QF_EQUEUE_INIT);
// QS_FILTER_OFF(QS_QF_EQUEUE_POST_FIFO);
// QS_FILTER_OFF(QS_QF_EQUEUE_POST_LIFO);
// QS_FILTER_OFF(QS_QF_EQUEUE_GET);
// QS_FILTER_OFF(QS_QF_EQUEUE_GET_LAST);
// QS_FILTER_OFF(QS_QF_MPOOL_INIT);
// QS_FILTER_OFF(QS_QF_MPOOL_GET);
// QS_FILTER_OFF(QS_QF_MPOOL_PUT);
// QS_FILTER_OFF(QS_QF_PUBLISH);
// QS_FILTER_OFF(QS_QF_NEW);
// QS_FILTER_OFF(QS_QF_GC_ATTEMPT);
// QS_FILTER_OFF(QS_QF_GC);
// QS_FILTER_OFF(QS_QF_TICK);
// QS_FILTER_OFF(QS_QF_TIMEEVT_ARM);
// QS_FILTER_OFF(QS_QF_TIMEEVT_AUTO_DISARM);
// QS_FILTER_OFF(QS_QF_TIMEEVT_DISARM_ATTEMPT);
// QS_FILTER_OFF(QS_QF_TIMEEVT_DISARM);
// QS_FILTER_OFF(QS_QF_TIMEEVT_REARM);
// QS_FILTER_OFF(QS_QF_TIMEEVT_POST);
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].m_timeEvt); /* trace only this time event */
. . .
}

Definition at line 400 of file qs.h.

◆ QS_FILTER_OFF

#define QS_FILTER_OFF (   rec_)    (QS_filterOff((uint_fast8_t)(rec_)))

Global filter OFF for a given record type rec.

Description
This macro provides an indirection layer to call QS_filterOff() if Q_SPY is defined, or do nothing if Q_SPY is not defined.
Note
The QS records marked as "non-maskable" in the
See also
Example of using QS filters in QS_FILTER_ON documentation

Definition at line 413 of file qs.h.

◆ QS_FILTER_SM_OBJ

#define QS_FILTER_SM_OBJ (   obj_)    (QS_priv_.locFilter[SM_OBJ] = (obj_))

Local Filter for a given state machine object obj_.

Description
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_INTERN_TRAN, QS_QEP_TRAN, QS_QEP_IGNORED, QS_QEP_TRAN_HIST, Q_RET_TRAN_EP, Q_RET_TRAN_XP
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 441 of file qs.h.

◆ QS_FILTER_AO_OBJ

#define QS_FILTER_AO_OBJ (   obj_)    (QS_priv_.locFilter[AO_OBJ] = (obj_))

Local Filter for a given active object obj_.

Description
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, 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 462 of file qs.h.

◆ QS_FILTER_MP_OBJ

#define QS_FILTER_MP_OBJ (   obj_)    (QS_priv_.locFilter[MP_OBJ] = (obj_))

Local Filter for a given memory pool object obj_.

Description
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 482 of file qs.h.

◆ QS_FILTER_EQ_OBJ

#define QS_FILTER_EQ_OBJ (   obj_)    (QS_priv_.locFilter[EQ_OBJ] = (obj_))

Local Filter for a given event queue object obj_.

Description
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, 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 502 of file qs.h.

◆ QS_FILTER_TE_OBJ

#define QS_FILTER_TE_OBJ (   obj_)    (QS_priv_.locFilter[TE_OBJ] = (obj_))

Local Filter for a given time event object obj_.

Description
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 523 of file qs.h.

◆ QS_FILTER_AP_OBJ

#define QS_FILTER_AP_OBJ (   obj_)    (QS_priv_.locFilter[AP_OBJ] = (obj_))

Local Filter for a generic application object obj_.

Description
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 540 of file qs.h.

◆ QS_BEGIN_NOCRIT

#define QS_BEGIN_NOCRIT (   rec_,
  obj_ 
)
Value:
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_(); {
generic Application-specific object
Definition: qs.h:1062
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:28
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
void const * locFilter[MAX_OBJ]
local QS filters
Definition: qs.h:1069
uint8_t glbFilter[16]
global on/off QS filter
Definition: qs.h:1068

Begin a QS user record without entering critical section.

Definition at line 546 of file qs.h.

◆ QS_END_NOCRIT

#define QS_END_NOCRIT ( )
Value:
} \
QS_END_NOCRIT_()

End a QS user record without exiting critical section.

Definition at line 557 of file qs.h.

◆ QS_CRIT_STAT_

#define QS_CRIT_STAT_

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

Description
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 592 of file qs.h.

◆ QS_CRIT_ENTRY_

#define QS_CRIT_ENTRY_ ( )    QF_CRIT_ENTRY(dummy)

This is an internal macro for entering a critical section.

Description
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 604 of file qs.h.

◆ QS_CRIT_EXIT_

#define QS_CRIT_EXIT_ ( )    QF_CRIT_EXIT(dummy); QS_REC_DONE()

This is an internal macro for exiting a critical section.

Description
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 616 of file qs.h.

◆ QS_BEGIN

#define QS_BEGIN (   rec_,
  obj_ 
)
Value:
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_beginRec((uint_fast8_t)(rec_)); \
QS_TIME_(); {
generic Application-specific object
Definition: qs.h:1062
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:28
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
void const * locFilter[MAX_OBJ]
local QS filters
Definition: qs.h:1069
uint8_t glbFilter[16]
global on/off QS filter
Definition: qs.h:1068
#define QS_CRIT_ENTRY_()
This is an internal macro for entering a critical section.
Definition: qs.h:604

Begin a user QS record with entering critical section.

Usage
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 635 of file qs.h.

◆ QS_END

#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 651 of file qs.h.

◆ QS_BEGIN_

#define QS_BEGIN_ (   rec_,
  objFilter_,
  obj_ 
)
Value:
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_));
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:28
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
uint8_t glbFilter[16]
global on/off QS filter
Definition: qs.h:1068

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 661 of file qs.h.

◆ QS_END_

#define QS_END_ ( )
Value:
QS_CRIT_EXIT_(); \
}
void QS_endRec(void)
Mark the end of a QS record rec.
Definition: qs.c:328

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 676 of file qs.h.

◆ QS_BEGIN_NOCRIT_

#define QS_BEGIN_NOCRIT_ (   rec_,
  objFilter_,
  obj_ 
)
Value:
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_));
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:28
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
uint8_t glbFilter[16]
global on/off QS filter
Definition: qs.h:1068

Internal 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 686 of file qs.h.

◆ QS_END_NOCRIT_

#define QS_END_NOCRIT_ ( )
Value:
}
void QS_endRec(void)
Mark the end of a QS record rec.
Definition: qs.c:328

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 700 of file qs.h.

◆ QS_OBJ_

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

Internal 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 744 of file qs.h.

◆ QS_FUN_

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

Internal macro to output an unformatted function pointer.

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 762 of file qs.h.

◆ QS_SIG_DICTIONARY

#define QS_SIG_DICTIONARY (   sig_,
  obj_ 
)
Value:
do { \
static char_t const sig_name_[] = #sig_; \
QS_sig_dict((sig_), (obj_), &sig_name_[0]); \
} while (0)
char char_t
typedef for character strings.
Definition: qep.h:70

Output signal dictionary record.

Description
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 * const me, QEvt const *) {
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(&me->super, HUNGRY_SIG);
QActive_subscribe(&me->super, DONE_SIG);
QActive_subscribe(&me->super, TERMINATE_SIG);
for (n = 0U; n < N; ++n) {
me->fork[n] = FREE;
me->isHungry[n] = 0U;
}
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 938 of file qs.h.

◆ QS_OBJ_DICTIONARY

#define QS_OBJ_DICTIONARY (   obj_)
Value:
do { \
static char_t const obj_name_[] = #obj_; \
QS_obj_dict((obj_), &obj_name_[0]); \
} while (0)
char char_t
typedef for character strings.
Definition: qep.h:70

Output object dictionary record.

Description
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:

static Table l_table;
void tableStart(uint8_t prio,
QEvt const *qSto[], uint32_t qLen,
void *stkSto, uint32_t stkSize)
{
QS_OBJ_DICTIONARY(&l_table); /* provide object dictionary for table */
table.start(prio,
qSto, qLen, stkSto, stkSize,
(QEvt *)0);
}

Definition at line 957 of file qs.h.

◆ QS_FUN_DICTIONARY

#define QS_FUN_DICTIONARY (   fun_)
Value:
do { \
static char_t const fun_name_[] = #fun_; \
QS_fun_dict((void (*)(void))(fun_), &fun_name_[0]); \
} while (0)
char char_t
typedef for character strings.
Definition: qep.h:70

Output function dictionary record.

Description
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 975 of file qs.h.

◆ QS_USR_DICTIONARY

#define QS_USR_DICTIONARY (   rec_)
Value:
do { \
static char_t const usr_name_[] = #rec_; \
QS_usr_dict((rec_), &usr_name_[0]); \
} while (0)
char char_t
typedef for character strings.
Definition: qep.h:70

Output user QS-record dictionary record.

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

Definition at line 986 of file qs.h.

◆ QS_ASSERTION

#define QS_ASSERTION (   module_,
  loc_,
  delay_ 
)
Value:
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_); \
QS_END_NOCRIT_() \
QS_onFlush(); \
for (delay_ctr_ = (delay_); delay_ctr_ > (uint32_t)0; --delay_ctr_) {} \
} while (0)
unsigned short uint16_t
exact-width 16-bit unsigned int
Definition: stdint.h:29
assertion failed in the code
Definition: qs.h:146
unsigned long uint32_t
exact-width 32-bit unsigned int
Definition: stdint.h:30

Output the assertion failure trace record.

Description
This trace record is intended to use from the Q_onAssert() callback.

Definition at line 996 of file qs.h.

◆ QS_FLUSH

#define QS_FLUSH ( )    (QS_onFlush())

Flush the QS trace data to the host.

Description
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 1015 of file qs.h.

◆ QF_QS_CRIT_ENTRY

#define QF_QS_CRIT_ENTRY ( )
Value:
QS_BEGIN_NOCRIT_(QS_QF_CRIT_ENTRY, (void *)0, (void *)0) \
QS_TIME_(); \
QS_U8_(++QS_priv_.critNest); \
QS_END_NOCRIT_()
#define QS_BEGIN_NOCRIT_(rec_, objFilter_, obj_)
Internal macro to begin a QS record without entering critical section.
Definition: qs.h:686
uint8_t critNest
critical section nesting level
Definition: qs.h:1078
critical section was entered
Definition: qs.h:110

Output the critical section entry.

Definition at line 1018 of file qs.h.

◆ QF_QS_CRIT_EXIT

#define QF_QS_CRIT_EXIT ( )
Value:
QS_BEGIN_NOCRIT_(QS_QF_CRIT_EXIT, (void *)0, (void *)0) \
QS_TIME_(); \
QS_U8_(QS_priv_.critNest--); \
QS_END_NOCRIT_()
critical section was exited
Definition: qs.h:111
#define QS_BEGIN_NOCRIT_(rec_, objFilter_, obj_)
Internal macro to begin a QS record without entering critical section.
Definition: qs.h:686
uint8_t critNest
critical section nesting level
Definition: qs.h:1078

Output the critical section exit.

Definition at line 1025 of file qs.h.

◆ QF_QS_ISR_ENTRY

#define QF_QS_ISR_ENTRY (   isrnest_,
  prio_ 
)
Value:
QS_BEGIN_NOCRIT_(QS_QF_ISR_ENTRY, (void *)0, (void *)0) \
QS_TIME_(); \
QS_2U8_(isrnest_, prio_); \
QS_END_NOCRIT_()
#define QS_BEGIN_NOCRIT_(rec_, objFilter_, obj_)
Internal macro to begin a QS record without entering critical section.
Definition: qs.h:686
an ISR was entered
Definition: qs.h:112

Output the interrupt entry record.

Definition at line 1032 of file qs.h.

◆ QF_QS_ISR_EXIT

#define QF_QS_ISR_EXIT (   isrnest_,
  prio_ 
)
Value:
QS_BEGIN_NOCRIT_(QS_QF_ISR_EXIT, (void *)0, (void *)0) \
QS_TIME_(); \
QS_2U8_(isrnest_, prio_); \
QS_END_NOCRIT_()
#define QS_BEGIN_NOCRIT_(rec_, objFilter_, obj_)
Internal macro to begin a QS record without entering critical section.
Definition: qs.h:686
an ISR was exited
Definition: qs.h:113

Output the interrupt exit record.

Definition at line 1039 of file qs.h.

◆ QS_RX_PUT

#define QS_RX_PUT (   b_)
Value:
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)
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:28
uint8_t * buf
pointer to the start of the ring buffer
Definition: qs.h:1121
uint_fast16_t QSCtr
QS ring buffer counter and offset type.
Definition: qs.h:1053
QSCtr head
offset to where next byte will be inserted
Definition: qs.h:1123
QSCtr tail
offset of where next byte will be extracted
Definition: qs.h:1124
QSCtr end
offset of the end of the ring buffer
Definition: qs.h:1122

put one byte into the QS RX lock-free buffer

Definition at line 1131 of file qs.h.

◆ QS_TEST_PAUSE

#define QS_TEST_PAUSE ( )
Value:
do { \
QS_beginRec((uint_fast8_t)QS_TEST_PAUSED); \
QS_endRec(); \
QS_onTestLoop(); \
} while (0)
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
test has been paused
Definition: qs.h:135

QS macro to pause test execution and enter the test event loop.

Definition at line 1185 of file qs.h.

Typedef Documentation

◆ QSTimeCtr

The type of the QS time stamp.

This type determines the dynamic range of QS time stamps

Definition at line 202 of file qs.h.

Enumeration Type Documentation

◆ QSpyRecords

Quantum Spy record types.

Description
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 125.
Note
The QS records labeled as "not maskable" are always enabled and cannot be turend off with the QS_FILTER_OFF() macro.
The numerical values of the QS trace records used by the Target and the host "back-end", such as the QSPY host application.
See also
QS_FILTER_ON() and QS_FILTER_OFF() macros
Enumerator
QS_EMPTY 

QS record for cleanly starting a session.

QS_QEP_STATE_ENTRY 

a state was entered

QS_QEP_STATE_EXIT 

a state was exited

QS_QEP_STATE_INIT 

an initial 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 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 memory pool

QS_QF_MPOOL_PUT 

a memory block was returned to 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_tickX() 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_QF_ACTIVE_POST_ATTEMPT 

attempt to post an evt to AO failed

QS_QF_EQUEUE_POST_ATTEMPT 

attempt to post an evt to QEQueue failed

QS_QF_MPOOL_GET_ATTEMPT 

attempt to get a memory block failed

QS_MUTEX_LOCK 

a mutex was locked

QS_MUTEX_UNLOCK 

a mutex was unlocked

QS_SCHED_LOCK 

scheduler was locked

QS_SCHED_UNLOCK 

scheduler was unlocked

QS_SCHED_NEXT 

scheduler found next task to execute

QS_SCHED_IDLE 

scheduler became idle

QS_SCHED_RESUME 

scheduler resumed previous task (not idle)

QS_QEP_TRAN_HIST 

a tran to history was taken

QS_QEP_TRAN_EP 

a tran to entry point into a submachine

QS_QEP_TRAN_XP 

a tran to exit point out of a submachine

QS_TEST_PAUSED 

test has been paused

QS_TEST_PROBE_GET 

reports that Test-Probe has been used

QS_SIG_DICT 

signal dictionary entry

QS_OBJ_DICT 

object dictionary entry

QS_FUN_DICT 

function dictionary entry

QS_USR_DICT 

user QS record dictionary entry

QS_TARGET_INFO 

reports the Target information

QS_TARGET_DONE 

reports completion of a user callback

QS_RX_STATUS 

reports QS data receive status

QS_PEEK_DATA 

reports the data from the PEEK query

QS_ASSERT_FAIL 

assertion failed in the code

QS_USER 

the first record available to QS users

Definition at line 65 of file qs.h.

◆ QSpyRecordGroups

QS record groups for QS_FILTER_ON() and QS_FILTER_OFF()

Enumerator
QS_ALL_RECORDS 

all maskable QS records

QS_SM_RECORDS 

State Machine QS records.

QS_AO_RECORDS 

Active Object QS records.

QS_EQ_RECORDS 

Event Queues QS records.

QS_MP_RECORDS 

Memory Pools QS records.

QS_TE_RECORDS 

Time Events QS records.

QS_QF_RECORDS 

QF QS records.

QS_SC_RECORDS 

Scheduler QS records.

QS_U0_RECORDS 

User Group 70-79 records.

QS_U1_RECORDS 

User Group 80-89 records.

QS_U2_RECORDS 

User Group 90-99 records.

QS_U3_RECORDS 

User Group 100-109 records.

QS_U4_RECORDS 

User Group 110-124 records.

QS_UA_RECORDS 

All User records.

Definition at line 153 of file qs.h.

◆ QSpyUserRecords

QS user record group offsets.

Enumerator
QS_USER0 

offset for User Group 0

QS_USER1 

offset for User Group 1

QS_USER2 

offset for User Group 2

QS_USER3 

offset for User Group 3

Definition at line 171 of file qs.h.

◆ anonymous enum

anonymous enum

Enumerates data formats recognized by QS.

Description
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 777 of file qs.h.

◆ QSpyObjKind

Kinds of objects used in QS.

Enumerator
SM_OBJ 

state machine object for QEP

AO_OBJ 

active object

MP_OBJ 

event pool object

EQ_OBJ 

raw queue object

TE_OBJ 

time event object

AP_OBJ 

generic Application-specific object

Definition at line 1056 of file qs.h.

◆ QSpyRxRecords

Quantum Spy Receive (RX) record types:

Description
This enumeration specifies the record types for the QS receive channel.
Enumerator
QS_RX_INFO 

query Target info (ver, config, tstamp)

QS_RX_COMMAND 

execute a user-defined command in the Target

QS_RX_RESET 

reset the Target

QS_RX_TICK 

call QF_TICK_X() in the Target

QS_RX_PEEK 

peek Target memory

QS_RX_POKE 

poke Target memory

QS_RX_FILL 

fill Target memory

QS_RX_TEST_SETUP 

test setup

QS_RX_TEST_TEARDOWN 

test teardown

QS_RX_TEST_PROBE 

set a Test-Probe in the Target

QS_RX_GLB_FILTER 

set global filters in the Target

QS_RX_LOC_FILTER 

set local filters in the Target

QS_RX_AO_FILTER 

set local AO filter in the Target

QS_RX_CURR_OBJ 

set the "current-object" in the Target

QS_RX_TEST_CONTINUE 

continue a test after QS_TEST_PAUSE()

QS_RX_RESERVED1 

reserved for future use

QS_RX_EVENT 

inject an event to the Target

Definition at line 1092 of file qs.h.

Function Documentation

◆ QS_initBuf()

void QS_initBuf ( uint8_t  sto[],
uint_fast16_t  stoSize 
)

Initialize the QS data buffer.

Description
This function should be called from QS_onStartup() to provide QS with the data buffer. The first parameter sto[] is the address of the memory block, and the second parameter stoSize is the size of this block in bytes. Currently the size of the QS buffer cannot exceed 64KB.
Note
QS can work with quite small data buffers, but you will start losing data if the buffer is too small for the bursts of tracing 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.
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 check sums on each record allow the QSPY host uitiliy to easily detect any data loss.
This function initializes all the internal QS variables, so that the tracing can start correctly even if the startup code fails to clear any uninitialized data (as is required by the C Standard).

Definition at line 79 of file qs.c.

◆ QS_filterOn()

void QS_filterOn ( uint_fast8_t  rec)

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

Description
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 124 of file qs.c.

◆ QS_filterOff()

void QS_filterOff ( uint_fast8_t  rec)

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

Description
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 (global filter). The second layer is based on the object-type (local filter). Both filter layers must be enabled for the QS record to be inserted into the QS buffer.

Definition at line 212 of file qs.c.

◆ QS_beginRec()

void QS_beginRec ( uint_fast8_t  rec)

Mark the begin of a QS record rec.

Description
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 301 of file qs.c.

◆ QS_endRec()

void QS_endRec ( void  )

Mark the end of a QS record rec.

Description
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 328 of file qs.c.

◆ QS_u8_()

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 549 of file qs.c.

◆ QS_u8u8_()

void QS_u8u8_ ( uint8_t  d1,
uint8_t  d2 
)

output two uint8_t data elements without format information

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

Definition at line 566 of file qs.c.

◆ QS_u16_()

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 585 of file qs.c.

◆ QS_u32_()

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 608 of file qs.c.

◆ QS_str_()

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 631 of file qs.c.

◆ QS_u8()

void QS_u8 ( uint8_t  format,
uint8_t  d 
)

Output uint8_t data element with format information.

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

Definition at line 476 of file qs.c.

◆ QS_u16()

void QS_u16 ( uint8_t  format,
uint16_t  d 
)

output uint16_t data element with format information

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

Definition at line 497 of file qs.c.

◆ QS_u32()

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 523 of file qs.c.

◆ QS_f32()

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 48 of file qs_fp.c.

◆ QS_f64()

void QS_f64 ( uint8_t  format,
float64_t  d 
)

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

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

Definition at line 81 of file qs_fp.c.

◆ QS_str()

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 849 of file qs.c.

◆ QS_mem()

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 820 of file qs.c.

◆ QS_sig_dict()

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

Output signal dictionary record.

Note
This function is only to be used through macro QS_SIG_DICTIONARY()

Definition at line 743 of file qs.c.

◆ QS_obj_dict()

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

Output object dictionary record.

Note
This function is only to be used through macro QS_OBJ_DICTIONARY()

Definition at line 764 of file qs.c.

◆ QS_fun_dict()

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

Output function dictionary record.

Note
This function is only to be used through macro QS_FUN_DICTIONARY()

Definition at line 784 of file qs.c.

◆ QS_usr_dict()

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

Output user dictionary record.

Note
This function is only to be used through macro QS_USR_DICTIONARY()

Definition at line 802 of file qs.c.

◆ QS_getByte()

uint16_t QS_getByte ( void  )

Byte-oriented interface to the QS data buffer.

Description
This function delivers one byte at a time from the QS data buffer.
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 665 of file qs.c.

◆ QS_getBlock()

uint8_t const* QS_getBlock ( uint16_t pNbytes)

Block-oriented interface to the QS data buffer.

Description
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 parameter pNbytes is also used as input to provide the maximum size of the data block that the caller can accept.
Returns
if data is available, the function returns pointer to the contiguous block of data and sets the value pointed to by pNbytes to the # available bytes. If data is available at the time the function is called, the function returns 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 707 of file qs.c.

◆ QS_onStartup()

uint8_t QS_onStartup ( void const *  arg)

Callback to startup the QS facility.

Description
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.
Returns
the staus of initialization. Typically 1 (true) when the QS initialization was successful, or 0 (false) when it failed.
Usage
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 */

◆ QS_onCleanup()

void QS_onCleanup ( void  )

Callback to cleanup the QS facility.

Description
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.

◆ QS_onFlush()

void QS_onFlush ( void  )

Callback to flush the QS trace data to the host.

Description
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.

◆ QS_onGetTime()

QSTimeCtr QS_onGetTime ( void  )

Callback to obtain a timestamp for a QS record.

Description
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 predefined 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.
Returns
the current timestamp.
Usage
The following example shows using a system call to implement QS time stamping:
#ifdef Q_SPY
return (QSTimeCtr)clock();
}
. . .
#endif /* Q_SPY */

Definition at line 1160 of file qs_rx.c.

◆ QS_rxInitBuf()

void QS_rxInitBuf ( uint8_t  sto[],
uint16_t  stoSize 
)

Initialize the QS RX data buffer.

Description
This function should be called from QS_onStartup() to provide QS-RX with the receive data buffer.
Parameters
[in]sto[]the address of the memory block
[in]stoSizethe size of this block [bytes]. The size of the QS RX buffer cannot exceed 64KB.
Note
QS-RX can work with quite small data buffers, but you will start losing data if the buffer is not drained fast enough in the idle task.
If the data input rate exceeds the QS-RX processing rate, the data will be lost, but the QS protocol will notice that: (1) that the checksum in the incomplete QS records will fail; and (2) the sequence counter in QS records will show discontinuities.

The QS-RX channel will report any data errors by sending the QS_RX_DATA_ERROR trace record.

Definition at line 251 of file qs_rx.c.

◆ QS_rxGetNfree()

uint16_t QS_rxGetNfree ( void  )

Obtain the number of free bytes in the QS RX data buffer.

Description
This function is intended to be called from the ISR that reads the QS-RX bytes from the QSPY host application. The function returns the conservative number of free bytes currently available in the buffer, assuming that the head pointer is not being moved concurrently. The tail pointer might be moving, meaning that bytes can be concurrently removed from the buffer.

Definition at line 290 of file qs_rx.c.

◆ QS_getTestProbe_()

uint32_t QS_getTestProbe_ ( void(*)(void)  api)

QS internal function to get the Test-Probe for a given API.

Description
This function obtains the Test-Probe for a given API.
Parameters
[in]api_idthe API-ID that requests its Test-Probe

Test-Probe data that has been received for the given API from the Host (running qutest). For any ginve API, the function returns the Test-Probe data in the same order as it was received from the Host. If there is no Test-Probe for a ginve API, or no more Test-Probes for a given API, the function returns zero.

Definition at line 1136 of file qs_rx.c.