QS Class Reference

Mark the begin of a QS record rec.

This function must be called at the beginning of each QS record. This function should be called indirectly through the macro QS_BEGIN, or QS_BEGIN_NOCRIT, depending if it's called in a normal code or from a critical section.

Mark the end of a QS record rec.

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.

Output 32-bit floating point data element with format information.

Note:

This function is only to be used through macros, never in the client code directly.

Output 64-bit floating point data element with format information.

Note:

This function is only to be used through macros, never in the client code directly.

Turn the global Filter off for a given record type rec.

This function sets up the QS filter to disable the record type rec. The argument QS_ALL_RECORDS specifies to suppress all records. This function should be called indirectly through the macro QS_FILTER_OFF.

Note:

Filtering records 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 into the QS buffer.

See also:

Turn the global Filter on for a given record type rec.

This function sets up the QS filter to enable the record type rec. The argument QS_ALL_RECORDS specifies to filter-on all records. This function should be called indirectly through the macro QS_FILTER_ON.

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 into the QS buffer.

See also:

QS_filterOff(), QS_FILTER_SM_OBJ, QS_FILTER_AO_OBJ, QS_FILTER_MP_OBJ, QS_FILTER_EQ_OBJ, and QS_FILTER_TE_OBJ.

Block-oriented interface to the QS data buffer.

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.

If no bytes are available in the QS buffer when the function is called, the function returns a 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.

QS::getBlock() is NOT protected with a critical section.

Byte-oriented interface to the QS data buffer.

This function delivers one byte at a time from the QS data buffer. The function 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).

Note:

QS::getByte() is NOT protected with a critical section.

Get the current version of QS.

Returns:

version of the QS as a constant 6-character string of the form x.y.zz, where x is a 1-digit major version number, y is a 1-digit minor version number, and zz is a 2-digit release number.

Initialize the QS data buffer.

This function should be called from QS_init() 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.

QS can work with quite small data buffers, but you will start losing data if the buffer is too small for the bursts of logging 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 record sequence counters and checksums on each record allow to easily detect data loss.

Output memory block of up to 255-bytes with format information.

Note:

This function is only to be used through macros, never in the client code directly.

Callback to cleanup the QS facility.

This is a platform-dependent "callback" function invoked through the macro QS_EXIT. You need to implement this function in your application. The main purpose of this function is to close the QS output channel, if necessary.

Callback to flush the QS trace data to the host.

This is a platform-dependent "callback" function to flush the QS trace buffer to the host. The function typically busy-waits until all the data in the buffer is sent to the host. This is acceptable only in the initial transient.

Callback to obtain a timestamp for a QS record.

This is a platform-dependent "callback" function invoked from the macro QS_TIME_ to add the time stamp to the QS record.

Note:

Some of the pre-defined QS records from QP do not output the time stamp. However, ALL user records do output the time stamp.

QS::onGetTime() is called in a critical section and should not exit critical section.

The following example shows using a system call to implement QS time stamping:

Callback to startup the QS facility.

This is a platform-dependent "callback" function invoked through the macro QS_INIT. You need to implement this function in your application. At a minimum, the function must configure the QS buffer by calling QS::initBuf(). Typically, you will also want to open/ configure the QS output channel, such as a serial port, or a file. The void* argument arg can be used to pass parameter(s) needed to configure the output channel.

The function returns true if the QS initialization was successful, or false if it failed.

The following example illustrates an implementation of QS_onStartup():

Output zero-terminated ASCII string element with format information.

Note:

This function is only to be used through macros, never in the client code directly.

Output zero-terminated ASCII string element without format information.

Note:

This function is only to be used through macros, never in the client code directly.

Output zero-terminated ASCII string element allocated in ROM with format information.

Note:

This function is only to be used through macros, never in the client code directly.

Output zero-terminated ASCII string element allocated in ROM without format information.

Note:

This function is only to be used through macros, never in the client code directly.

output uint16_t data element with format information

Note:

This function is only to be used through macros, never in the client code directly.

Output uint16_t data element without format information.

Note:

This function is only to be used through macros, never in the client code directly.

Output uint32_t data element with format information.

Note:

This function is only to be used through macros, never in the client code directly.

Output uint32_t data element without format information.

Note:

This function is only to be used through macros, never in the client code directly.

Output uint64_t data element with format information.

Note:

This function is only to be used through macros, never in the client code directly.

Output uint64_t data element without format information.

Note:

This function is only to be used through macros, never in the client code directly.

Output uint8_t data element with format information.

Note:

This function is only to be used through macros, never in the client code directly.

output uint8_t data element without format information

Note:

This function is only to be used through macros, never in the client code directly.

active object for QF/QK local filter

Definition at line 2787 of file qp.h.

generic object Application QF local filter

Definition at line 2791 of file qp.h.

raw queue for QF local filter

Definition at line 2789 of file qp.h.

global on/off QS filter

Definition at line 2785 of file qp.h.

event pool for QF local filter

Definition at line 2788 of file qp.h.

state machine for QEP local filter

Definition at line 2786 of file qp.h.

time event for QF local filter

Definition at line 2790 of file qp.h.

tick counter for the QS_QF_TICK record

Definition at line 2796 of file qp.h.