Software tracing instrumentation, target-resident component (QS namespace emulated as a "class" in C) More...

#include "qs.h"

Public Types
enum	QSpyPre

enum	QSpyGroups

enum	QSpyUserOffsets

enum	QSpyIdOffsets

enum	QSpyIdGroups

enum	QS_QSpyObjKind

enum	QS_OSpyObjComb

Static Public Member 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_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_rxInitBuf (uint8_t *const sto, uint16_t const stoSize)

static bool	QS_rxPut (uint8_t const b)

void	QS_rxParse (void)

void	QS_setCurrObj (uint8_t const obj_kind, void *const obj_ptr)

uint16_t	QS_rxGetNfree (void)

void	QS_doInput (void)

void	QS_onReset (void)

void	QS_onCommand (uint8_t cmdId, uint32_t param1, uint32_t param2, uint32_t param3)

Static Private Member Functions
typedef void(*	QSpyFunPtr) (void)

Private Attributes
QS_Filter	QS_filt_

QS_RxAttr	QS_rxPriv_

Detailed Description

Software tracing instrumentation, target-resident component (QS namespace emulated as a "class" in C)

Details

This namespace groups together QP/Spy services for target-resident software tracing instrumentation.

Definition at line 68 of file qs.h.

Member Typedef Documentation

◆ QSpyFunPtr

typedef void(* QSpyFunPtr) (void)

staticprivate

Definition at line 290 of file qs.h.

Member Enumeration Documentation

◆ QSpyPre

enum QSpyPre

pre-defined QS record IDs

Definition at line 77 of file qs.h.

◆ QSpyGroups

enum QSpyGroups

QS-TX record groups for QS_GLB_FILTER()

Definition at line 202 of file qs.h.

◆ QSpyUserOffsets

enum QSpyUserOffsets

QS user record group offsets for QS_GLB_FILTER()

Definition at line 224 of file qs.h.

◆ QSpyIdOffsets

enum QSpyIdOffsets

QS ID offsets for QS_LOC_FILTER()

Definition at line 236 of file qs.h.

◆ QSpyIdGroups

enum QSpyIdGroups

QS ID groups for QS_LOC_FILTER()

Definition at line 246 of file qs.h.

◆ QS_QSpyObjKind

enum QS_QSpyObjKind

Kinds of objects used in QS-RX

Definition at line 959 of file qs.h.

◆ QS_OSpyObjComb

enum QS_OSpyObjComb

Object combinations for QS-RX

Definition at line 972 of file qs.h.

Member Function Documentation

◆ QS_initBuf()

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

static

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 )

static

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

Definition at line 94 of file qs.c.

◆ QS_getBlock()

uint8_t const * QS_getBlock ( uint16_t *const pNbytes )

static

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

Definition at line 115 of file qs.c.

◆ QS_doOutput()

void QS_doOutput ( void )

static

◆ QS_onStartup()

uint8_t QS_onStartup ( void const * arg )

static

◆ QS_onCleanup()

void QS_onCleanup ( void )

static

◆ QS_onFlush()

void QS_onFlush ( void )

static

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 )

static

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

void QS_onTestSetup ( void )

static

◆ QS_onTestTeardown()

void QS_onTestTeardown ( void )

static

◆ QS_onTestEvt()

void QS_onTestEvt ( QEvt * e )

static

◆ QS_onTestPost()

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

static

◆ QS_onTestLoop()

void QS_onTestLoop ( void )

static

◆ QS_rxInitBuf()

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

static

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.

Definition at line 133 of file qs_rx.c.

◆ QS_rxPut()

static bool QS_rxPut ( uint8_t const b )

inlinestatic

Put a byte into the QS-RX (receive channel) input buffer

Parameters

[in] b data byte to insert into the QS-RX receive buffer

Details

This function is called (typically from an ISR) to put a new incoming byte into the QS-RX input buffer. Typically, this function is called by means of the macro QS_RX_PUT().

Attention: QS_rxPut() (QS_RX_PUT()) is designed to be called concurrently without disabling interrupts, even from a "kernel-unaware" ISR (typically UART receive ISR).

Definition at line 984 of file qs.h.

◆ QS_rxParse()

void QS_rxParse ( void )

static

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

Definition at line 168 of file qs_rx.c.

◆ QS_setCurrObj()

void QS_setCurrObj	(	uint8_t const	obj_kind,
		void *const	obj_ptr )

static

Set the "current object" inside the Target

Parameters

[in]	obj_kind	kind of "current object" to set The possible values are: 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
[in]	obj_ptr	pointer to the object to set as "current"

Details

This function sets the "current object" selected object kind inside the QS-RX target-resident component. This "current object" is subsequently used in all commands that pertain to that object.

Definition at line 214 of file qs_rx.c.

◆ QS_rxGetNfree()

uint16_t QS_rxGetNfree ( void )

static

Definition at line 232 of file qs_rx.c.

◆ QS_doInput()

void QS_doInput ( void )

static

◆ QS_onReset()

void QS_onReset ( void )

static

◆ QS_onCommand()

void QS_onCommand	(	uint8_t	cmdId,
		uint32_t	param1,
		uint32_t	param2,
		uint32_t	param3 )

static

Member Data Documentation

◆ QS_filt_

QS_Filter QS_filt_

private

The instance of the QS-TX filters (Singleton)

Details

The QS filters are exposed as a separate object because when Memory Isolation is used, the QS filters must be accessible in their own memory region.

Definition at line 324 of file qs.h.

◆ QS_rxPriv_

QS_RxAttr QS_rxPriv_

private

The instance of the QS-RX attributes (Singleton)

Details

The QS-RX attributes are exposed as a separate object because when Memory Isolation is used, the QS-RX attributes must be accessible in their own memory region.

Definition at line 950 of file qs.h.

The documentation for this class was generated from the following files:

Public Types

Static Public Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ QSpyFunPtr

Member Enumeration Documentation

◆ QSpyPre

◆ QSpyGroups

◆ QSpyUserOffsets

◆ QSpyIdOffsets

◆ QSpyIdGroups

◆ QS_QSpyObjKind

◆ QS_OSpyObjComb

Member Function Documentation

◆ QS_initBuf()

◆ QS_getByte()

◆ QS_getBlock()

◆ QS_doOutput()

◆ QS_onStartup()

◆ QS_onCleanup()

◆ QS_onFlush()

◆ QS_onGetTime()

◆ QS_onTestSetup()

◆ QS_onTestTeardown()

◆ QS_onTestEvt()

◆ QS_onTestPost()

◆ QS_onTestLoop()

◆ QS_rxInitBuf()

◆ QS_rxPut()

◆ QS_rxParse()

◆ QS_setCurrObj()

◆ QS_rxGetNfree()

◆ QS_doInput()

◆ QS_onReset()

◆ QS_onCommand()

Member Data Documentation

◆ QS_filt_

◆ QS_rxPriv_