qs.c File Reference

QS software tracing services. More...

#include "qs_port.h"
#include "qs_pkg.h"
#include "qassert.h"

Include dependency graph for qs.c:

Go to the source code of this file.

Functions
void	QS_initBuf (uint8_t sto[], uint_fast16_t stoSize)
	Initialize the QS data buffer. More...
void	QS_filterOn_ (uint_fast8_t rec)
	Turn the global Filter on for a given record type rec. More...
void	QS_filterOff_ (uint_fast8_t rec)
	Turn the global Filter off for a given record type rec. More...
void	QS_beginRec_ (uint_fast8_t rec)
	Mark the begin of a QS record rec. More...
void	QS_endRec_ (void)
	Mark the end of a QS record rec. More...
void	QS_target_info_pre_ (uint8_t isReset)
	send the predefined target info trace record (object sizes, build time-stamp, QP version) More...
void	QS_u8_fmt_ (uint8_t format, uint8_t d)
	Output uint8_t data element with format information. More...
void	QS_u16_fmt_ (uint8_t format, uint16_t d)
	output uint16_t data element with format information More...
void	QS_u32_fmt_ (uint8_t format, uint32_t d)
	Output uint32_t data element with format information. More...
void	QS_u8_raw_ (uint8_t d)
	output uint8_t data element without format information More...
void	QS_2u8_raw_ (uint8_t d1, uint8_t d2)
	output two raw uint8_t data elements (without format information) More...
void	QS_u16_raw_ (uint16_t d)
	Output raw uint16_t data element (without format information) More...
void	QS_u32_raw_ (uint32_t d)
	Output raw uint32_t data element (without format information) More...
void	QS_obj_raw_ (void const *const obj)
	Output obj pointer data element without format information. More...
void	QS_str_raw_ (char_t const *str)
	Output raw zero-terminated string element (without format information) More...
uint16_t	QS_getByte (void)
	Byte-oriented interface to the QS data buffer. More...
uint8_t const *	QS_getBlock (uint16_t *pNbytes)
	Block-oriented interface to the QS data buffer. More...
void	QS_sig_dict_pre_ (enum_t const sig, void const *const obj, char_t const *name)
	Output predefined signal-dictionary record. More...
void	QS_obj_dict_pre_ (void const *const obj, char_t const *name)
	Output predefined object-dictionary record. More...
void	QS_fun_dict_pre_ (void(*const fun)(void), char_t const *name)
	Output predefined function-dictionary record. More...
void	QS_usr_dict_pre_ (enum_t const rec, char_t const *const name)
	Output predefined user-dictionary record. More...
void	QS_mem_fmt_ (uint8_t const *blk, uint8_t size)
	Output memory block of up to 255-bytes with format information. More...
void	QS_str_fmt_ (char_t const *str)
	Output zero-terminated ASCII string element with format information. More...
void	QS_ASSERTION (char_t const *const module, int_t const loc, uint32_t delay)
	Output the assertion failure trace record. More...
void	QF_QS_CRIT_ENTRY (void)
	Output the critical section entry. More...
void	QF_QS_CRIT_EXIT (void)
	Output the critical section exit. More...
void	QF_QS_ISR_ENTRY (uint8_t const isrnest, uint8_t const prio)
	Output the interrupt entry record. More...
void	QF_QS_ISR_EXIT (uint8_t const isrnest, uint8_t const prio)
	Output the interrupt exit record. More...

Variables
QSPrivAttr	QS_priv_

Detailed Description

QS software tracing services.

Definition in file qs.c.

Function Documentation

QS_initBuf()

void QS_initBuf	(	uint8_t	sto[],
		uint_fast16_t	stoSize
	)

Initialize the QS data buffer.

Description

This function should be called from QS_onStartup() to provide QS with the data buffer. The first parameter sto[] is the address of the memory block, and the second parameter 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 uitiliy to easily detect any data loss.

This function initializes all the internal QS variables, so that the tracing can start correctly even if the startup code fails to clear any uninitialized data (as is required by the C Standard).

Definition at line 75 of file qs.c.

QS_filterOn_()

void QS_filterOn_

(

uint_fast8_t

rec

)

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

Description

This function sets up the QS filter to enable the record type rec. The argument QS_ALL_RECORDS specifies to filter-in 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 121 of file qs.c.

QS_filterOff_()

void QS_filterOff_

(

uint_fast8_t

rec

)

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

Description

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 (global filter). The second layer is based on the object-type (local filter). Both filter layers must be enabled for the QS record to be inserted into the QS buffer.

Definition at line 202 of file qs.c.

QS_beginRec_()

void QS_beginRec_

(

uint_fast8_t

rec

)

Mark the begin of a QS record rec.

Description

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

QS_endRec_()

void QS_endRec_

(

void

)

Mark the end of a QS record rec.

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

QS_target_info_pre_()

void QS_target_info_pre_

(

uint8_t

isReset

)

send the predefined target info trace record (object sizes, build time-stamp, QP version)

Definition at line 342 of file qs.c.

QS_u8_fmt_()

void QS_u8_fmt_	(	uint8_t	format,
		uint8_t	d
	)

Output uint8_t data element with format information.

Description

Note

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

Definition at line 449 of file qs.c.

QS_u16_fmt_()

void QS_u16_fmt_	(	uint8_t	format,
		uint16_t	d
	)

output uint16_t data element with format information

Description

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

Definition at line 470 of file qs.c.

QS_u32_fmt_()

void QS_u32_fmt_	(	uint8_t	format,
		uint32_t	d
	)

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

QS_u8_raw_()

void QS_u8_raw_

(

uint8_t

d

)

output uint8_t data element without format information

output raw 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 519 of file qs.c.

QS_2u8_raw_()

void QS_2u8_raw_	(	uint8_t	d1,
		uint8_t	d2
	)

output two raw uint8_t data elements (without format information)

Note

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

Definition at line 536 of file qs.c.

QS_u16_raw_()

void QS_u16_raw_

(

uint16_t

d

)

Output raw 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 555 of file qs.c.

QS_u32_raw_()

void QS_u32_raw_

(

uint32_t

d

)

Output raw 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 576 of file qs.c.

QS_obj_raw_()

void QS_obj_raw_

(

void const *const

obj

)

Output obj pointer data element without format information.

Note

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

Definition at line 598 of file qs.c.

QS_str_raw_()

void QS_str_raw_

(

char_t const *

str

)

Output raw zero-terminated string element (without format information)

Note

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

Definition at line 617 of file qs.c.

QS_getByte()

uint16_t QS_getByte

(

void

)

Byte-oriented interface to the QS 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).

Note

QS_getByte() is not protected with a critical section.

Definition at line 649 of file qs.c.

QS_getBlock()

uint8_t const* QS_getBlock

(

uint16_t *

pNbytes

)

Block-oriented interface to the QS 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 parameter 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 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 691 of file qs.c.

QS_sig_dict_pre_()

void QS_sig_dict_pre_	(	enum_t const	sig,
		void const *const	obj,
		char_t const *	name
	)

Output predefined signal-dictionary record.

Note

This function is only to be used through macro QS_SIG_DICTIONARY()

Definition at line 727 of file qs.c.

QS_obj_dict_pre_()

void QS_obj_dict_pre_	(	void const *const	obj,
		char_t const *	name
	)

Output predefined object-dictionary record.

Note

This function is only to be used through macro QS_OBJ_DICTIONARY()

Definition at line 745 of file qs.c.

QS_fun_dict_pre_()

void QS_fun_dict_pre_	(	void(*)(void)	fun,
		char_t const *	name
	)

Output predefined function-dictionary record.

Note

This function is only to be used through macro QS_FUN_DICTIONARY()

Definition at line 762 of file qs.c.

QS_usr_dict_pre_()

void QS_usr_dict_pre_	(	enum_t const	rec,
		char_t const *const	name
	)

Output predefined user-dictionary record.

Note

This function is only to be used through macro QS_USR_DICTIONARY()

Definition at line 777 of file qs.c.

QS_mem_fmt_()

void QS_mem_fmt_	(	uint8_t const *	blk,
		uint8_t	size
	)

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

QS_str_fmt_()

void QS_str_fmt_

(

char_t const *

str

)

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

QS_ASSERTION()

void QS_ASSERTION	(	char_t const *const	module,
		int_t const	loc,
		uint32_t	delay
	)

Output the assertion failure trace record.

Description

This trace record is intended to use from the Q_onAssert() callback.

Definition at line 850 of file qs.c.

QF_QS_CRIT_ENTRY()

void QF_QS_CRIT_ENTRY

(

void

)

Output the critical section entry.

Definition at line 870 of file qs.c.

QF_QS_CRIT_EXIT()

void QF_QS_CRIT_EXIT

(

void

)

Output the critical section exit.

Definition at line 878 of file qs.c.

QF_QS_ISR_ENTRY()

void QF_QS_ISR_ENTRY	(	uint8_t const	isrnest,
		uint8_t const	prio
	)

Output the interrupt entry record.

Definition at line 889 of file qs.c.

QF_QS_ISR_EXIT()

void QF_QS_ISR_EXIT	(	uint8_t const	isrnest,
		uint8_t const	prio
	)

Output the interrupt exit record.

Definition at line 896 of file qs.c.

Variable Documentation

QS_priv_

QSPrivAttr QS_priv_

Definition at line 48 of file qs.c.