qs_dummy.h File Reference

Go to the source code of this file.

Classes
struct	QS_TProbe
	QUTest Test-Probe attributes. More...

Macros
#define	QS_INIT(arg_)   ((uint8_t)1U)
#define	QS_EXIT()   ((void)0)
#define	QS_DUMP()   ((void)0)
#define	QS_GLB_FILTER(rec_)   ((void)0)
#define	QS_LOC_FILTER(qsId_)   ((void)0)
#define	QS_BEGIN_ID(rec_, qsId_)   if (false) {
#define	QS_END()   }
#define	QS_BEGIN_INCRIT(rec_, qsId_)   if (false) {
#define	QS_END_INCRIT()   }
#define	QS_I8(width_, data_)   ((void)0)
#define	QS_U8(width_, data_)   ((void)0)
#define	QS_I16(width_, data_)   ((void)0)
#define	QS_U16(width_, data_)   ((void)0)
#define	QS_I32(width_, data_)   ((void)0)
#define	QS_U32(width_, data_)   ((void)0)
#define	QS_F32(width_, data_)   ((void)0)
#define	QS_F64(width_, data_)   ((void)0)
#define	QS_I64(width_, data_)   ((void)0)
#define	QS_U64(width_, data_)   ((void)0)
#define	QS_ENUM(group_, value_)   ((void)0)
#define	QS_STR(str_)   ((void)0)
#define	QS_MEM(mem_, size_)   ((void)0)
#define	QS_SIG(sig_, obj_)   ((void)0)
#define	QS_OBJ(obj_)   ((void)0)
#define	QS_FUN(fun_)   ((void)0)
#define	QS_SIG_DICTIONARY(sig_, obj_)   ((void)0)
#define	QS_OBJ_DICTIONARY(obj_)   ((void)0)
#define	QS_OBJ_ARR_DICTIONARY(obj_, idx_)   ((void)0)
#define	QS_FUN_DICTIONARY(fun_)   ((void)0)
#define	QS_USR_DICTIONARY(rec_)   ((void)0)
#define	QS_ENUM_DICTIONARY(value_, group_)   ((void)0)
#define	QS_ASSERTION(module_, loc_, delay_)   ((void)0)
#define	QS_FLUSH()   ((void)0)
#define	QS_TEST_PROBE_DEF(fun_)
#define	QS_TEST_PROBE(code_)
#define	QS_TEST_PROBE_ID(id_, code_)
#define	QS_TEST_PAUSE()   ((void)0)
#define	QS_OUTPUT()   ((void)0)
#define	QS_RX_INPUT()   ((void)0)
#define	QS_RX_PUT(b_)   ((void)0)
#define	QS_ONLY(code_)   ((void)0)
#define	QS_BEGIN_PRE(rec_, qsId_)   if (false) {
#define	QS_END_PRE()   }
#define	QS_U8_PRE(data_)   ((void)0)
#define	QS_2U8_PRE(data1_, data2_)   ((void)0)
#define	QS_U16_PRE(data_)   ((void)0)
#define	QS_U32_PRE(data_)   ((void)0)
#define	QS_TIME_PRE()   ((void)0)
#define	QS_SIG_PRE(sig_)   ((void)0)
#define	QS_EVS_PRE(size_)   ((void)0)
#define	QS_OBJ_PRE(obj_)   ((void)0)
#define	QS_FUN_PRE(fun_)   ((void)0)
#define	QS_EQC_PRE(ctr_)   ((void)0)
#define	QS_MPC_PRE(ctr_)   ((void)0)
#define	QS_MPS_PRE(size_)   ((void)0)
#define	QS_TEC_PRE(ctr_)   ((void)0)
#define	QS_CRIT_STAT
#define	QS_CRIT_ENTRY()   ((void)0)
#define	QS_CRIT_EXIT()   ((void)0)
#define	QS_MEM_SYS()   ((void)0)
#define	QS_MEM_APP()   ((void)0)
#define	QS_TR_CRIT_ENTRY()   ((void)0)
#define	QS_TR_CRIT_EXIT()   ((void)0)
#define	QS_TR_ISR_ENTRY(isrnest_, prio_)   ((void)0)
#define	QS_TR_ISR_EXIT(isrnest_, prio_)   ((void)0)

Typedefs
typedef uint32_t	QSTimeCtr
	Unsigned integer type for QS timestamps.

Functions
void	QS_initBuf (uint8_t *const sto, uint_fast32_t const stoSize)
uint16_t	QS_getByte (void)
uint8_t const *	QS_getBlock (uint16_t *const pNbytes)
void	QS_doOutput (void)
uint8_t	QS_onStartup (void const *arg)
void	QS_onCleanup (void)
void	QS_onFlush (void)
	Flush the QS output buffer.
QSTimeCtr	QS_onGetTime (void)
	Return the current timestamp for QS trace records.
void	QS_rxInitBuf (uint8_t *const sto, uint16_t const stoSize)
void	QS_rxParse (void)
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)

Macro Definition Documentation

QS_INIT

#define QS_INIT

(

arg_

)

((uint8_t)1U)

Definition at line 41 of file qs_dummy.h.

QS_EXIT

#define QS_EXIT

(

)

((void)0)

Definition at line 42 of file qs_dummy.h.

QS_DUMP

#define QS_DUMP

(

)

((void)0)

Definition at line 43 of file qs_dummy.h.

QS_GLB_FILTER

#define QS_GLB_FILTER

(

rec_

)

((void)0)

Definition at line 44 of file qs_dummy.h.

QS_LOC_FILTER

#define QS_LOC_FILTER

(

qsId_

)

((void)0)

Definition at line 45 of file qs_dummy.h.

QS_BEGIN_ID

#define QS_BEGIN_ID	(		rec_,
			qsId_ )   if (false) {

Definition at line 47 of file qs_dummy.h.

QS_END

#define QS_END

(

)

}

Definition at line 48 of file qs_dummy.h.

QS_BEGIN_INCRIT

#define QS_BEGIN_INCRIT	(		rec_,
			qsId_ )   if (false) {

Definition at line 49 of file qs_dummy.h.

QS_END_INCRIT

#define QS_END_INCRIT

(

)

}

Definition at line 50 of file qs_dummy.h.

QS_I8

#define QS_I8	(		width_,
			data_ )   ((void)0)

Definition at line 52 of file qs_dummy.h.

QS_U8

#define QS_U8	(		width_,
			data_ )   ((void)0)

Definition at line 53 of file qs_dummy.h.

QS_I16

#define QS_I16	(		width_,
			data_ )   ((void)0)

Definition at line 54 of file qs_dummy.h.

QS_U16

#define QS_U16	(		width_,
			data_ )   ((void)0)

Definition at line 55 of file qs_dummy.h.

QS_I32

#define QS_I32	(		width_,
			data_ )   ((void)0)

Definition at line 56 of file qs_dummy.h.

QS_U32

#define QS_U32	(		width_,
			data_ )   ((void)0)

Definition at line 57 of file qs_dummy.h.

QS_F32

#define QS_F32	(		width_,
			data_ )   ((void)0)

Definition at line 58 of file qs_dummy.h.

QS_F64

#define QS_F64	(		width_,
			data_ )   ((void)0)

Definition at line 59 of file qs_dummy.h.

QS_I64

#define QS_I64	(		width_,
			data_ )   ((void)0)

Definition at line 60 of file qs_dummy.h.

QS_U64

#define QS_U64	(		width_,
			data_ )   ((void)0)

Definition at line 61 of file qs_dummy.h.

QS_ENUM

#define QS_ENUM	(		group_,
			value_ )   ((void)0)

Definition at line 62 of file qs_dummy.h.

QS_STR

#define QS_STR

(

str_

)

((void)0)

Definition at line 63 of file qs_dummy.h.

QS_MEM

#define QS_MEM	(		mem_,
			size_ )   ((void)0)

Definition at line 64 of file qs_dummy.h.

QS_SIG

#define QS_SIG	(		sig_,
			obj_ )   ((void)0)

Definition at line 65 of file qs_dummy.h.

QS_OBJ

#define QS_OBJ

(

obj_

)

((void)0)

Definition at line 66 of file qs_dummy.h.

QS_FUN

#define QS_FUN

(

fun_

)

((void)0)

Definition at line 67 of file qs_dummy.h.

QS_SIG_DICTIONARY

#define QS_SIG_DICTIONARY	(		sig_,
			obj_ )   ((void)0)

Definition at line 69 of file qs_dummy.h.

QS_OBJ_DICTIONARY

#define QS_OBJ_DICTIONARY

(

obj_

)

((void)0)

Definition at line 70 of file qs_dummy.h.

QS_OBJ_ARR_DICTIONARY

#define QS_OBJ_ARR_DICTIONARY	(		obj_,
			idx_ )   ((void)0)

Definition at line 71 of file qs_dummy.h.

QS_FUN_DICTIONARY

#define QS_FUN_DICTIONARY

(

fun_

)

((void)0)

Definition at line 72 of file qs_dummy.h.

QS_USR_DICTIONARY

#define QS_USR_DICTIONARY

(

rec_

)

((void)0)

Definition at line 73 of file qs_dummy.h.

QS_ENUM_DICTIONARY

#define QS_ENUM_DICTIONARY	(		value_,
			group_ )   ((void)0)

Definition at line 74 of file qs_dummy.h.

QS_ASSERTION

#define QS_ASSERTION	(		module_,
			loc_,
			delay_ )   ((void)0)

Definition at line 75 of file qs_dummy.h.

QS_FLUSH

#define QS_FLUSH

(

)

((void)0)

Definition at line 76 of file qs_dummy.h.

QS_TEST_PROBE_DEF

#define QS_TEST_PROBE_DEF

(

fun_

)

QS macro to define the Test-Probe for a given fun_

Backward Traceability

• DVP_QS_MC4_R11_01
• DVP_QS_MC4_R15_05
• DVP_QS_PCLP_823

Definition at line 78 of file qs_dummy.h.

QS_TEST_PROBE

#define QS_TEST_PROBE

(

code_

)

Definition at line 79 of file qs_dummy.h.

QS_TEST_PROBE_ID

#define QS_TEST_PROBE_ID	(		id_,
			code_ )

QS_TEST_PROBE QS macro to apply a Test-Probe

Backward Traceability

• DVR_QS_MC4_R11_05

QS macro to apply a Test-Probe

Definition at line 80 of file qs_dummy.h.

QS_TEST_PAUSE

#define QS_TEST_PAUSE

(

)

((void)0)

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

Definition at line 81 of file qs_dummy.h.

QS_OUTPUT

#define QS_OUTPUT

(

)

((void)0)

Definition at line 83 of file qs_dummy.h.

QS_RX_INPUT

#define QS_RX_INPUT

(

)

((void)0)

Definition at line 84 of file qs_dummy.h.

QS_RX_PUT

#define QS_RX_PUT

(

b_

)

((void)0)

Macro to call QS_rxPut() when Q_SPY is defined (resolves to nothing when Q_SPY is not defined)

Definition at line 85 of file qs_dummy.h.

QS_ONLY

#define QS_ONLY

(

code_

)

((void)0)

Definition at line 86 of file qs_dummy.h.

QS_BEGIN_PRE

#define QS_BEGIN_PRE	(		rec_,
			qsId_ )   if (false) {

Definition at line 141 of file qs_dummy.h.

QS_END_PRE

#define QS_END_PRE

(

)

}

Definition at line 142 of file qs_dummy.h.

QS_U8_PRE

#define QS_U8_PRE

(

data_

)

((void)0)

Definition at line 143 of file qs_dummy.h.

QS_2U8_PRE

#define QS_2U8_PRE	(		data1_,
			data2_ )   ((void)0)

Definition at line 144 of file qs_dummy.h.

QS_U16_PRE

#define QS_U16_PRE

(

data_

)

((void)0)

Definition at line 145 of file qs_dummy.h.

QS_U32_PRE

#define QS_U32_PRE

(

data_

)

((void)0)

Definition at line 146 of file qs_dummy.h.

QS_TIME_PRE

#define QS_TIME_PRE

(

)

((void)0)

Definition at line 147 of file qs_dummy.h.

QS_SIG_PRE

#define QS_SIG_PRE

(

sig_

)

((void)0)

Definition at line 148 of file qs_dummy.h.

QS_EVS_PRE

#define QS_EVS_PRE

(

size_

)

((void)0)

Definition at line 149 of file qs_dummy.h.

QS_OBJ_PRE

#define QS_OBJ_PRE

(

obj_

)

((void)0)

Definition at line 150 of file qs_dummy.h.

QS_FUN_PRE

#define QS_FUN_PRE

(

fun_

)

((void)0)

Definition at line 151 of file qs_dummy.h.

QS_EQC_PRE

#define QS_EQC_PRE

(

ctr_

)

((void)0)

Definition at line 152 of file qs_dummy.h.

QS_MPC_PRE

#define QS_MPC_PRE

(

ctr_

)

((void)0)

Definition at line 153 of file qs_dummy.h.

QS_MPS_PRE

#define QS_MPS_PRE

(

size_

)

((void)0)

Definition at line 154 of file qs_dummy.h.

QS_TEC_PRE

#define QS_TEC_PRE

(

ctr_

)

((void)0)

Definition at line 155 of file qs_dummy.h.

QS_CRIT_STAT

#define QS_CRIT_STAT

Internal QS macro for defining the critical section status

Definition at line 157 of file qs_dummy.h.

QS_CRIT_ENTRY

#define QS_CRIT_ENTRY

(

)

((void)0)

Internal macro for entering a critical section

Definition at line 158 of file qs_dummy.h.

QS_CRIT_EXIT

#define QS_CRIT_EXIT

(

)

((void)0)

Internal macro for exiting a critical section

Definition at line 159 of file qs_dummy.h.

QS_MEM_SYS

#define QS_MEM_SYS

(

)

((void)0)

Internal macro for configuring MPU for System access

Definition at line 161 of file qs_dummy.h.

QS_MEM_APP

#define QS_MEM_APP

(

)

((void)0)

Internal macro for configuring MPU for Application access

Definition at line 162 of file qs_dummy.h.

QS_TR_CRIT_ENTRY

#define QS_TR_CRIT_ENTRY

(

)

((void)0)

Definition at line 164 of file qs_dummy.h.

QS_TR_CRIT_EXIT

#define QS_TR_CRIT_EXIT

(

)

((void)0)

Definition at line 165 of file qs_dummy.h.

QS_TR_ISR_ENTRY

#define QS_TR_ISR_ENTRY	(		isrnest_,
			prio_ )   ((void)0)

Definition at line 166 of file qs_dummy.h.

QS_TR_ISR_EXIT

#define QS_TR_ISR_EXIT	(		isrnest_,
			prio_ )   ((void)0)

Definition at line 167 of file qs_dummy.h.

Typedef Documentation

QSTimeCtr

typedef uint32_t QSTimeCtr

Unsigned integer type for QS timestamps.

Details

The dynamic range of QSTimeCtr is configurable by the macro QS_TIME_SIZE, which can take values 1-byte (256 counts), 2-bytes (64K counts) and 4-bytes (4G counts).

See also

• QS_TIME_SIZE
• QS::QS_onGetTime()

Definition at line 95 of file qs_dummy.h.

Function Documentation

QS_initBuf()

void QS_initBuf	(	uint8_t *const	sto,
		uint_fast32_t const	stoSize )

Initialize the QS-TX data buffer

Details

This function should be called from QS_onStartup() to provide QS-TX (transmit channel) with the data buffer.

Parameters

[in]	sto	pointer to the storage for the transmit buffer
[in]	stoSize	size in [bytes] of the storage buffer. Currently the size of the QS buffer cannot exceed 64KB.

Remarks

QS can work with quite small data buffers (e.g., 1024 bytes), but you will start losing data (tracing information) 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.

Note

If the data output rate cannot keep up with the production rate, QS will start overwriting the older data with newer data. This is consistent with the "last-is-best" QS policy. The QS data protocol sequence counters and check sums on each QS-record allow the QSPY host utility to easily detect any data loss. (See also functions QS_getByte() and QS_getBlock() for performing QS-TX output.)

QS_getByte()

uint16_t QS_getByte

(

void

)

Byte-oriented interface to the QS-TX data buffer

Details

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

Attention

QS_getByte() should be called from within a critical section (interrupts disabled).

QS_getBlock()

uint8_t const * QS_getBlock

(

uint16_t *const

pNbytes

)

Block-oriented interface to the QS-TX data buffer

Details

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

Parameters

[in,out]

pNbytes

pointer to the number of bytes to send. On input, pNbytes specifies the maximum number of bytes that the function can provide. On output, pNbytes contains the actual number of bytes available.

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.

Attention

QS_getBlock() should be called from within a critical section (interrupts disabled).

QS_doOutput()

void QS_doOutput

(

void

)

QS_onStartup()

uint8_t QS_onStartup

(

void const *

arg

)

QS_onCleanup()

void QS_onCleanup

(

void

)

QS_onFlush()

void QS_onFlush

(

void

)

Flush the QS output buffer.

Details

This function is used at the end of QS dictionaries and other QS records that need to be transmitted immediately. QS_onFlush() is typically used only during the initial transient and should NOT be used thereafter because it is busy-waiting for the transmission of the data.

Attention

Typically, no critical section (or interrupt disabling) should be used in QS_onFlush() to avoid nesting of critical sections in case QS_onFlush() is called from Q_onError().

QS_onGetTime()

QSTimeCtr QS_onGetTime

(

void

)

Return the current timestamp for QS trace records.

Details

This function is defined in the application and is called for every QS trace record that requires a timestamp. The function shall return the current timestamp as an unsigned integer of the type QSTimeCtr. The dynamic range of QSTimeCtr is configurable by the macro QS_TIME_SIZE, which can take values 1-byte (256 counts), 2-bytes (64K counts) and 4-bytes (4G counts).

As this is a callback from QS to the application, the properties of the timestamp depend entirely on the application. Typically, the function requires a hardware timer with the following properties:

• sufficiently fine granularity (typically sub-microsecond)
• natural warp-around by the end of the dynamic range (e.g., 0xFFFFFFFF -> 0 for a 4-byte timestamp)

Attention

The QS_onGetTime() function is called within a critical section.

Example

The following code implements QS_onGetTime() with a free-running, 32-bit timer in STM32U545 MCU:

QSTimeCtr QS_onGetTime(void) {
    return TIM5->CNT; // 32-bit Timer5 count
}
 
// where Timer5 is configured inside QS_onStartup() as follows:
uint8_t QS_onStartup(void const *arg) {
    . . .
    // configure Timer5 for delivering QS time-stamp...........................
    SET_BIT(RCC->APB1ENR1, RCC_APB1ENR1_TIM5EN);
 
    uint32_t tmp = TIM5->CR1;
    MODIFY_REG(tmp, TIM_CR1_DIR | TIM_CR1_CMS, 0U); // counter-mode=Up
    MODIFY_REG(tmp, TIM_CR1_CKD, 0U); // clock-division=1
    WRITE_REG(TIM5->CR1, tmp);
 
    WRITE_REG(TIM5->ARR, 0xFFFFFFFFU); // auto-reload
    WRITE_REG(TIM5->PSC, 0U); // prescaler=1
    SET_BIT(TIM5->EGR, TIM_EGR_UG); // update event to reload prescaler
 
    CLEAR_BIT(TIM5->CR1, TIM_CR1_ARPE); // disable ARR preload
    MODIFY_REG(TIM5->SMCR, TIM_SMCR_SMS | TIM_SMCR_ECE, 0U); // internal clock
    MODIFY_REG(TIM5->CR2, TIM_CR2_MMS, 0U); // reset timer synchronization
    CLEAR_BIT(TIM5->SMCR, TIM_SMCR_MSM); // disable master-slave
 
    // enable Timer5 to start time stamp
    SET_BIT(TIM5->CR1, TIM_CR1_CEN);
    . . .
}

See also

• QS_TIME_SIZE
• QSTimeCtr

QS_rxInitBuf()

void QS_rxInitBuf	(	uint8_t *const	sto,
		uint16_t const	stoSize )

Initialize the QS-RX data buffer

Details

This function should be called from QS_onStartup() to provide QS-RX (receive channel) with the data buffer. The QS-RX channel requires the initialization of the QS-TX channel (see QS_initBuf()). The QS-RX channel is optional and does not need to be initialized when not needed.

Parameters

[in]	sto	pointer to the storage for the QS-RX receive buffer
[in]	stoSize	size in [bytes] of the storage buffer

Remarks

QS can work with quite small data buffers (e.g., 128 bytes), but you will start losing data (commands to the target) if the buffer is too small for the commands that are being sent. The right size of the buffer depends on the commands and the data input rate.

Note

If the QS-RX processing cannot keep up with the input rate, QS will start overwriting the older data with newer data. The QS data protocol sequence counters and check sums on each QS-record allow the QS-RX parser (see QS_rxParse()) to detect any data loss, but the corrupted commands won't be executed.

QS_rxParse()

void QS_rxParse

(

void

)

Parse and process QS-RX (receive channel) data bytes

Details

The application must call this function repeatedly to process the incoming commands from the QS-RX input channel. The frequency of the calls must be high enough to avoid overflowing the QS-RX input buffer (see QS_rxInitBuf(), QS_rxPut(), and QS_RX_PUT()).

Note

This function should be called from a single thread of execution. An ideal place to call this function is the idle-thread. Also, this function must be called outside a critical section (with interrupts enabled).

QS_onTestSetup()

void QS_onTestSetup

(

void

)

QS_onTestTeardown()

void QS_onTestTeardown

(

void

)

QS_onTestEvt()

void QS_onTestEvt

(

QEvt *

e

)

QS_onTestPost()

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

QS_onTestLoop()

void QS_onTestLoop

(

void

)