QP/C  6.5.1
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_ (uint8_t isReset)
 send the Target info (object sizes, build time-stamp, QP version) More...
 
void QS_u8 (uint8_t format, uint8_t d)
 Output uint8_t data element with format information. More...
 
void QS_u16 (uint8_t format, uint16_t d)
 output uint16_t data element with format information More...
 
void QS_u32 (uint8_t format, uint32_t d)
 Output uint32_t data element with format information. More...
 
void QS_u8_ (uint8_t d)
 output uint8_t data element without format information More...
 
void QS_u8u8_ (uint8_t d1, uint8_t d2)
 output two uint8_t data elements without format information More...
 
void QS_u16_ (uint16_t d)
 Output uint16_t data element without format information. More...
 
void QS_u32_ (uint32_t d)
 Output uint32_t data element without format information. More...
 
void QS_str_ (char_t const *s)
 Output zero-terminated ASCII 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 (enum_t const sig, void const *const obj, char_t const *name)
 Output signal dictionary record. More...
 
void QS_obj_dict (void const *const obj, char_t const *name)
 Output object dictionary record. More...
 
void QS_fun_dict (void(*const fun)(void), char_t const *name)
 Output function dictionary record. More...
 
void QS_usr_dict (enum_t const rec, char_t const *const name)
 Output user dictionary record. More...
 
void QS_mem (uint8_t const *blk, uint8_t size)
 Output memory block of up to 255-bytes with format information. More...
 
void QS_str (char_t const *s)
 Output zero-terminated ASCII string element with format information. More...
 

Variables

char_t const Q_BUILD_DATE [12]
 
char_t const Q_BUILD_TIME [9]
 
QSPriv 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 80 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 125 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 215 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 306 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 333 of file qs.c.

◆ QS_target_info_()

void QS_target_info_ ( uint8_t  isReset)

send the Target info (object sizes, build time-stamp, QP version)

Definition at line 363 of file qs.c.

◆ QS_u8()

void QS_u8 ( 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 481 of file qs.c.

◆ QS_u16()

void QS_u16 ( 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 502 of file qs.c.

◆ QS_u32()

void QS_u32 ( 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 528 of file qs.c.

◆ QS_u8_()

void QS_u8_ ( uint8_t  d)

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

◆ QS_u8u8_()

void QS_u8u8_ ( uint8_t  d1,
uint8_t  d2 
)

output two 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 571 of file qs.c.

◆ QS_u16_()

void QS_u16_ ( uint16_t  d)

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

◆ QS_u32_()

void QS_u32_ ( uint32_t  d)

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

◆ QS_str_()

void QS_str_ ( char_t const *  s)

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 636 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 670 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 712 of file qs.c.

◆ QS_sig_dict()

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

Output signal dictionary record.

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

Definition at line 748 of file qs.c.

◆ QS_obj_dict()

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

Output object dictionary record.

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

Definition at line 769 of file qs.c.

◆ QS_fun_dict()

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

Output function dictionary record.

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

Definition at line 789 of file qs.c.

◆ QS_usr_dict()

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

Output user dictionary record.

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

Definition at line 807 of file qs.c.

◆ QS_mem()

void QS_mem ( 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 825 of file qs.c.

◆ QS_str()

void QS_str ( char_t const *  s)

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

Variable Documentation

◆ Q_BUILD_DATE

char_t const Q_BUILD_DATE[12]

◆ Q_BUILD_TIME

char_t const Q_BUILD_TIME[9]

◆ QS_priv_

QSPriv QS_priv_

Definition at line 53 of file qs.c.