QP::QS Namespace Reference

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

Typedefs
using	QSTimeCtr = std::uint32_t

Functions
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	rxInitBuf (std::uint8_t *const sto, std::uint16_t const stoSize) noexcept
bool	rxPut (std::uint8_t const b) noexcept
void	rxParse ()

Detailed Description

QP/Spy software tracing (target-resident components)

Typedef Documentation

QSTimeCtr

using QP::QS::QSTimeCtr = std::uint32_t

Definition at line 97 of file qs_dummy.hpp.

Function Documentation

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

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

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

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

(

)

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.

rxPut()

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

noexcept

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

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