QS software tracing services. More...

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

Include dependency graph for qs.c:

Functions
void	QS_initBuf (uint8_t sto[], uint_fast16_t stoSize)
	Initialize the QS data buffer. More...

void	QS_glbFilter_ (int_fast16_t const filter)
	Set/clear the global Filter for a given QS record or group of records. More...

void	QS_locFilter_ (int_fast16_t const filter)
	Set/clear the local Filter for a given object-id or group of object-ids. 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 76 of file qs.c.

◆ QS_glbFilter_()

void QS_glbFilter_ ( int_fast16_t const filter )

Set/clear the global Filter for a given QS record or group of records.

Description: This function sets up the global QS filter to enable or disable the given QS record or a group of records rec.

Parameters

[in] filter the QS record number or group to enable in the filter, if positive or disable, if negative. The record numbers must be from the enumeration QSpyRecords. The record groups from enumeration QSpyRecordGroups.

Note: Filtering based on the record-type (global filter) is only the first layer of filtering. The second layer is based on the object-id (local filter). Both filter layers must be enabled for the QS record to be inserted into the QS buffer.

Definition at line 119 of file qs.c.

◆ QS_locFilter_()

void QS_locFilter_ ( int_fast16_t const filter )

Set/clear the local Filter for a given object-id or group of object-ids.

Description: This function sets up the local QS filter to enable or disable the given QS object-id or a group of object-ids qs_id.

Parameters

[in] qs_id the 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 (gloabl filter). Both filter layers must be enabled for the QS record to be inserted into the QS buffer.

Definition at line 314 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_ID(), or QS_BEGIN_NOCRIT(), depending if it's called in a normal code or from a critical section.

Definition at line 376 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 403 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 433 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 547 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 568 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 591 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 617 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 634 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 653 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 674 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 696 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 715 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 747 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 789 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 825 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 843 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 860 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 875 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 893 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 922 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 948 of file qs.c.

◆ QF_QS_CRIT_ENTRY()

void QF_QS_CRIT_ENTRY ( void )

Output the critical section entry.

Definition at line 968 of file qs.c.

◆ QF_QS_CRIT_EXIT()

void QF_QS_CRIT_EXIT ( void )

Output the critical section exit.

Definition at line 976 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 987 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 994 of file qs.c.

Variable Documentation

◆ QS_priv_

QSPrivAttr QS_priv_

Definition at line 49 of file qs.c.

Functions

Variables