QP::QS Namespace Reference

QP/Spy software tracing (target-resident components) More...

Classes
class	Filter
	QS type for output filters (global and local) More...
struct	TProbe
	QUTest Test-Probe attributes. More...

Enumerations
enum	preType : std::uint8_t {   I8_ENUM_T , U8_T , I16_T , U16_T ,   I32_T , U32_T , F32_T , F64_T ,   STR_T , MEM_T , SIG_T , OBJ_T ,   FUN_T , I64_T , U64_T }
	Enumerates data elements for app-specific trace records. More...
enum	QSpyObjKind : std::uint8_t {   SM_OBJ , AO_OBJ , MP_OBJ , EQ_OBJ ,   TE_OBJ , AP_OBJ , MAX_OBJ }
	Kinds of objects used QS-RX. More...
enum	OSpyObjCombnation : std::uint8_t { SM_AO_OBJ = MAX_OBJ }
	Object combinations for QS-RX. More...

Functions
template<typename T_OUT , typename T_IN >
T_OUT	force_cast (T_IN in)
void	initBuf (std::uint8_t *const sto, std::uint_fast32_t const stoSize) noexcept
std::uint16_t	getByte () noexcept
std::uint8_t const *	getBlock (std::uint16_t *const pNbytes) noexcept
void	doOutput ()
bool	onStartup (void const *arg)
void	onCleanup ()
void	onFlush ()
QSTimeCtr	onGetTime ()
void	onTestSetup ()
void	onTestTeardown ()
void	onTestEvt (QEvt *e)
void	onTestPost (void const *sender, QActive *recipient, QEvt const *e, bool status)
void	onTestLoop ()
void	rxInitBuf (std::uint8_t *const sto, std::uint16_t const stoSize) noexcept
bool	rxPut (std::uint8_t const b) noexcept
void	rxParse ()
void	setCurrObj (std::uint8_t const obj_kind, void *const obj_ptr)
std::uint16_t	rxGetNfree () noexcept
void	doInput ()
void	onReset ()
void	onCommand (std::uint8_t cmdId, std::uint32_t param1, std::uint32_t param2, std::uint32_t param3)
void	processTestEvts_ ()

Variables
Filter	filt_

Detailed Description

QP/Spy software tracing (target-resident components)

Enumeration Type Documentation

preType

enum QP::QS::preType : std::uint8_t

Enumerates data elements for app-specific trace records.

Enumerator
I8_ENUM_T	signed 8-bit integer or enum format
U8_T	unsigned 8-bit integer format
I16_T	signed 16-bit integer format
U16_T	unsigned 16-bit integer format
I32_T	signed 32-bit integer format
U32_T	unsigned 32-bit integer format
F32_T	32-bit floating point format
F64_T	64-bit floating point format
STR_T	zero-terminated ASCII string format
MEM_T	up to 255-bytes memory block format
SIG_T	event signal format
OBJ_T	object pointer format
FUN_T	function pointer format
I64_T	signed 64-bit integer format
U64_T	unsigned 64-bit integer format

Definition at line 695 of file qs.hpp.

QSpyObjKind

enum QP::QS::QSpyObjKind : std::uint8_t

Kinds of objects used QS-RX.

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 990 of file qs.hpp.

OSpyObjCombnation

enum QP::QS::OSpyObjCombnation : std::uint8_t

Object combinations for QS-RX.

Enumerator
SM_AO_OBJ	combination of SM and AO

Definition at line 1002 of file qs.hpp.

Function Documentation

force_cast()

template<typename T_OUT , typename T_IN >

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

inline

Definition at line 715 of file qs.hpp.

initBuf()

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

noexcept

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

Definition at line 65 of file qs.cpp.

getByte()

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

noexcept

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 93 of file qs.cpp.

getBlock()

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

noexcept

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 116 of file qs.cpp.

doOutput()

void QP::QS::doOutput

(

)

onStartup()

bool QP::QS::onStartup

(

void const *

arg

)

onCleanup()

void QP::QS::onCleanup

(

)

onFlush()

void QP::QS::onFlush

(

)

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

(

)

onTestSetup()

void QP::QS::onTestSetup

(

)

onTestTeardown()

void QP::QS::onTestTeardown

(

)

onTestEvt()

void QP::QS::onTestEvt

(

QEvt *

e

)

onTestPost()

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

onTestLoop()

void QP::QS::onTestLoop

(

)

rxInitBuf()

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

noexcept

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

rxPut()

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

inlinenoexcept

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.

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 1012 of file qs.hpp.

rxParse()

void QP::QS::rxParse

(

)

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

setCurrObj()

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

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

rxGetNfree()

std::uint16_t QP::QS::rxGetNfree ( )

noexcept

Definition at line 240 of file qs_rx.cpp.

doInput()

void QP::QS::doInput

(

)

onReset()

void QP::QS::onReset

(

)

onCommand()

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

processTestEvts_()

void QP::QS::processTestEvts_

(

)

Definition at line 162 of file qutest.cpp.

Variable Documentation

filt_

Filter QP::QS::filt_

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 162 of file qs.cpp.