Software tracing instrumentation target-resident component. More...

#include <qs.hpp>

Classes
class	Attr
	Private attributes of the QS software tracing target-resident component (TX channel). More...
class	Filter
	QS type for output filters (global and local. More...

Public Types
enum class	QSResetAction : std::uint8_t { TARGET_NO_RESET , TARGET_RESET }
enum	ObjKind_old : std::uint8_t { SM_OBJ , AO_OBJ , MP_OBJ , EQ_OBJ , TE_OBJ , AP_OBJ , SM_AO_OBJ }

Static Public Member Functions
template<typename T_OUT, typename T_IN>
static T_OUT	force_cast (T_IN in)
static void	initBuf (std::uint8_t *const sto, std::uint_fast32_t const stoSize) noexcept
	Initialize the QS-TX data buffer.
static std::uint16_t	getByte () noexcept
static std::uint8_t const *	getBlock (std::uint16_t *const pNbytes) noexcept
static void	doOutput ()
static bool	onStartup (void const *arg)
static void	onCleanup ()
static void	onFlush ()
	Flush the QS output buffer.
static QSTimeCtr	onGetTime ()
	Return the current timestamp for QS trace records.
static void	rxInitBuf (std::uint8_t *const sto, std::uint16_t const stoSize) noexcept
static bool	rxPut (std::uint8_t const b) noexcept
static void	rxParse ()
	Parse and process QS-RX (receive channel) data bytes.
static void	rxParseBuf (std::uint16_t const len)
static bool	setCurrObj (std::uint8_t const obj_kind, void *const obj_ptr) noexcept
	Set the "current object" inside the Target.
static void *	getCurrObj (std::uint8_t const obj_kind) noexcept
static bool	setCurrId (std::uint8_t const obj_kind, std::uint8_t const obj_id) noexcept
	Set the "current object" inside the Target.
static std::uint8_t	getCurrId (std::uint8_t const obj_kind) noexcept
static std::uint16_t	rxGetFree () noexcept
static void	doInput ()
static void	onReset ()
static void	onCommand (std::uint8_t cmdId, std::uint32_t param1, std::uint32_t param2, std::uint32_t param3)
static void	target_info_pre_ (QSResetAction const act)
static void	onTestSetup ()
static void	onTestTeardown ()
static void	onTestEvt (QEvt *e)
static void	onTestPost (void const sender, QActive recipient, QEvt const *e, bool status)
static void	onTestLoop ()

Static Public Attributes
static Attr	priv_
static Filter	filt_
static RxAttr &	rxPriv_ = l_rxPriv_

Detailed Description

Software tracing instrumentation target-resident component.

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

Definition at line 459 of file qs.hpp.

Member Enumeration Documentation

◆ QSResetAction

enum class QP::QS::QSResetAction : std::uint8_t

strong

Enumerator
TARGET_NO_RESET
TARGET_RESET

Definition at line 616 of file qs.hpp.

◆ ObjKind_old

enum QP::QS::ObjKind_old : std::uint8_t

Deprecated: instead use: QP::QS_ObjKind

Enumerator
SM_OBJ
AO_OBJ
MP_OBJ
EQ_OBJ
TE_OBJ
AP_OBJ
SM_AO_OBJ

Definition at line 623 of file qs.hpp.

Member Function Documentation

◆ force_cast()

template<typename T_OUT, typename T_IN>

T_OUT QP::QS::force_cast ( T_IN in )

inlinestatic

Definition at line 565 of file qs.hpp.

◆ initBuf()

void QP::QS::initBuf	(	std::uint8_t *const	sto,
		std::uint_fast32_t const	stoSize )

staticnoexcept

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 relatively 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 checksums on each QS-record allow the QSPY host utility to detect any data loss easily. (See also functions QS::getByte() and QS::getBlock() for performing QS-TX output.)

◆ getByte()

std::uint16_t QP::QS::getByte ( )

staticnoexcept

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

◆ getBlock()

std::uint8_t const * QP::QS::getBlock ( std::uint16_t *const pNbytes )

staticnoexcept

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 a pointer to the contiguous block of data and sets the value pointed to by pNbytes to the # available bytes. If data is NOT available at the time the function is called, the function returns nullptr and sets the value pointed to by pNbytes to zero.

Note: As long as QS_getBlock() returns non-NULL, the QS transmit (QS-TX) buffer is NOT empty. The function might need to be called multiple times until it returns NULL, which means that the QS transmit (QS-TX) buffer becomes empty at this time.

Attention: QS::getBlock() should be called from within a critical section (interrupts disabled).

◆ doOutput()

void QP::QS::doOutput ( )

static

◆ onStartup()

bool QP::QS::onStartup ( void const * arg )

static

◆ onCleanup()

void QP::QS::onCleanup ( )

static

◆ onFlush()

void QP::QS::onFlush ( )

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

◆ onGetTime()

QSTimeCtr QP::QS::onGetTime ( )

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 QS::QSTimeCtr. The dynamic range of QS::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() {
    return TIM5->CNT; // 32-bit Timer5 count
}
 
// where Timer5 is configured inside QS_onStartup() as follows:
std::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

◆ rxInitBuf()

void QS::rxInitBuf	(	std::uint8_t *const	sto,
		std::uint16_t const	stoSize )

staticnoexcept

code_uid{QP::QS::QS_rxInitBuf(), 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 require initialization when not in use.

Parameters

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

Remarks: QS receive channel (QS-RX) can work with relatively 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 checksums on each QS-record enable the QS-RX parser (see QS::rxParse()) to detect any data loss; however, corrupted commands won't be executed.

Definition at line 212 of file qs_rx.cpp.

◆ rxPut()

bool QS::rxPut ( std::uint8_t const b )

staticnoexcept

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

Details
This function is called (typically from an ISR) to put a new incoming byte into the QS-RX input buffer.

Parameters

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

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

Definition at line 285 of file qs_rx.cpp.

◆ rxParse()

void QS::rxParse ( )

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

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 234 of file qs_rx.cpp.

◆ rxParseBuf()

void QS::rxParseBuf ( std::uint16_t const len )

static

Definition at line 279 of file qs_rx.cpp.

◆ setCurrObj()

bool QS::setCurrObj	(	std::uint8_t const	obj_kind,
		void *const	obj_ptr )

staticnoexcept

Set the "current object" inside the Target.

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.

Parameters

[in]	obj_kind	kind of "current object" to set. The possible values are: OBJ_SM // state machine object OBJ_AO // active object OBJ_MP // memory pool object OBJ_EQ // event queue object OBJ_TE // time event object OBJ_AP // generic Application-specific object
[in]	obj_ptr	pointer to the object to set as "current"

Definition at line 322 of file qs_rx.cpp.

◆ getCurrObj()

void * QS::getCurrObj ( std::uint8_t const obj_kind )

staticnoexcept

Definition at line 343 of file qs_rx.cpp.

◆ setCurrId()

bool QS::setCurrId	(	std::uint8_t const	obj_kind,
		std::uint8_t const	obj_id )

staticnoexcept

Set the "current object" inside the Target.

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.

Parameters

[in]	obj_kind	kind of "current object" to set. The possible values are: QS_OBJ_AO // active object QS_OBJ_EP // event pool object
[in]	obj_id	the "ID" of the object to set as "current". The example object IDs are: 1..64 // active object priorities (for QS_OBJ_AO) 1..QF_MAX_EPOOL // event pool numbers (for QS_OBJ_EP)

Definition at line 359 of file qs_rx.cpp.

◆ getCurrId()

std::uint8_t QS::getCurrId ( std::uint8_t const obj_kind )

staticnoexcept

Definition at line 379 of file qs_rx.cpp.

◆ rxGetFree()

std::uint16_t QS::rxGetFree ( )

staticnoexcept

Definition at line 302 of file qs_rx.cpp.

◆ doInput()

void QP::QS::doInput ( )

static

◆ onReset()

void QP::QS::onReset ( )

static

◆ onCommand()

void QP::QS::onCommand	(	std::uint8_t	cmdId,
		std::uint32_t	param1,
		std::uint32_t	param2,
		std::uint32_t	param3 )

static

◆ target_info_pre_()

void QP::QS::target_info_pre_ ( QSResetAction const act )

static

◆ onTestSetup()

void QP::QS::onTestSetup ( )

static

◆ onTestTeardown()

void QP::QS::onTestTeardown ( )

static

◆ onTestEvt()

void QP::QS::onTestEvt ( QEvt * e )

static

◆ onTestPost()

void QP::QS::onTestPost	(	void const *	sender,
		QActive *	recipient,
		QEvt const *	e,
		bool	status )

static

◆ onTestLoop()

void QP::QS::onTestLoop ( )

static

Member Data Documentation

◆ priv_

Attr QP::QS::priv_

static

Definition at line 473 of file qs.hpp.

◆ filt_

Filter QP::QS::filt_

static

Definition at line 480 of file qs.hpp.

◆ rxPriv_

RxAttr & QS::rxPriv_ = l_rxPriv_

static

Definition at line 591 of file qs.hpp.

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


QP/C++ 8.1.2 Real-Time Event Framework

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ QSResetAction

◆ ObjKind_old

Member Function Documentation

◆ force_cast()

◆ initBuf()

◆ getByte()

◆ getBlock()

◆ doOutput()

◆ onStartup()

◆ onCleanup()

◆ onFlush()

◆ onGetTime()

◆ rxInitBuf()

◆ rxPut()

◆ rxParse()

◆ rxParseBuf()

◆ setCurrObj()

◆ getCurrObj()

◆ setCurrId()

◆ getCurrId()

◆ rxGetFree()

◆ doInput()

◆ onReset()

◆ onCommand()

◆ target_info_pre_()

◆ onTestSetup()

◆ onTestTeardown()

◆ onTestEvt()

◆ onTestPost()

◆ onTestLoop()

Member Data Documentation

◆ priv_

◆ filt_

◆ rxPriv_