QTools  7.1.2
Collection of Host-Based Tools
Loading...
Searching...
No Matches
qpc_qs.h File Reference

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

Go to the source code of this file.

Data Structures

struct  QSpyId
 QS ID type for applying local filtering. More...
 
struct  QS_tx
 Software tracing, output QS-TX. More...
 
struct  QS_rx
 QS software tracing parameters for QS input (QS-RX) More...
 
struct  QS_TProbe
 Test Probe attributes. More...
 
struct  QS_TestData
 QUTest data. More...
 
class  QHsmDummy
 QHsmDummy class. More...
 
class  QActiveDummy
 QActiveDummy Object class. More...
 

Macros

#define QS_TIME_SIZE   4U
 
#define QS_EOD   ((uint16_t)0xFFFFU)
 
#define QS_INIT(arg_)   (QS_onStartup(arg_))
 
#define QS_EXIT()   (QS_onCleanup())
 
#define QS_OUTPUT()   (QS_output())
 
#define QS_RX_INPUT()   (QS_rx_input())
 
#define QS_GLB_FILTER(rec_)   (QS_glbFilter_((int_fast16_t)(rec_)))
 
#define QS_LOC_FILTER(qs_id_)   (QS_locFilter_((int_fast16_t)(qs_id_)))
 
#define QS_BEGIN_ID(rec_, qs_id_)
 
#define QS_END()
 
#define QS_FLUSH()   (QS_onFlush())
 
#define QS_BEGIN_NOCRIT(rec_, qs_id_)
 
#define QS_END_NOCRIT()
 
#define QS_GLB_CHECK_(rec_)
 
#define QS_LOC_CHECK_(qs_id_)
 
#define QS_REC_DONE()   ((void)0)
 
#define QS_I8(width_, data_)    (QS_u8_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_I8_T, (data_)))
 
#define QS_U8(width_, data_)    (QS_u8_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_U8_T, (data_)))
 
#define QS_I16(width_, data_)    (QS_u16_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_I16_T, (data_)))
 
#define QS_U16(width_, data_)    (QS_u16_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_U16_T, (data_)))
 
#define QS_I32(width_, data_)    (QS_u32_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_I32_T, (data_)))
 
#define QS_U32(width_, data_)    (QS_u32_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_U32_T, (data_)))
 
#define QS_I64(width_, data_)    (QS_u64_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_I64_T, (data_)))
 
#define QS_U64(width_, data_)    (QS_u64_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_U64_T, (data_)))
 
#define QS_F32(width_, data_)    (QS_f32_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_F32_T, (data_)))
 
#define QS_F64(width_, data_)    (QS_f64_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_F64_T, (data_)))
 
#define QS_STR(str_)   (QS_str_fmt_((str_)))
 
#define QS_MEM(mem_, size_)   (QS_mem_fmt_((mem_), (size_)))
 
#define QS_TIME_PRE_()   (QS_u32_raw_(QS_onGetTime()))
 
#define QS_SIG_DICTIONARY(sig_, obj_)    (QS_sig_dict_pre_((sig_), (obj_), #sig_))
 
#define QS_OBJ_DICTIONARY(obj_)    (QS_obj_dict_pre_((obj_), #obj_))
 
#define QS_OBJ_ARR_DICTIONARY(obj_, idx_)    (QS_obj_arr_dict_pre_((obj_), (idx_), #obj_))
 
#define QS_FUN_DICTIONARY(fun_)    (QS_fun_dict_pre_((void (*)(void))(fun_), #fun_))
 
#define QS_USR_DICTIONARY(rec_)    (QS_usr_dict_pre_((rec_), #rec_))
 
#define QF_QS_ACTION(act_)   (act_)
 
#define QS_CRIT_STAT_
 
#define QS_CRIT_E_()   QF_CRIT_ENTRY(dummy)
 
#define QS_CRIT_X_()   QF_CRIT_EXIT(dummy); QS_REC_DONE()
 
#define QUTEST_ON_POST   124
 
#define QS_TEST_PROBE_DEF(fun_)    uint32_t const qs_tp_ = QS_getTestProbe_((void (*)(void))(fun_));
 
#define QS_TEST_PROBE(code_)    if (qs_tp_ != 0U) { code_ }
 
#define QS_TEST_PROBE_ID(id_, code_)    if (qs_tp_ == (uint32_t)(id_)) { code_ }
 
#define QS_TEST_PAUSE()   (QS_test_pause_())
 

Typedefs

typedef uint32_t QSTimeCtr
 
typedef uint_fast16_t QSCtr
 
typedef void(* QSpyFunPtr) (void)
 

Enumerations

enum  QSpyPre {
  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_DEFER , QS_QF_ACTIVE_RECALL ,
  QS_QF_ACTIVE_SUBSCRIBE , QS_QF_ACTIVE_UNSUBSCRIBE , QS_QF_ACTIVE_POST , QS_QF_ACTIVE_POST_LIFO ,
  QS_QF_ACTIVE_GET , QS_QF_ACTIVE_GET_LAST , QS_QF_ACTIVE_RECALL_ATTEMPT , QS_QF_EQUEUE_POST ,
  QS_QF_EQUEUE_POST_LIFO , QS_QF_EQUEUE_GET , QS_QF_EQUEUE_GET_LAST , QS_QF_NEW_ATTEMPT ,
  QS_QF_MPOOL_GET , QS_QF_MPOOL_PUT , QS_QF_PUBLISH , QS_QF_NEW_REF ,
  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_DELETE_REF , QS_QF_CRIT_ENTRY ,
  QS_QF_CRIT_EXIT , QS_QF_ISR_ENTRY , QS_QF_ISR_EXIT , QS_QF_INT_DISABLE ,
  QS_QF_INT_ENABLE , QS_QF_ACTIVE_POST_ATTEMPT , QS_QF_EQUEUE_POST_ATTEMPT , QS_QF_MPOOL_GET_ATTEMPT ,
  QS_SCHED_PREEMPT , QS_SCHED_RESTORE , 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_QUERY_DATA ,
  QS_PEEK_DATA , QS_ASSERT_FAIL , QS_QF_RUN , QS_SEM_TAKE ,
  QS_SEM_BLOCK , QS_SEM_SIGNAL , QS_SEM_BLOCK_ATTEMPT , QS_MTX_LOCK ,
  QS_MTX_BLOCK , QS_MTX_UNLOCK , QS_MTX_LOCK_ATTEMPT , QS_MTX_BLOCK_ATTEMPT ,
  QS_MTX_UNLOCK_ATTEMPT , QS_PRE_MAX
}
 
enum  QSpyGroups {
  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_SEM_RECORDS , QS_MTX_RECORDS , QS_U0_RECORDS , QS_U1_RECORDS ,
  QS_U2_RECORDS , QS_U3_RECORDS , QS_U4_RECORDS , QS_UA_RECORDS
}
 
enum  QSpyUserOffsets {
  QS_USER = 100 , QS_USER0 = (enum_t)QS_USER , QS_USER1 = (enum_t)QS_USER0 + 5 , QS_USER2 = (enum_t)QS_USER1 + 5 ,
  QS_USER3 = (enum_t)QS_USER2 + 5 , QS_USER4 = (enum_t)QS_USER3 + 5
}
 
enum  QSpyIdOffsets { QS_AO_ID = 0 , QS_EP_ID = 64 , QS_EQ_ID = 80 , QS_AP_ID = 96 }
 
enum  QSpyIdGroups {
  QS_ALL_IDS = 0xF0 , QS_AO_IDS = (0x80 + (enum_t)QS_AO_ID) , QS_EP_IDS = (0x80 + (enum_t)QS_EP_ID) , QS_EQ_IDS = (0x80 + (enum_t)QS_EQ_ID) ,
  QS_AP_IDS = (0x80 + (enum_t)QS_AP_ID)
}
 
enum  QS_preType {
  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_HEX_FMT
}
 
enum  QS_QSpyObjKind {
  SM_OBJ , AO_OBJ , MP_OBJ , EQ_OBJ ,
  TE_OBJ , AP_OBJ , MAX_OBJ
}
 
enum  QS_OSpyObjCombnation { SM_AO_OBJ = (enum_t)MAX_OBJ }
 

Functions

void QS_onCleanup (void)
 
void QS_onFlush (void)
 
QSTimeCtr QS_onGetTime (void)
 
void QF_QS_CRIT_ENTRY (void)
 
void QF_QS_CRIT_EXIT (void)
 
void QF_QS_ISR_ENTRY (uint_fast8_t const isrnest, uint_fast8_t const prio_)
 

Variables

QS_tx QS_priv_
 
QS_rx QS_rxPriv_
 
struct QS_TestData QS_testData
 

Data Structure Documentation

◆ QSpyId

struct QSpyId

Definition at line 315 of file qpc_qs.h.

Data Fields
uint8_t prio

◆ QS_tx

struct QS_tx

This class groups together QS services.

Definition at line 323 of file qpc_qs.h.

Data Fields
uint8_t glbFilter[16]

global on/off QS filter

uint8_t locFilter[16]

local on/off QS filter

void const * locFilter_AP
Deprecated:
old local QS filter
uint8_t * buf

pointer to the start of the QS-TX ring buffer

QSCtr end

offset of the end of the ring buffer

QSCtr volatile head

offset to where next byte will be inserted

QSCtr volatile tail

offset of where next record will be extracted

QSCtr volatile used

number of bytes currently in the ring buffer

uint8_t volatile seq

sequence number of the last inserted QS record

uint8_t volatile chksum

checksum of the currently inserted record

uint8_t volatile critNest

critical section nesting level

◆ QS_rx

struct QS_rx

Definition at line 757 of file qpc_qs.h.

Data Fields
void * currObj[8]
uint8_t * buf
QSCtr end
QSCtr volatile head
QSCtr volatile tail
bool inTestLoop

◆ QS_TProbe

struct QS_TProbe

Definition at line 1414 of file qpc_qs.h.

Data Fields
QSFun addr
uint32_t data
uint8_t idx

◆ QS_TestData

struct QS_TestData

Definition at line 1422 of file qpc_qs.h.

Data Fields
struct QS_TProbe tpBuf[16]

buffer of Test-Probes received so far

uint8_t tpNum

current number of Test-Probes

QSTimeCtr testTime

test time (tick counter)

Macro Definition Documentation

◆ QS_TIME_SIZE

#define QS_TIME_SIZE   4U

The size [bytes] of the QS time stamp. Valid values: 1U, 2U, or 4U; default 4U.

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 62 of file qpc_qs.h.

◆ QS_EOD

#define QS_EOD   ((uint16_t)0xFFFFU)

Constant representing End-Of-Data condition returned from the QS_getByte() function.

Definition at line 311 of file qpc_qs.h.

◆ QS_INIT

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

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_GLB_FILTER()

Definition at line 928 of file qpc_qs.h.

◆ QS_EXIT

#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_onCleanup()

Definition at line 938 of file qpc_qs.h.

◆ QS_OUTPUT

#define QS_OUTPUT ( )    (QS_output())

macro to handle the QS output from the application

Note
If this macro is used, the application must define QS_output().

Definition at line 946 of file qpc_qs.h.

◆ QS_RX_INPUT

#define QS_RX_INPUT ( )    (QS_rx_input())

macro to handle the QS-RX input to the application

Note
If this macro is used, the application must define QS_doInput().

Definition at line 954 of file qpc_qs.h.

◆ QS_GLB_FILTER

#define QS_GLB_FILTER (   rec_)    (QS_glbFilter_((int_fast16_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.

See also
  • ::QSpyRecordGroups - QS record groups that can be used as rec_
  • ::QSpyRecords - individual QS records that can be used as rec_
Usage
The following example shows how to use QS filters:

Definition at line 971 of file qpc_qs.h.

◆ QS_LOC_FILTER

#define QS_LOC_FILTER (   qs_id_)    (QS_locFilter_((int_fast16_t)(qs_id_)))

Local Filter for a given state machine object qs_id

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

See also

The following example shows how to use QS filters:

Definition at line 987 of file qpc_qs.h.

◆ QS_BEGIN_ID

#define QS_BEGIN_ID (   rec_,
  qs_id_ 
)
Value:
if (QS_GLB_CHECK_(rec_) && QS_LOC_CHECK_(qs_id_)) { \
QS_CRIT_STAT_ \
QS_CRIT_E_(); \
QS_beginRec_((uint_fast8_t)(rec_)); \
QS_TIME_PRE_(); {
#define QS_LOC_CHECK_(qs_id_)
Definition: qpc_qs.h:1052
#define QS_GLB_CHECK_(rec_)
Definition: qpc_qs.h:1046

Begin an application-specific QS record with entering critical section

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

Note
Must always be used in pair with QS_END()

Definition at line 1002 of file qpc_qs.h.

◆ QS_END

#define QS_END ( )
Value:
} \
QS_endRec_(); \
QS_CRIT_X_(); \
}

End an application-specific QS record with exiting critical section.

See also
example for QS_BEGIN_ID()
Note
Must always be used in pair with QS_BEGIN_ID()

Definition at line 1015 of file qpc_qs.h.

◆ QS_FLUSH

#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 1029 of file qpc_qs.h.

◆ QS_BEGIN_NOCRIT

#define QS_BEGIN_NOCRIT (   rec_,
  qs_id_ 
)
Value:
if (QS_GLB_CHECK_(rec_) && QS_LOC_CHECK_(qs_id_)) { \
QS_beginRec_((uint_fast8_t)(rec_)); \
QS_TIME_PRE_(); {

Begin an application-specific QS record WITHOUT entering critical section

Definition at line 1033 of file qpc_qs.h.

◆ QS_END_NOCRIT

#define QS_END_NOCRIT ( )
Value:
} \
QS_endRec_();\
}

End an application-specific QS record WITHOUT exiting critical section

Definition at line 1040 of file qpc_qs.h.

◆ QS_GLB_CHECK_

#define QS_GLB_CHECK_ (   rec_)
Value:
(((uint_fast8_t)QS_priv_.glbFilter[(uint_fast8_t)(rec_) >> 3U] \
& ((uint_fast8_t)1U << ((uint_fast8_t)(rec_) & 7U))) != 0U)
uint8_t glbFilter[16]
Definition: qpc_qs.h:327
QS_tx QS_priv_

Helper macro for checking the global QS filter

Definition at line 1046 of file qpc_qs.h.

◆ QS_LOC_CHECK_

#define QS_LOC_CHECK_ (   qs_id_)
Value:
(((uint_fast8_t)QS_priv_.locFilter[(uint_fast8_t)(qs_id_) >> 3U] \
& ((uint_fast8_t)1U << ((uint_fast8_t)(qs_id_) & 7U))) != 0U)
uint8_t locFilter[16]
Definition: qpc_qs.h:330

Helper macro for checking the local QS filter

Definition at line 1052 of file qpc_qs.h.

◆ QS_REC_DONE

#define QS_REC_DONE ( )    ((void)0)

Macro to execute user code when a QS record is produced

Note
This is a dummy definition in case this macro is undefined.

Definition at line 1063 of file qpc_qs.h.

◆ QS_I8

#define QS_I8 (   width_,
  data_ 
)     (QS_u8_fmt_((uint8_t)(((width_) << 4)) | (uint8_t)QS_I8_T, (data_)))

Output formatted int8_t to the QS record

Definition at line 1068 of file qpc_qs.h.

◆ QS_U8

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

Output formatted uint8_t to the QS record

Definition at line 1073 of file qpc_qs.h.

◆ QS_I16

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

Output formatted int16_t to the QS record

Definition at line 1078 of file qpc_qs.h.

◆ QS_U16

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

Output formatted uint16_t to the QS record

Definition at line 1083 of file qpc_qs.h.

◆ QS_I32

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

Output formatted int32_t to the QS record

Definition at line 1088 of file qpc_qs.h.

◆ QS_U32

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

Output formatted uint32_t to the QS record

Definition at line 1093 of file qpc_qs.h.

◆ QS_I64

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

Output formatted int64_t to the QS record

Definition at line 1098 of file qpc_qs.h.

◆ QS_U64

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

Output formatted uint64_t to the QS record

Definition at line 1103 of file qpc_qs.h.

◆ QS_F32

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

Output formatted 32-bit floating point number to the QS record

Definition at line 1108 of file qpc_qs.h.

◆ QS_F64

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

Output formatted 64-bit floating point number to the QS record

Definition at line 1113 of file qpc_qs.h.

◆ QS_STR

#define QS_STR (   str_)    (QS_str_fmt_((str_)))

Output formatted zero-terminated ASCII string to the QS record

Definition at line 1118 of file qpc_qs.h.

◆ QS_MEM

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

Output formatted memory block of up to 255 bytes to the QS record

Definition at line 1122 of file qpc_qs.h.

◆ QS_TIME_PRE_

#define QS_TIME_PRE_ ( )    (QS_u32_raw_(QS_onGetTime()))

Output time stamp to a QS record (used in predefined and application-specific trace records)

Definition at line 1129 of file qpc_qs.h.

◆ QS_SIG_DICTIONARY

#define QS_SIG_DICTIONARY (   sig_,
  obj_ 
)     (QS_sig_dict_pre_((sig_), (obj_), #sig_))

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

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:

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

Definition at line 1249 of file qpc_qs.h.

◆ QS_OBJ_DICTIONARY

#define QS_OBJ_DICTIONARY (   obj_)     (QS_obj_dict_pre_((obj_), #obj_))

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:

Definition at line 1267 of file qpc_qs.h.

◆ QS_OBJ_ARR_DICTIONARY

#define QS_OBJ_ARR_DICTIONARY (   obj_,
  idx_ 
)     (QS_obj_arr_dict_pre_((obj_), (idx_), #obj_))

Output object-array dictionary record

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

Providing a 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 array dictionary for Philo::inst[n] and Philo::inst[n].m_timeEvt:

Definition at line 1286 of file qpc_qs.h.

◆ QS_FUN_DICTIONARY

#define QS_FUN_DICTIONARY (   fun_)     (QS_fun_dict_pre_((void (*)(void))(fun_), #fun_))

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 1303 of file qpc_qs.h.

◆ QS_USR_DICTIONARY

#define QS_USR_DICTIONARY (   rec_)     (QS_usr_dict_pre_((rec_), #rec_))

Output user QS record dictionary record

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

Definition at line 1313 of file qpc_qs.h.

◆ QF_QS_ACTION

#define QF_QS_ACTION (   act_)    (act_)

Execute an action that is only necessary for QS output

Definition at line 1340 of file qpc_qs.h.

◆ QS_CRIT_STAT_

#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 1372 of file qpc_qs.h.

◆ QS_CRIT_E_

#define QS_CRIT_E_ ( )    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 1383 of file qpc_qs.h.

◆ QS_CRIT_X_

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

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 1394 of file qpc_qs.h.

◆ QUTEST_ON_POST

#define QUTEST_ON_POST   124

record-ID for posting events

Definition at line 1480 of file qpc_qs.h.

◆ QS_TEST_PROBE_DEF

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

Definition at line 1606 of file qpc_qs.h.

◆ QS_TEST_PROBE

#define QS_TEST_PROBE (   code_)     if (qs_tp_ != 0U) { code_ }

QS macro to apply a Test-Probe

Definition at line 1610 of file qpc_qs.h.

◆ QS_TEST_PROBE_ID

#define QS_TEST_PROBE_ID (   id_,
  code_ 
)     if (qs_tp_ == (uint32_t)(id_)) { code_ }

QS macro to apply a Test-Probe

Definition at line 1614 of file qpc_qs.h.

◆ QS_TEST_PAUSE

#define QS_TEST_PAUSE ( )    (QS_test_pause_())

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

Definition at line 1618 of file qpc_qs.h.

Typedef Documentation

◆ QSTimeCtr

typedef uint32_t QSTimeCtr

QS time stamp type, which determines the dynamic range of QS time stamps

Definition at line 77 of file qpc_qs.h.

◆ QSCtr

typedef uint_fast16_t QSCtr

QS function pointer type (for serializing function pointers)

QS ring buffer counter and offset type

Definition at line 113 of file qpc_qs.h.

◆ QSpyFunPtr

typedef void(* QSpyFunPtr) (void)

function pointer type for QS_fun_dict_pre_()

Definition at line 305 of file qpc_qs.h.

Enumeration Type Documentation

◆ QSpyPre

enum QSpyPre

QS pre-defined record types (TX channel)

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_GLB_FILTER() macro. Other QS trace records can be disabled by means of the "global filters"
See also
QS_GLB_FILTER() macro
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 un-handled due to a guard

QS_QF_ACTIVE_DEFER 

AO deferred an event

QS_QF_ACTIVE_RECALL 

AO recalled an event

QS_QF_ACTIVE_SUBSCRIBE 

an AO subscribed to an event

QS_QF_ACTIVE_UNSUBSCRIBE 

an AO unsubscribed to an event

QS_QF_ACTIVE_POST 

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_ACTIVE_RECALL_ATTEMPT 

AO attempted to recall an event

QS_QF_EQUEUE_POST 

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_NEW_ATTEMPT 

an attempt to allocate an event failed

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 to active objects

QS_QF_NEW_REF 

new event reference was created

QS_QF_NEW 

new event was created

QS_QF_GC_ATTEMPT 

garbage collection attempt

QS_QF_GC 

garbage collection

QS_QF_TICK 

QTimeEvt_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_DELETE_REF 

an event reference is about to be deleted

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_SCHED_PREEMPT 

scheduler asynchronously preempted a task

QS_SCHED_RESTORE 

scheduler restored preempted task

QS_SCHED_LOCK 

scheduler was locked

QS_SCHED_UNLOCK 

scheduler was unlocked

QS_SCHED_NEXT 

scheduler started new task

QS_SCHED_IDLE 

scheduler restored the idle task

QS_SCHED_RESUME 

scheduler resumed a task

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_QUERY_DATA 

reports the data from "current object" query

QS_PEEK_DATA 

reports the data from the PEEK query

QS_ASSERT_FAIL 

assertion failed in the code

QS_QF_RUN 

QF_run() was entered

QS_SEM_TAKE 

a semaphore was taken by a thread

QS_SEM_BLOCK 

a semaphore blocked a thread

QS_SEM_SIGNAL 

a semaphore was signaled

QS_SEM_BLOCK_ATTEMPT 

a semaphore blocked was attempted

QS_MTX_LOCK 

a mutex was locked

QS_MTX_BLOCK 

a mutex blocked a thread

QS_MTX_UNLOCK 

a mutex was unlocked

QS_MTX_LOCK_ATTEMPT 

a mutex lock was attempted

QS_MTX_BLOCK_ATTEMPT 

a mutex blocking was attempted

QS_MTX_UNLOCK_ATTEMPT 

a mutex unlock was attempted

QS_PRE_MAX 

the number of predefined signals

Definition at line 130 of file qpc_qs.h.

◆ QSpyGroups

enum QSpyGroups

QS record groups for QS_GLB_FILTER()

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_SEM_RECORDS 

Semaphore QS records

QS_MTX_RECORDS 

Mutex QS records

QS_U0_RECORDS 

User Group 100-104 records

QS_U1_RECORDS 

User Group 105-109 records

QS_U2_RECORDS 

User Group 110-114 records

QS_U3_RECORDS 

User Group 115-119 records

QS_U4_RECORDS 

User Group 120-124 records

QS_UA_RECORDS 

All User records

Definition at line 254 of file qpc_qs.h.

◆ QSpyUserOffsets

QS user record group offsets for QS_GLB_FILTER()

Enumerator
QS_USER 

the first record available to QS users

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

QS_USER4 

offset for User Group 4

Definition at line 275 of file qpc_qs.h.

◆ QSpyIdOffsets

QS ID offsets for QS_LOC_FILTER()

Enumerator
QS_AO_ID 

offset for AO priorities

QS_EP_ID 

offset for event-pool IDs

QS_EQ_ID 

offset for event-queue IDs

QS_AP_ID 

offset for Application-specific IDs

Definition at line 286 of file qpc_qs.h.

◆ QSpyIdGroups

QS ID groups for QS_LOC_FILTER()

Enumerator
QS_ALL_IDS 

all QS IDs

QS_AO_IDS 

AO IDs (priorities)

QS_EP_IDS 

event-pool IDs

QS_EQ_IDS 

event-queue IDs

QS_AP_IDS 

Application-specific IDs

Definition at line 295 of file qpc_qs.h.

◆ QS_preType

enum QS_preType

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_HEX_FMT 

HEX format for the "width" filed

Definition at line 367 of file qpc_qs.h.

◆ QS_QSpyObjKind

Kinds of objects used in QS_setCurrObj() and QS_queryCurrObj()

Enumerator
SM_OBJ 

state machine object

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

MAX_OBJ 

Definition at line 775 of file qpc_qs.h.

◆ QS_OSpyObjCombnation

Object combinations for QS_setCurrObj() and QS_queryCurrObj()

Enumerator
SM_AO_OBJ 

combination of SM and AO

Definition at line 787 of file qpc_qs.h.

Function Documentation

◆ QS_onCleanup()

void QS_onCleanup ( void  )

◆ QS_onFlush()

void QS_onFlush ( void  )

◆ QS_onGetTime()

QSTimeCtr QS_onGetTime ( void  )

◆ QF_QS_CRIT_ENTRY()

void QF_QS_CRIT_ENTRY ( void  )

Output the critical section entry record

◆ QF_QS_CRIT_EXIT()

void QF_QS_CRIT_EXIT ( void  )

Output the critical section exit record

◆ QF_QS_ISR_ENTRY()

void QF_QS_ISR_ENTRY ( uint_fast8_t const  isrnest,
uint_fast8_t const  prio_ 
)

Output the interrupt entry record

Variable Documentation

◆ QS_priv_

QS_tx QS_priv_
extern

the only instance of the QS-TX object (Singleton)

◆ QS_rxPriv_

QS_rx QS_rxPriv_
extern

the only instance of the QS-RX object (Singleton)

◆ QS_testData

struct QS_TestData QS_testData
extern

QUTest data