mirror of
https://github.com/FreeRTOS/FreeRTOS-Kernel.git
synced 2025-10-15 09:17:44 -04:00
3a2f6646f0
* Use new version of CI-CD Actions, checkout@v3 instead of checkout@v2 on all jobs * Use cSpell spell check, and use ubuntu-20.04 for formatting check * Add in bot formatting action * Update freertos_demo.yml and freertos_plus_demo.yml files to increase github log readability * Add in a Qemu demo onto the workflows.
213 lines
7 KiB
C
213 lines
7 KiB
C
/*
|
|
* Percepio Trace Recorder for Tracealyzer v4.6.0
|
|
* Copyright 2021 Percepio AB
|
|
* www.percepio.com
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
/**
|
|
* @file
|
|
*
|
|
* @brief Public trace print APIs.
|
|
*/
|
|
|
|
#ifndef TRC_PRINT_H
|
|
#define TRC_PRINT_H
|
|
|
|
#if ( TRC_USE_TRACEALYZER_RECORDER == 1 )
|
|
|
|
#if ( TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING )
|
|
|
|
#include <stdarg.h>
|
|
#include <trcTypes.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @defgroup trace_print_apis Trace Print APIs
|
|
* @ingroup trace_recorder_apis
|
|
* @{
|
|
*/
|
|
|
|
#if ( TRC_CFG_SCHEDULING_ONLY == 0 ) && ( TRC_CFG_INCLUDE_USER_EVENTS == 1 )
|
|
|
|
/** @internal */
|
|
#define TRC_PRINT_BUFFER_SIZE ( sizeof( TraceStringHandle_t ) + sizeof( TraceStringHandle_t ) )
|
|
|
|
/**
|
|
* @internal Trace Print Buffer Structure
|
|
*/
|
|
typedef struct TracePrintBuffer
|
|
{
|
|
uint32_t buffer[ ( TRC_PRINT_BUFFER_SIZE ) / sizeof( uint32_t ) ];
|
|
} TracePrintBuffer_t;
|
|
|
|
/**
|
|
* @internal Initialize print trace system.
|
|
*
|
|
* @param[in] pxBuffer Pointer to memory that will be used by the print
|
|
* trace system.
|
|
*
|
|
* @retval TRC_FAIL Failure
|
|
* @retval TRC_SUCCESS Success
|
|
*/
|
|
traceResult xTracePrintInitialize( TracePrintBuffer_t * pxBuffer );
|
|
|
|
/**
|
|
* @brief 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!");
|
|
*
|
|
* @param[in] xChannel Channel.
|
|
* @param[in] szString String.
|
|
*
|
|
* @retval TRC_FAIL Failure
|
|
* @retval TRC_SUCCESS Success
|
|
*/
|
|
traceResult xTracePrint( TraceStringHandle_t xChannel,
|
|
const char * szString );
|
|
|
|
/**
|
|
* @brief 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);
|
|
*
|
|
* @param[in] szFormat Format
|
|
* @param[in] ...
|
|
*
|
|
* @retval TRC_FAIL Failure
|
|
* @retval TRC_SUCCESS Success
|
|
*/
|
|
traceResult xTraceConsoleChannelPrintF( const char * szFormat,
|
|
... );
|
|
|
|
/**
|
|
* @brief 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).
|
|
*
|
|
* @param[in] xChannel Channel.
|
|
* @param[in] szFormat Format.
|
|
* @param[in] ...
|
|
*
|
|
* @retval TRC_FAIL Failure
|
|
* @retval TRC_SUCCESS Success
|
|
*/
|
|
traceResult xTracePrintF( TraceStringHandle_t xChannel,
|
|
const char * szFormat,
|
|
... );
|
|
|
|
/**
|
|
* @brief Generates "User Events" with formatted text and data.
|
|
*
|
|
* @param[in] xChannel Channel.
|
|
* @param[in] szFormat Format.
|
|
* @param[in] xVL Variable list arguments.
|
|
*
|
|
* @retval TRC_FAIL Failure
|
|
* @retval TRC_SUCCESS Success
|
|
*/
|
|
traceResult xTraceVPrintF( TraceStringHandle_t xChannel,
|
|
const char * szFormat,
|
|
va_list xVL );
|
|
|
|
#else /* (TRC_CFG_SCHEDULING_ONLY == 0) && (TRC_CFG_INCLUDE_USER_EVENTS == 1) */
|
|
|
|
typedef struct TracePrintBuffer
|
|
{
|
|
uint32_t buffer[ 1 ];
|
|
} TracePrintBuffer_t;
|
|
|
|
#define xTracePrintInitialize( p ) ( ( void ) p, p != 0 ? TRC_SUCCESS : TRC_FAIL )
|
|
|
|
#define xTracePrint( c, s ) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( ( void ) c, ( void ) s, TRC_SUCCESS )
|
|
|
|
#define xTracePrintF( c, s, ... ) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( ( void ) c, ( void ) s, TRC_SUCCESS )
|
|
|
|
#define xTraceConsoleChannelPrintF( s, ... ) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2( ( void ) s, TRC_SUCCESS )
|
|
|
|
#define xTraceVPrintF( c, s, v ) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4( ( void ) c, ( void ) s, ( void ) v, TRC_SUCCESS )
|
|
|
|
#endif /* (TRC_CFG_SCHEDULING_ONLY == 0) && (TRC_CFG_INCLUDE_USER_EVENTS == 1) */
|
|
|
|
/** @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */
|
|
|
|
#endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */
|
|
|
|
|
|
#endif /* TRC_PRINT_H */
|