QP/C  7.3.3
Real-Time Embedded Framework
Loading...
Searching...
No Matches
QS Class Reference

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)
 
QSTimeCtr QS_onGetTime (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)
 
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)

Description
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

QS user record group offsets for QS_GLB_FILTER()

Definition at line 224 of file qs.h.

◆ QSpyIdOffsets

QS ID offsets for QS_LOC_FILTER()

Definition at line 236 of file qs.h.

◆ QSpyIdGroups

QS ID groups for QS_LOC_FILTER()

Definition at line 246 of file qs.h.

◆ QS_QSpyObjKind

Kinds of objects used in QS-RX

Definition at line 959 of file qs.h.

◆ QS_OSpyObjComb

Object combinations for QS-RX

Definition at line 972 of file qs.h.

Member Function Documentation

◆ QS_initBuf()

QS::QS_initBuf ( uint8_t *const  sto,
uint_fast32_t const  stoSize 
)
static

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

◆ QS_getByte()

QS::QS_getByte ( void  )
static

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 95 of file qs.c.

◆ QS_getBlock()

QS::QS_getBlock ( uint16_t *const  pNbytes)
static

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

QS::QS_onFlush ( void  )
static

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

◆ QS_onGetTime()

QSTimeCtr QS_onGetTime ( void  )
static

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

QS::QS_rxInitBuf ( uint8_t *const  sto,
uint16_t const  stoSize 
)
static

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 134 of file qs_rx.c.

◆ QS_rxPut()

QS::QS_rxPut ( uint8_t const  b)
inlinestatic

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

QS::QS_rxParse ( void  )
static

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(), 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 169 of file qs_rx.c.

◆ QS_setCurrObj()

QS::QS_setCurrObj ( uint8_t const  obj_kind,
void *const  obj_ptr 
)
static

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 215 of file qs_rx.c.

◆ QS_rxGetNfree()

uint16_t QS_rxGetNfree ( void  )
static

Definition at line 233 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::QS_filt_
private

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 324 of file qs.h.

◆ QS_rxPriv_

QS::QS_rxPriv_
private

The instance of the QS-RX attributes (Singleton)

Description
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: