QS Class Reference

Quantum Spy logging facilities. More...

#include <qs.h>

List of all members.

Static Public Member Functions
static char_t const Q_ROM *Q_ROM_VAR	getVersion (void)
	Get the current version of QS.
static void	initBuf (uint8_t sto[], uint32_t const stoSize)
	Initialize the QS data buffer.
static void	filterOn (uint8_t const rec)
	Turn the global Filter on for a given record type rec.
static void	filterOff (uint8_t const rec)
	Turn the global Filter off for a given record type rec.
static void	begin (uint8_t const rec)
	Mark the begin of a QS record rec.
static void	end (void)
	Mark the end of a QS record rec.
static void	u8_ (uint8_t const d)
	output uint8_t data element without format information
static void	u16_ (uint16_t d)
	Output uint16_t data element without format information.
static void	u32_ (uint32_t d)
	Output uint32_t data element without format information.
static void	str_ (char_t const *s)
	Output zero-terminated ASCII string element without format information.
static void	str_ROM_ (char_t const Q_ROM *Q_ROM_VAR s)
	Output zero-terminated ASCII string element allocated in ROM without format information.
static void	u8 (uint8_t const format, uint8_t const d)
	Output uint8_t data element with format information.
static void	u16 (uint8_t const format, uint16_t d)
	output uint16_t data element with format information
static void	u32 (uint8_t const format, uint32_t d)
	Output uint32_t data element with format information.
static void	f32 (uint8_t const format, float32_t const d)
	Output 32-bit floating point data element with format information.
static void	f64 (uint8_t const format, float64_t const d)
	Output 64-bit floating point data element with format information.
static void	str (char_t const *s)
	Output zero-terminated ASCII string element with format information.
static void	str_ROM (char_t const Q_ROM *Q_ROM_VAR s)
	Output zero-terminated ASCII string element allocated in ROM with format information.
static void	mem (uint8_t const *blk, uint8_t size)
	Output memory block of up to 255-bytes with format information.
static uint16_t	getByte (void)
	Byte-oriented interface to the QS data buffer.
static uint8_t const *	getBlock (uint16_t *const pNbytes)
	Block-oriented interface to the QS data buffer.
static bool	onStartup (void const *arg)
	Callback to startup the QS facility.
static void	onCleanup (void)
	Callback to cleanup the QS facility.
static void	onFlush (void)
	Callback to flush the QS trace data to the host.
static QSTimeCtr	onGetTime (void)
	Callback to obtain a timestamp for a QS record.
Static Public Attributes
static uint8_t	glbFilter_ [32]
	global on/off QS filter
static void const *	smObj_
	state machine for QEP local filter
static void const *	aoObj_
	active object for QF/QK local filter
static void const *	mpObj_
	event pool for QF local filter
static void const *	eqObj_
	raw queue for QF local filter
static void const *	teObj_
	time event for QF local filter
static void const *	apObj_
	generic object Application QF local filter
static QSTimeCtr	tickCtr_
	tick counter for the QS_QF_TICK record

---

Detailed Description

Quantum Spy logging facilities.

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

Definition at line 195 of file qs.h.

---

Member Function Documentation

void QS::begin

(

uint8_t const

rec

)

[static]

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.

Definition at line 109 of file qs.cpp.

References QS_chksum_, QS_INSERT_ESC_BYTE, and QS_seq_.

void QS::end

(

void

)

[static]

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.

Definition at line 116 of file qs.cpp.

References QS_end_, QS_FRAME, QS_head_, QS_INSERT_BYTE, QS_INSERT_CHKSUM_BYTE, QS_tail_, and QS_used_.

QP_BEGIN_ void QS::f32	(	uint8_t const	format,
		float32_t const	d
	)		[static]

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.

Definition at line 44 of file qs_f32.cpp.

References QS_INSERT_ESC_BYTE.

QP_BEGIN_ void QS::f64	(	uint8_t const	format,
		float64_t const	d
	)		[static]

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.

Definition at line 44 of file qs_f64.cpp.

References QS_INSERT_ESC_BYTE.

void QS::filterOff

(

uint8_t const

rec

)

[static]

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:

Definition at line 93 of file qs.cpp.

References glbFilter_, and QS_ALL_RECORDS.

void QS::filterOn

(

uint8_t const

rec

)

[static]

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.

Definition at line 77 of file qs.cpp.

References glbFilter_, and QS_ALL_RECORDS.

QP_BEGIN_ uint8_t const * QS::getBlock

(

uint16_t *const

pNbytes

)

[static]

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.

Definition at line 45 of file qs_blk.cpp.

References QS_end_, QS_PTR_AT_, QS_tail_, QS_used_, and QSCtr.

QP_BEGIN_ uint16_t QS::getByte

(

void

)

[static]

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.

Definition at line 44 of file qs_byte.cpp.

References QS_end_, QS_EOD, QS_PTR_AT_, QS_tail_, QS_used_, and QSCtr.

char_t const Q_ROM *Q_ROM_VAR QS::getVersion

(

void

)

[static]

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.

Definition at line 58 of file qs.cpp.

References QP_VERSION.

void QS::initBuf	(	uint8_t	sto[],
		uint32_t const	stoSize
	)		[static]

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 check sums on each record allow to easily detect data loss.

Definition at line 72 of file qs.cpp.

References QS_end_, QS_ring_, and QSCtr.

QP_BEGIN_ void QS::mem	(	uint8_t const *	blk,
		uint8_t	size
	)		[static]

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.

Definition at line 44 of file qs_mem.cpp.

References QS_chksum_, QS_INSERT_BYTE, QS_INSERT_ESC_BYTE, and QS_MEM_T.

static void QS::onCleanup

(

void

)

[static]

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.

static void QS::onFlush

(

void

)

[static]

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.

static QSTimeCtr QS::onGetTime

(

void

)

[static]

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:

#ifdef Q_SPY

QSTimeCtr QS::onGetTime(void) {
    return (QSTimeCtr)clock();
}

. . .

#endif // Q_SPY

static bool QS::onStartup

(

void const *

arg

)

[static]

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

#ifdef Q_SPY

uint8_t QS::onStartup(void const *arg) {
    static uint8_t qsBuf[4*1024];                    // buffer for Quantum Spy

    initBuf(qsBuf, sizeof(qsBuf));               // configure the Q-Spy buffer

    // configure UART 0/1 for QSPY output ...
    if (*(char const *)arg == '0') {                             // use UART 0
           // configure UART 0 for QSPY output ...
        . . .
        return (uint8_t)1;                       // UART 0 successfully opened
    }
    else {                                                       // use UART 1
           // configure UART 1 for QSPY output ...
        . . .
        return (uint8_t)1;                       // UART 1 successfully opened
    }
}

. . .

#endif // Q_SPY

QP_BEGIN_ void QS::str

(

char_t const *

s

)

[static]

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.

Definition at line 44 of file qs_str.cpp.

References QS_chksum_, QS_INSERT_BYTE, and QS_STR_T.

void QS::str_

(

char_t const *

s

)

[static]

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.

Definition at line 74 of file qs_.cpp.

References QS_chksum_, and QS_INSERT_BYTE.

void QS::str_ROM

(

char_t const Q_ROM *Q_ROM_VAR

s

)

[static]

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.

Definition at line 59 of file qs_str.cpp.

References QS_chksum_, QS_INSERT_BYTE, and QS_STR_T.

void QS::str_ROM_

(

char_t const Q_ROM *Q_ROM_VAR

s

)

[static]

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.

Definition at line 86 of file qs_.cpp.

References QS_chksum_, and QS_INSERT_BYTE.

void QS::u16	(	uint8_t const	format,
		uint16_t	d
	)		[static]

output uint16_t data element with format information

Note:

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

Definition at line 130 of file qs.cpp.

References QS_INSERT_ESC_BYTE.

void QS::u16_

(

uint16_t

d

)

[static]

Output uint16_t data element without format information.

Note:

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

Definition at line 58 of file qs_.cpp.

References QS_INSERT_ESC_BYTE.

void QS::u32	(	uint8_t const	format,
		uint32_t	d
	)		[static]

Output uint32_t data element with format information.

Note:

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

Definition at line 137 of file qs.cpp.

References QS_INSERT_ESC_BYTE.

void QS::u32_

(

uint32_t

d

)

[static]

Output uint32_t data element without format information.

Note:

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

Definition at line 64 of file qs_.cpp.

References QS_INSERT_ESC_BYTE.

void QS::u8	(	uint8_t const	format,
		uint8_t const	d
	)		[static]

Output uint8_t data element with format information.

Note:

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

Definition at line 125 of file qs.cpp.

References QS_INSERT_ESC_BYTE.

void QS::u8_

(

uint8_t const

d

)

[static]

output uint8_t data element without format information

Note:

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

Definition at line 54 of file qs_.cpp.

References QS_INSERT_ESC_BYTE.

---

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

• qs.h
• qs.cpp
• qs_.cpp
• qs_blk.cpp
• qs_byte.cpp
• qs_f32.cpp
• qs_f64.cpp
• qs_mem.cpp
• qs_str.cpp