Percepio Trace Recorder  v4.6.6
Trace Print APIs

Functions

traceResult xTracePrint (TraceStringHandle_t xChannel, const char *szString)
 Generate "User Events" with unformatted text. More...
 
traceResult xTraceConsoleChannelPrintF (const char *szFormat,...)
 Wrapper for vTracePrintF for printing to default channel. More...
 
traceResult xTracePrintF (TraceStringHandle_t xChannel, const char *szFormat,...)
 Generates "User Events" with formatted text and data. More...
 
traceResult xTraceVPrintF (TraceStringHandle_t xChannel, const char *szFormat, va_list xVL)
 Generates "User Events" with formatted text and data. More...
 

Detailed Description

Function Documentation

◆ xTraceConsoleChannelPrintF()

traceResult xTraceConsoleChannelPrintF ( const char *  szFormat,
  ... 
)

Wrapper for vTracePrintF for printing to default channel.

Wrapper for vTracePrintF, using the default channel. Can be used as a drop-in replacement for printf and similar functions, e.g. in a debug logging macro.

Example: // Old: #define LogString debug_console_printf

// New, log to Tracealyzer instead: #define LogString xTraceConsoleChannelPrintF ... LogString("My value is: %d", myValue);

Parameters
[in]szFormatFormat
[in]...
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTracePrint()

traceResult xTracePrint ( TraceStringHandle_t  xChannel,
const char *  szString 
)

Generate "User Events" with unformatted text.

User Events can be used for very efficient application logging, and are shown as yellow labels in the main trace view.

You may group User Events into User Event Channels. The yellow User Event labels shows the logged string, preceded by the channel name within brackets. For example:

"[MyChannel] Hello World!"

The User Event Channels are shown in the View Filter, which makes it easy to select what User Events you wish to display. User Event Channels are created using xTraceStringRegister().

Example:

TraceStringHandle_t xChannel = xTraceStringRegister("MyChannel"); ... xTracePrint(xChannel, "Hello World!");

Parameters
[in]xChannelChannel.
[in]szStringString.
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTracePrintF()

traceResult xTracePrintF ( TraceStringHandle_t  xChannel,
const char *  szFormat,
  ... 
)

Generates "User Events" with formatted text and data.

Generates "User Events", with formatted text and data, similar to a "printf". It is very fast since the actual formatting is done on the host side when the trace is displayed.

User Events can be used for very efficient application logging, and are shown as yellow labels in the main trace view. An advantage of User Events is that data can be plotted in the "User Event Signal Plot" view, visualizing any data you log as User Events, discrete states or control system signals (e.g. system inputs or outputs).

You may group User Events into User Event Channels. The yellow User Event labels show the logged string, preceded by the channel name within brackets.

Example:

"[MyChannel] Hello World!"

The User Event Channels are shown in the View Filter, which makes it easy to select what User Events you wish to display. User Event Channels are created using xTraceStringRegister().

Example:

TraceStringHandle_t adc_uechannel = xTraceStringRegister("ADC User Events"); ... xTracePrintF(adc_uechannel, "ADC channel %d: %d volts", ch, adc_reading);

All data arguments are assumed to be 32 bit wide. The following formats are supported: d - signed integer. The following width and padding format is supported: "%05d" -> "-0042" and "%5d" -> " -42" u - unsigned integer. The following width and padding format is supported: "%05u" -> "00042" and "%5u" -> " 42" X - hexadecimal (uppercase). The following width and padding format is supported: "%04X" -> "002A" and "%4X" -> " 2A" x - hexadecimal (lowercase). The following width and padding format is supported: "%04x" -> "002a" and "%4x" -> " 2a" s - string (currently, this must be an earlier stored symbol name)

Up to 15 data arguments are allowed, with a total size of maximum 60 byte including 8 byte for the base event fields and the format string. So with one data argument, the maximum string length is 48 chars. If this is exceeded the string is truncated (4 bytes at a time).

Parameters
[in]xChannelChannel.
[in]szFormatFormat.
[in]...
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess

◆ xTraceVPrintF()

traceResult xTraceVPrintF ( TraceStringHandle_t  xChannel,
const char *  szFormat,
va_list  xVL 
)

Generates "User Events" with formatted text and data.

Parameters
[in]xChannelChannel.
[in]szFormatFormat.
[in]xVLVariable list arguments.
Return values
TRC_FAILFailure
TRC_SUCCESSSuccess