QP/C++  7.0.1
Real-Time Embedded Framework
QS Class Reference

QS software tracing facilities for output (QS-TX) More...

#include <qs.hpp>

Public Types

enum  QSType : std::uint8_t {
  I8_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 , HEX_FMT
}
 Enumerates data formats recognized by QS. More...
 
enum  QSpyObjKind : std::uint8_t {
  SM_OBJ , AO_OBJ , MP_OBJ , EQ_OBJ ,
  TE_OBJ , AP_OBJ , MAX_OBJ
}
 Kinds of objects used in QS. More...
 
enum  OSpyObjCombnation : std::uint8_t { SM_AO_OBJ = MAX_OBJ }
 

Static Public Member Functions

static void initBuf (std::uint8_t *const sto, std::uint_fast16_t const stoSize) noexcept
 Initialize the QS data buffer. More...
 
static void glbFilter_ (std::int_fast16_t const filter) noexcept
 Set/clear the global Filter for a given QS record or a group of records. More...
 
static void locFilter_ (std::int_fast16_t const filter) noexcept
 Set/clear the local Filter for a given object-id or a group of object-ids. More...
 
static void beginRec_ (std::uint_fast8_t const rec) noexcept
 Mark the begin of a QS record rec More...
 
static void endRec_ (void) noexcept
 Mark the end of a QS record rec More...
 
static void u8_raw_ (std::uint8_t const d) noexcept
 output std::uint8_t data element without format information More...
 
static void u8u8_raw_ (std::uint8_t const d1, std::uint8_t const d2) noexcept
 output two std::uint8_t data elements without format information More...
 
static void u16_raw_ (std::uint16_t d) noexcept
 Output std::uint16_t data element without format information. More...
 
static void u32_raw_ (std::uint32_t d) noexcept
 Output std::uint32_t data element without format information. More...
 
static void obj_raw_ (void const *const obj) noexcept
 Output obj pointer data element without format information. More...
 
static void str_raw_ (char const *s) noexcept
 Output zero-terminated ASCII string element without format information. More...
 
static void u8_fmt_ (std::uint8_t const format, std::uint8_t const d) noexcept
 Output std::uint8_t data element with format information. More...
 
static void u16_fmt_ (std::uint8_t format, std::uint16_t d) noexcept
 output std::uint16_t data element with format information More...
 
static void u32_fmt_ (std::uint8_t format, std::uint32_t d) noexcept
 Output std::uint32_t data element with format information. More...
 
static void f32_fmt_ (std::uint8_t format, float32_t const d) noexcept
 Output 32-bit floating point data element with format information. More...
 
static void f64_fmt_ (std::uint8_t format, float64_t const d) noexcept
 Output 64-bit floating point data element with format information. More...
 
static void str_fmt_ (char const *s) noexcept
 Output zero-terminated ASCII string element with format information. More...
 
static void mem_fmt_ (std::uint8_t const *blk, std::uint8_t size) noexcept
 Output memory block of up to 255-bytes with format information. More...
 
static void u64_raw_ (std::uint64_t d) noexcept
 Output uint64_t data element without format information. More...
 
static void u64_fmt_ (std::uint8_t format, std::uint64_t d) noexcept
 Output uint64_t data element with format information. More...
 
static void sig_dict_pre_ (enum_t const sig, void const *const obj, char const *const name) noexcept
 Output signal dictionary record. More...
 
static void obj_dict_pre_ (void const *const obj, char const *const name) noexcept
 Output object dictionary record. More...
 
static void obj_arr_dict_pre_ (void const *const obj, std::uint_fast16_t const idx, char const *const name) noexcept
 Output predefined object-array dictionary record. More...
 
static void fun_dict_pre_ (void(*const fun)(void), char const *const name) noexcept
 Output function dictionary record. More...
 
static void usr_dict_pre_ (enum_t const rec, char const *const name) noexcept
 Output user dictionary record. More...
 
static void rxInitBuf (std::uint8_t *const sto, std::uint16_t const stoSize) noexcept
 Initialize the QS RX data buffer. More...
 
static void rxParse (void)
 Parse all bytes present in the QS RX data buffer. More...
 
static std::uint16_t rxGetNfree (void) noexcept
 Obtain the number of free bytes in the QS RX data buffer. More...
 
static bool rxPut (std::uint8_t const b) noexcept
 Put one byte into the QS RX lock-free buffer. More...
 
static void setCurrObj (std::uint8_t obj_kind, void *obj_ptr) noexcept
 Set the "current object" in the Target. More...
 
static void queryCurrObj (std::uint8_t obj_kind) noexcept
 Query the "current object" in the Target. More...
 
static std::uint16_t getByte (void) noexcept
 Byte-oriented interface to the QS data buffer. More...
 
static std::uint8_t const * getBlock (std::uint16_t *const pNbytes) noexcept
 Block-oriented interface to the QS data buffer. More...
 
static bool onStartup (void const *arg)
 Callback to startup the QS facility. More...
 
static void onCleanup (void)
 Callback to cleanup the QS facility. More...
 
static void onFlush (void)
 Callback to flush the QS trace data to the host. More...
 
static QSTimeCtr onGetTime (void)
 Callback to obtain a timestamp for a QS record. More...
 
static void onReset (void)
 callback function to reset the Target (to be implemented in the BSP) More...
 
static void onCommand (std::uint8_t cmdId, std::uint32_t param1, std::uint32_t param2, std::uint32_t param3)
 Callback function to execute user commands (to be implemented in BSP) More...
 
static void rxHandleGoodFrame_ (std::uint8_t const state)
 internal function to handle incoming (QS-RX) packet More...
 
static void assertion_pre_ (char const *const module, int_t const loc, std::uint32_t const delay)
 internal function to produce the assertion failure trace record More...
 
static void crit_entry_pre_ (void)
 internal function to produce the critical section entry record More...
 
static void crit_exit_pre_ (void)
 internal function to produce the critical section exit record More...
 
static void isr_entry_pre_ (std::uint8_t const isrnest, std::uint8_t const prio)
 internal function to produce the ISR entry record More...
 
static void isr_exit_pre_ (std::uint8_t const isrnest, std::uint8_t const prio)
 internal function to produce the ISR exit record More...
 
static void onTestSetup (void)
 callback to setup a unit test inside the Target More...
 
static void onTestTeardown (void)
 callback to teardown after a unit test inside the Target More...
 
static void onTestEvt (QEvt *e)
 callback to "massage" the test event before dispatching/posting it More...
 
static void onTestPost (void const *sender, QActive *recipient, QEvt const *e, bool status)
 
static void onTestLoop (void)
 callback to run the test loop More...
 
static void processTestEvts_ (void)
 internal function to process posted events during test More...
 
static void tickX_ (std::uint_fast8_t const tickRate, void const *const sender) noexcept
 internal function to process armed time events during test More...
 
static std::uint32_t getTestProbe_ (void(*const api)(void)) noexcept
 internal function to get the Test-Probe for a given API More...
 
static void test_pause_ (void)
 internal function to pause test and enter the test event loop More...
 
template<typename T_OUT , typename T_IN >
static T_OUT force_cast (T_IN in)
 template for forcing cast of member functions for function dictionaries and test probes. More...
 

Public Attributes

std::uint8_t glbFilter [16]
 global on/off QS filter More...
 
std::uint8_t locFilter [16]
 local on/off QS filter More...
 
void const * locFilter_AP
 deprecated local QS filter More...
 
std::uint8_t * buf
 pointer to the start of the ring buffer More...
 
QSCtr end
 offset of the end of the ring buffer More...
 
QSCtr volatile head
 offset to where next byte will be inserted More...
 
QSCtr volatile tail
 offset of where next record will be extracted More...
 
QSCtr volatile used
 number of bytes currently in the ring buffer More...
 
std::uint8_t volatile seq
 the record sequence number More...
 
std::uint8_t volatile chksum
 the checksum of the current record More...
 
std::uint_fast8_t volatile critNest
 critical section nesting level More...
 

Static Public Attributes

static QS priv_
 
static QSrx rxPriv_
 

Detailed Description

Description
This class groups together QS services. It has only static members and should not be instantiated.

Definition at line 74 of file qs.hpp.

Member Enumeration Documentation

◆ QSType

enum QSType : std::uint8_t
Description
QS uses this enumeration is used only internally for the formatted user data elements.
Enumerator
I8_T 

signed 8-bit integer 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

HEX_FMT 

HEX format for the "width" filed.

Definition at line 493 of file qs.hpp.

◆ QSpyObjKind

enum QSpyObjKind : std::uint8_t
Enumerator
SM_OBJ 

state machine object for QEP

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

◆ OSpyObjCombnation

enum OSpyObjCombnation : std::uint8_t
Enumerator
SM_AO_OBJ 

combination of SM and AO

Definition at line 523 of file qs.hpp.

Member Function Documentation

◆ initBuf()

void initBuf ( std::uint8_t *const  sto,
std::uint_fast16_t const  stoSize 
)
staticnoexcept
Description
This function should be called from QP::QS::onStartup() to provide QS with the data buffer. The first argument sto[] is the address of the memory block, and the second argument stoSize is the size of this block [in bytes]. Currently the size of the QS buffer cannot exceed 64KB.
Note
QS can work with quite small data buffers, but you will start losing data 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.
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 record sequence counters and check sums on each record allow the QSPY host utility to easily detect any data loss.

Definition at line 50 of file qs.cpp.

◆ glbFilter_()

void glbFilter_ ( std::int_fast16_t const  filter)
staticnoexcept
Description
This function sets up the QS filter to enable record types specified in the filter parameter. The value QS_ALL_RECORDS specifies to filter-in all records. This function should be called indirectly through the macro QS_GLB_FILTER()
Parameters
[in]filterthe QS record-d or group to enable in the filter, if positive or disable, if negative. The record-id numbers must be in the range -127..127.
Note
Filtering based on the record-type is only the first layer of filtering. The second layer is based on the object-type. Both filter layers must be enabled for the QS record to be inserted in the QS buffer.
See also
QP::QS::locFilter_()

Definition at line 84 of file qs.cpp.

◆ locFilter_()

void locFilter_ ( std::int_fast16_t const  filter)
staticnoexcept
Description
This function sets up the local QS filter to enable or disable the given QS object-id or a group of object-ids filter. This function should be called indirectly through the macro QS_LOC_FILTER()
Parameters
[in]filterthe QS object-id or group to enable in the filter, if positive or disable, if negative. The qs_id numbers must be in the range 1..127.
Note
Filtering based on the object-id (local filter) is the second layer of filtering. The first layer is based on the QS record-type (global filter). Both filter layers must be enabled for the QS record to be inserted into the QS buffer.
See also
QP::QS::glbFilter_()

Definition at line 292 of file qs.cpp.

◆ beginRec_()

void beginRec_ ( std::uint_fast8_t const  rec)
staticnoexcept
Description
This function must be called at the beginning of each QS record. This function should be called indirectly through the macro QS_BEGIN_ID(), or QS_BEGIN_NOCRIT(), depending if it's called in a normal code or from a critical section.

Definition at line 350 of file qs.cpp.

◆ endRec_()

void endRec_ ( void  )
staticnoexcept
Description
This function must be called at the end of each QS record. This function should be called indirectly through the macro QS_END(), or QS_END_NOCRIT(), depending if it's called in a normal code or from a critical section.

Definition at line 370 of file qs.cpp.

◆ u8_raw_()

void u8_raw_ ( std::uint8_t const  d)
staticnoexcept

Definition at line 635 of file qs.cpp.

◆ u8u8_raw_()

void u8u8_raw_ ( std::uint8_t const  d1,
std::uint8_t const  d2 
)
staticnoexcept

Definition at line 649 of file qs.cpp.

◆ u16_raw_()

void u16_raw_ ( std::uint16_t  d)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 667 of file qs.cpp.

◆ u32_raw_()

void u32_raw_ ( std::uint32_t  d)
staticnoexcept

Definition at line 687 of file qs.cpp.

◆ obj_raw_()

void obj_raw_ ( void const *const  obj)
staticnoexcept

Definition at line 705 of file qs.cpp.

◆ str_raw_()

void str_raw_ ( char const *  s)
staticnoexcept

Definition at line 720 of file qs.cpp.

◆ u8_fmt_()

void u8_fmt_ ( std::uint8_t const  format,
std::uint8_t const  d 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 511 of file qs.cpp.

◆ u16_fmt_()

void u16_fmt_ ( std::uint8_t  format,
std::uint16_t  d 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 527 of file qs.cpp.

◆ u32_fmt_()

void u32_fmt_ ( std::uint8_t  format,
std::uint32_t  d 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 549 of file qs.cpp.

◆ f32_fmt_()

void f32_fmt_ ( std::uint8_t  format,
float32_t const  d 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 41 of file qs_fp.cpp.

◆ f64_fmt_()

void f64_fmt_ ( std::uint8_t  format,
float64_t const  d 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 70 of file qs_fp.cpp.

◆ str_fmt_()

void str_fmt_ ( char const *  s)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 607 of file qs.cpp.

◆ mem_fmt_()

void mem_fmt_ ( std::uint8_t const *  blk,
std::uint8_t  size 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 583 of file qs.cpp.

◆ u64_raw_()

void u64_raw_ ( std::uint64_t  d)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 41 of file qs_64bit.cpp.

◆ u64_fmt_()

void u64_fmt_ ( std::uint8_t  format,
std::uint64_t  d 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 62 of file qs_64bit.cpp.

◆ sig_dict_pre_()

void sig_dict_pre_ ( enum_t const  sig,
void const *const  obj,
char const *const  name 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 801 of file qs.cpp.

◆ obj_dict_pre_()

void obj_dict_pre_ ( void const *const  obj,
char const *const  name 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 817 of file qs.cpp.

◆ obj_arr_dict_pre_()

void obj_arr_dict_pre_ ( void const *const  obj,
std::uint_fast16_t const  idx,
char const *const  name 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 832 of file qs.cpp.

◆ fun_dict_pre_()

void fun_dict_pre_ ( void(*)(void)  fun,
char const *const  name 
)
staticnoexcept

Definition at line 895 of file qs.cpp.

◆ usr_dict_pre_()

void usr_dict_pre_ ( enum_t const  rec,
char const *const  name 
)
staticnoexcept
Note
This function is only to be used through macros, never in the client code directly.

Definition at line 569 of file qs.cpp.

◆ rxInitBuf()

void rxInitBuf ( std::uint8_t *const  sto,
std::uint16_t const  stoSize 
)
staticnoexcept
Description
This function should be called from QS::onStartup() to provide QS-RX with the receive data buffer.
Parameters
[in]sto[]the address of the memory block
[in]stoSizethe size of this block [bytes]. The size of the QS RX buffer cannot exceed 64KB.
Note
QS-RX can work with quite small data buffers, but you will start losing data if the buffer is not drained fast enough (e.g., in the idle task).
If the data input rate exceeds the QS-RX processing rate, the data will be lost, but the QS protocol will notice that: (1) that the checksum in the incomplete QS records will fail; and (2) the sequence counter in QS records will show discontinuities.

The QS-RX channel will report any data errors by sending the QS_RX_DATA_ERROR trace record.

Definition at line 223 of file qs_rx.cpp.

◆ rxParse()

void rxParse ( void  )
static

Definition at line 332 of file qs_rx.cpp.

◆ rxGetNfree()

std::uint16_t rxGetNfree ( void  )
staticnoexcept
Description
This function is intended to be called from the ISR that reads the QS-RX bytes from the QSPY application. The function returns the conservative number of free bytes currently available in the buffer, assuming that the head pointer is not being moved concurrently. The tail pointer might be moving, meaning that bytes can be concurrently removed from the buffer.

Definition at line 256 of file qs_rx.cpp.

◆ rxPut()

bool rxPut ( std::uint8_t const  b)
inlinestaticnoexcept

Definition at line 763 of file qs.hpp.

◆ setCurrObj()

void setCurrObj ( std::uint8_t  obj_kind,
void *  obj_ptr 
)
staticnoexcept
Description
This function sets the "current object" in the Target.

Definition at line 271 of file qs_rx.cpp.

◆ queryCurrObj()

void queryCurrObj ( std::uint8_t  obj_kind)
staticnoexcept
Description
This function programmatically generates the response to the query for the "current object".

Definition at line 277 of file qs_rx.cpp.

◆ getByte()

std::uint16_t getByte ( void  )
staticnoexcept
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 QP::QS_EOD (End-Of-Data).
Note
QP::QS::getByte() is not protected with a critical section.

Definition at line 744 of file qs.cpp.

◆ getBlock()

std::uint8_t const * getBlock ( std::uint16_t *const  pNbytes)
staticnoexcept
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.
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 QP::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 QP::QS::getBlock() again to obtain the rest of the data that "wrapped around" to the beginning of the QS data buffer.
QP::QS::getBlock() is not protected with a critical section.

Definition at line 767 of file qs.cpp.

◆ onStartup()

static bool onStartup ( void const *  arg)
static

◆ onCleanup()

static void onCleanup ( void  )
static

◆ onFlush()

static void onFlush ( void  )
static

◆ onGetTime()

QSTimeCtr onGetTime ( void  )
static

Definition at line 752 of file qs_rx.cpp.

◆ onReset()

static void onReset ( void  )
static

◆ onCommand()

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

◆ rxHandleGoodFrame_()

void rxHandleGoodFrame_ ( std::uint8_t const  state)
static

Definition at line 377 of file qs_rx.cpp.

◆ assertion_pre_()

void assertion_pre_ ( char const *const  module,
int_t const  loc,
std::uint32_t const  delay 
)
static

Definition at line 910 of file qs.cpp.

◆ crit_entry_pre_()

void crit_entry_pre_ ( void  )
static

Definition at line 926 of file qs.cpp.

◆ crit_exit_pre_()

void crit_exit_pre_ ( void  )
static

Definition at line 935 of file qs.cpp.

◆ isr_entry_pre_()

void isr_entry_pre_ ( std::uint8_t const  isrnest,
std::uint8_t const  prio 
)
static

Definition at line 944 of file qs.cpp.

◆ isr_exit_pre_()

void isr_exit_pre_ ( std::uint8_t const  isrnest,
std::uint8_t const  prio 
)
static

Definition at line 955 of file qs.cpp.

◆ onTestSetup()

static void onTestSetup ( void  )
static

◆ onTestTeardown()

static void onTestTeardown ( void  )
static

◆ onTestEvt()

static void onTestEvt ( QEvt e)
static

◆ onTestPost()

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

◆ onTestLoop()

static void onTestLoop ( void  )
static

◆ processTestEvts_()

void processTestEvts_ ( void  )
static

Definition at line 305 of file qutest.cpp.

◆ tickX_()

void tickX_ ( std::uint_fast8_t const  tickRate,
void const *const  sender 
)
staticnoexcept

Definition at line 337 of file qutest.cpp.

◆ getTestProbe_()

std::uint32_t getTestProbe_ ( void(*)(void)  api)
staticnoexcept
Description
This function obtains the Test-Probe for a given API.
Parameters
[in]apipointer to the API function that requests its Test-Probe
Returns
Test-Probe data that has been received for the given API from the Host (running qutest). For any ginve API, the function returns the Test-Probe data in the same order as it was received from the Host. If there is no Test-Probe for a ginve API, or no more Test-Probes for a given API, the function returns zero.

Definition at line 723 of file qs_rx.cpp.

◆ test_pause_()

void test_pause_ ( void  )
static

Definition at line 446 of file qutest.cpp.

◆ force_cast()

static T_OUT force_cast ( T_IN  in)
inlinestatic

Definition at line 530 of file qs.hpp.

Member Data Documentation

◆ glbFilter

std::uint8_t glbFilter[16]

Definition at line 539 of file qs.hpp.

◆ locFilter

std::uint8_t locFilter[16]

Definition at line 540 of file qs.hpp.

◆ locFilter_AP

void const* locFilter_AP

Definition at line 541 of file qs.hpp.

◆ buf

std::uint8_t* buf

Definition at line 542 of file qs.hpp.

◆ end

QSCtr end

Definition at line 543 of file qs.hpp.

◆ head

QSCtr volatile head

Definition at line 544 of file qs.hpp.

◆ tail

QSCtr volatile tail

Definition at line 545 of file qs.hpp.

◆ used

QSCtr volatile used

Definition at line 546 of file qs.hpp.

◆ seq

std::uint8_t volatile seq

Definition at line 547 of file qs.hpp.

◆ chksum

std::uint8_t volatile chksum

Definition at line 548 of file qs.hpp.

◆ critNest

std::uint_fast8_t volatile critNest

Definition at line 550 of file qs.hpp.

◆ priv_

QS priv_
static

Definition at line 552 of file qs.hpp.

◆ rxPriv_

QSrx rxPriv_
static

Definition at line 554 of file qs.hpp.


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