qpc_qs.h File Reference

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

Go to the source code of this file.

Classes
struct	QSpyId
	QS ID type for applying local filtering. More...
struct	QS_tx
class	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_CTR_SIZE   2U
#define	QS_TIME_SIZE   4U
#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_)
#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_ENUM(group_, value_)
#define	QS_TIME_PRE_()   (QS_u32_raw_(QS_onGetTime()))
#define	QS_OBJ(obj_)   (QS_u32_fmt_(QS_OBJ_T, (uint32_t)(obj_)))
#define	QS_FUN(fun_)   (QS_u32_fmt_(QS_FUN_T, (uint32_t)(fun_)))
#define	QS_SIG(sig_, obj_)
#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	QS_ENUM_DICTIONARY(value_, group_)    (QS_enum_dict_pre_((value_), (group_), #value_))
#define	QF_QS_ACTION(act_)   (act_)
#define	QS_EOD   ((uint16_t)0xFFFFU)
#define	QS_CMD   ((uint8_t)7U)
#define	QS_HEX_FMT   ((uint8_t)0x0FU)
#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 uint_fast16_t	QSCtr
typedef uint32_t	QSTimeCtr
typedef uint32_t	QSFun

Enumerations
enum	QS_preType {   QS_I8_ENUM_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 }

Functions
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_)
void	QF_QS_ISR_EXIT (uint_fast8_t isrnest, uint_fast8_t prio)
void	QS_test_pause_ (void)
uint32_t	QS_getTestProbe_ (QSpyFunPtr const api)
void	QS_onTestSetup (void)
void	QS_onTestTeardown (void)
void	QS_onTestEvt (QEvt *e)
void	QS_onTestPost (void const *sender, QActive *recipient, QEvt const *e, bool status)
void	QS_onTestLoop (void)
void	QS_processTestEvts_ (void)

Variables
QS_tx	QS_priv_
struct QS_TestData	QS_testData

---

Class Documentation

QSpyId

struct QSpyId

Definition at line 347 of file qpc_qs.h.

Class Members
uint8_t	prio

QS_TProbe

struct QS_TProbe

Definition at line 1507 of file qpc_qs.h.

Class Members
QSFun	addr
uint32_t	data
uint8_t	idx

QS_TestData

struct QS_TestData

Definition at line 1515 of file qpc_qs.h.

Class Members
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_CTR_SIZE

#define QS_CTR_SIZE   2U

The size [bytes] of the internal QS buffer-counters. Valid values: 2U or 4U; default 2U.

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

Definition at line 62 of file qpc_qs.h.

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 80 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 998 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 1008 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 1016 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 1024 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

• enum QSpyGroups - QS record groups that can be used as rec_
• enum QSpyPre - predefined QS records that can be used as rec_

Usage

The following example shows how to use QS filters:

int main(int arc, char *argv[]) {
    . . .
 
    if (!QS_INIT(argv)) {         /* Initialize QS target component */
        return -1;                /* unable to initialize QSpy */
    }
 
    /* apply the global QS filters~~~ */
    /* NOTE: global filters start as being all OFF */
    QS_GLB_FILTER(QS_QF_RECORDS); /* turn QF-group ON */
    QS_GLB_FILTER(-QS_QF_TICK);   /* turn #QS_QF_TICK OFF */
 
    /* apply the local QS filters~~~ */
    /* NOTE: local filters start as being all ON */
    QS_LOC_FILTER(-QS_EP_IDS);    /* turn EP (Event-Pool) group  OFF */
    QS_LOC_FILTER(3);             /* turn AO with prioity 3 ON */
 
    /* start the active objects~~~ */
    . . .
 
    /* NOTE: the following will work only after AO_Table has been started */
    QS_LOC_FILTER(-AO_Table->prio); /* turn AO_Table OFF */
 
    . . .
}

Definition at line 1041 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

• enum QSpyIdGroups - QS ID groups that can be used as qs_id_
• enum QSpyIdOffsets - QS ID offsets for qs_id_ (e.g., QS_AP_IDS + 5)

The following example shows how to use QS filters:

int main(int arc, char *argv[]) {
    . . .
 
    if (!QS_INIT(argv)) {         /* Initialize QS target component */
        return -1;                /* unable to initialize QSpy */
    }
 
    /* apply the global QS filters~~~ */
    /* NOTE: global filters start as being all OFF */
    QS_GLB_FILTER(QS_QF_RECORDS); /* turn QF-group ON */
    QS_GLB_FILTER(-QS_QF_TICK);   /* turn #QS_QF_TICK OFF */
 
    /* apply the local QS filters~~~ */
    /* NOTE: local filters start as being all ON */
    QS_LOC_FILTER(-QS_EP_IDS);    /* turn EP (Event-Pool) group  OFF */
    QS_LOC_FILTER(3);             /* turn AO with prioity 3 ON */
 
    /* start the active objects~~~ */
    . . .
 
    /* NOTE: the following will work only after AO_Table has been started */
    QS_LOC_FILTER(-AO_Table->prio); /* turn AO_Table OFF */
 
    . . .
}

Definition at line 1057 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_(); {

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

enum UserSpyRecords {
    . . .
    PHILO_STAT = QS_USER, /* define a user QS record types */
    . . .
};
 
void displyPhilStat(uint8_t n, char const *stat) {
    . . .
 
    /* application-specific record */
    QS_BEGIN_ID(PHILO_STAT, AO_Philo[n]->prio);
        QS_U8(0, n);    /* Philosopher number */
        QS_STR(stat);   /* Philosopher status */
        QS_U8(QS_HEX_FMT,  0xABU);                /* test */
        QS_U16(QS_HEX_FMT, 0xDEADU);              /* test */
        QS_U32(QS_HEX_FMT, 0xDEADBEEFU);          /* test */
        QS_U64(QS_HEX_FMT, 0xDEADBEEF12345678LL); /* test */
    QS_END();
}
 
QSPY ouptut produced:
 
4294954639 PHILO_STAT 3 thinking 0xAB 0xDEAD 0xDEADBEEF 0xDEADBEEF12345678
 

Definition at line 1072 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 1085 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 1099 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 1103 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 1110 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)

Helper macro for checking the global QS filter

Definition at line 1116 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)

Helper macro for checking the local QS filter

Definition at line 1122 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 1133 of file qpc_qs.h.

QS_I8

#define QS_I8	(		width_,
			data_
	)

Value:

    (QS_u8_fmt_((uint8_t)(((width_) << 4U) & 0x7U) | (uint8_t)QS_I8_ENUM_T, \
                (data_)))

Output formatted int8_t to the QS record

Definition at line 1138 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 1144 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 1149 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 1154 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 1159 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 1164 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 1169 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 1174 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 1179 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 1184 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 1189 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 1193 of file qpc_qs.h.

QS_ENUM

#define QS_ENUM	(		group_,
			value_
	)

Value:

    (QS_u8_fmt_((uint8_t)(0x80U | ((group_) << 4U)) | (uint8_t)QS_I8_ENUM_T,\
                (uint8_t)(value_)))

Output formatted enumeration to the QS record

Definition at line 1197 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 1206 of file qpc_qs.h.

QS_OBJ

#define QS_OBJ

(

obj_

)

(QS_u32_fmt_(QS_OBJ_T, (uint32_t)(obj_)))

Output formatted object pointer to the QS record

Definition at line 1222 of file qpc_qs.h.

QS_FUN

#define QS_FUN

(

fun_

)

(QS_u32_fmt_(QS_FUN_T, (uint32_t)(fun_)))

Definition at line 1243 of file qpc_qs.h.

QS_SIG

#define QS_SIG	(		sig_,
			obj_
	)

Value:

        QS_u16_fmt_(QS_SIG_T, (sig_)); \
        QS_obj_raw_(obj_)

Definition at line 1273 of file qpc_qs.h.

QS_SIG_DICTIONARY

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

Output QS 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.

Parameters

[in]	sig_	event signal (typically enumerated, e.g. TIMEOUT_SIG)
[in]	obj_	pointer to the associated state machine object (might be (void*)0 for globally recognized signals)

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 many state machines (such as globally published signals), you can specify a signal dictionary entry with the obj_ parameter set to (void*)0.

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 *) {
 
    /* signals for all state machines~~~ */
    QS_SIG_DICTIONARY(EAT_SIG,    (void *)0);
    . . .
 
 
    /* signals for this specific state machine "me"~~~ */
    QS_SIG_DICTIONARY(HUNGRY_SIG, me);
    QS_SIG_DICTIONARY(DONE_SIG,   me);
    . . .
 
    return Q_TRAN(&Table_serving);
}

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

Definition at line 1318 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.

Parameters

[in]

obj_

pointer to the object (any object)

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

Table Table_inst; /* the instance of the Table Active Object */
 
/* top-most initial transition */
static QState Table_initial(Table * const me, QEvt const * const e) {
    . . .
    /* provide object dictionary for Table */
    QS_OBJ_DICTIONARY(&Table_inst); /* <--- */
    . . .
}

Definition at line 1334 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.

Parameters

[in]	obj_	pointer to the object (any object)
[in]	idx_	array index

The following example shows the definition of object array dictionary for Philo::inst[n] and Philo::inst[n].m_timeEvt:

Philo Philo_inst[N_PHILO];
. . .
for (uint8_t n = 0U; n < N_PHILO; ++n) {
    QS_OBJ_ARR_DICTIONARY(&Philo_inst[n], n);
    QS_OBJ_ARR_DICTIONARY(&Philo_inst[n].timeEvt, n);
}

Definition at line 1352 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 1369 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 1379 of file qpc_qs.h.

QS_ENUM_DICTIONARY

#define QS_ENUM_DICTIONARY	(		value_,
			group_
	)		(QS_enum_dict_pre_((value_), (group_), #value_))

Output enumeration dictionary record

An enum QS record dictionary record associates the numerical value of an enumeration with the human-readable identifier.

Definition at line 1389 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 1414 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 1420 of file qpc_qs.h.

QS_CMD

#define QS_CMD   ((uint8_t)7U)

Constant representing command enumeration group in QS_ENUM_DICTIONARY() and QS_ENUM()

See also

QS_onCommand()

Definition at line 1427 of file qpc_qs.h.

QS_HEX_FMT

#define QS_HEX_FMT   ((uint8_t)0x0FU)

Constant representing HEX format for the "width" filed in QS_U8(), QS_U16(), QS_U32(), and QS_U64().

Definition at line 1433 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 1465 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 1476 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 1487 of file qpc_qs.h.

QUTEST_ON_POST

#define QUTEST_ON_POST   124

record-ID for posting events

Definition at line 1559 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 1683 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 1687 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 1691 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 1695 of file qpc_qs.h.

Typedef Documentation

QSCtr

typedef uint_fast16_t QSCtr

QS ring buffer counter and offset type

Definition at line 95 of file qpc_qs.h.

QSTimeCtr

typedef uint32_t QSTimeCtr

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

Definition at line 106 of file qpc_qs.h.

QSFun

typedef uint32_t QSFun

QS function pointer type (for serializing function pointers)

Definition at line 122 of file qpc_qs.h.

Enumeration Type Documentation

QS_preType

enum QS_preType

Enumerates data elements for app-specific trace records

Enumerator
QS_I8_ENUM_T	signed 8-bit integer or enum 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

Definition at line 398 of file qpc_qs.h.

Function Documentation

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

QF_QS_ISR_EXIT()

void QF_QS_ISR_EXIT	(	uint_fast8_t	isrnest,
		uint_fast8_t	prio
	)

Output the ISR exit trace record

QS_test_pause_()

void QS_test_pause_

(

void

)

internal function to pause test and enter the test event loop

QS_getTestProbe_()

uint32_t QS_getTestProbe_

(

QSpyFunPtr const

api

)

get the test probe data for the given API

QS_onTestSetup()

void QS_onTestSetup

(

void

)

callback to setup a unit test inside the Target

QS_onTestTeardown()

void QS_onTestTeardown

(

void

)

callback to teardown after a unit test inside the Target

QS_onTestEvt()

void QS_onTestEvt

(

QEvt *

e

)

callback to "massage" the test event before dispatching/posting it

QS_onTestPost()

void QS_onTestPost	(	void const *	sender,
		QActive *	recipient,
		QEvt const *	e,
		bool	status
	)

callback to examine an event that is about to be posted

QS_onTestLoop()

void QS_onTestLoop

(

void

)

callback to run the test loop

QS_processTestEvts_()

void QS_processTestEvts_

(

void

)

internal function to process posted events during test

Variable Documentation

QS_priv_

QS_tx QS_priv_

extern

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

QS_testData

struct QS_TestData QS_testData

extern

QUTest data