QP/C++  7.3.4
Real-Time Embedded Framework
Loading...
Searching...
No Matches
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()

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

Initialize the QS-TX data buffer

Description
This function should be called from QS::onStartup() to provide QS-TX (transmit channel) with the data buffer.
Parameters
[in]stopointer to the storage for the transmit buffer
[in]stoSizesize 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 66 of file qs.cpp.

◆ getByte()

QP::QS::getByte ( )
noexcept

Byte-oriented interface to the QS-TX data buffer

Description
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.cpp.

◆ getBlock()

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

Block-oriented interface to the QS-TX data buffer

Description
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]pNbytespointer 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 117 of file qs.cpp.

◆ doOutput()

void QP::QS::doOutput ( )

◆ onStartup()

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

◆ onCleanup()

void QP::QS::onCleanup ( )

◆ onFlush()

QP::QS::onFlush ( )

Flush the QS output buffer

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

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

Initialize the QS-RX data buffer

Description
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]stopointer to the storage for the QS-RX receive buffer
[in]stoSizesize 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 145 of file qs_rx.cpp.

◆ rxPut()

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

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

Parameters
[in]bdata byte to insert into the QS-RX receive buffer
Description
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()

QP::QS::rxParse ( )

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

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

◆ setCurrObj()

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

Set the "current object" inside the Target

Parameters
[in]obj_kindkind 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_ptrpointer to the object to set as "current"
Description
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 224 of file qs_rx.cpp.

◆ rxGetNfree()

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

Definition at line 241 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 163 of file qutest.cpp.

Variable Documentation

◆ filt_

QP::QS::filt_

The instance of the QS-TX filters (Singleton)

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