1 /* 2 * Percepio Trace Recorder for Tracealyzer v4.6.6 3 * Copyright 2021 Percepio AB 4 * www.percepio.com 5 * 6 * SPDX-License-Identifier: Apache-2.0 7 */ 8 9 /** 10 * @file 11 * 12 * @brief Public trace print APIs. 13 */ 14 15 #ifndef TRC_PRINT_H 16 #define TRC_PRINT_H 17 18 #if (TRC_USE_TRACEALYZER_RECORDER == 1) 19 20 #if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 21 22 #include <stdarg.h> 23 #include <trcTypes.h> 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /** 30 * @defgroup trace_print_apis Trace Print APIs 31 * @ingroup trace_recorder_apis 32 * @{ 33 */ 34 35 #if (TRC_CFG_SCHEDULING_ONLY == 0) && (TRC_CFG_INCLUDE_USER_EVENTS == 1) 36 37 /** @internal */ 38 #define TRC_PRINT_BUFFER_SIZE (sizeof(TraceStringHandle_t) + sizeof(TraceStringHandle_t)) 39 40 /** 41 * @internal Trace Print Buffer Structure 42 */ 43 typedef struct TracePrintBuffer 44 { 45 uint32_t buffer[(TRC_PRINT_BUFFER_SIZE) / sizeof(uint32_t)]; 46 } TracePrintBuffer_t; 47 48 /** 49 * @internal Initialize print trace system. 50 * 51 * @param[in] pxBuffer Pointer to memory that will be used by the print 52 * trace system. 53 * 54 * @retval TRC_FAIL Failure 55 * @retval TRC_SUCCESS Success 56 */ 57 traceResult xTracePrintInitialize(TracePrintBuffer_t* pxBuffer); 58 59 /** 60 * @brief Generate "User Events" with unformatted text. 61 * 62 * User Events can be used for very efficient application logging, and are shown 63 * as yellow labels in the main trace view. 64 * 65 * You may group User Events into User Event Channels. The yellow User Event 66 * labels shows the logged string, preceded by the channel name within 67 * brackets. For example: 68 * 69 * "[MyChannel] Hello World!" 70 * 71 * The User Event Channels are shown in the View Filter, which makes it easy to 72 * select what User Events you wish to display. User Event Channels are created 73 * using xTraceStringRegister(). 74 * 75 * Example: 76 * 77 * TraceStringHandle_t xChannel = xTraceStringRegister("MyChannel"); 78 * ... 79 * xTracePrint(xChannel, "Hello World!"); 80 * 81 * @param[in] xChannel Channel. 82 * @param[in] szString String. 83 * 84 * @retval TRC_FAIL Failure 85 * @retval TRC_SUCCESS Success 86 */ 87 traceResult xTracePrint(TraceStringHandle_t xChannel, const char* szString); 88 89 /** 90 * @brief Wrapper for vTracePrintF for printing to default channel. 91 * 92 * Wrapper for vTracePrintF, using the default channel. Can be used as a drop-in 93 * replacement for printf and similar functions, e.g. in a debug logging macro. 94 * 95 * Example: 96 * // Old: #define LogString debug_console_printf 97 * 98 * // New, log to Tracealyzer instead: 99 * #define LogString xTraceConsoleChannelPrintF 100 * ... 101 * LogString("My value is: %d", myValue); 102 * 103 * @param[in] szFormat Format 104 * @param[in] ... 105 * 106 * @retval TRC_FAIL Failure 107 * @retval TRC_SUCCESS Success 108 */ 109 traceResult xTraceConsoleChannelPrintF(const char* szFormat, ...); 110 111 /** 112 * @brief Generates "User Events" with formatted text and data. 113 * 114 * Generates "User Events", with formatted text and data, similar to a "printf". 115 * It is very fast since the actual formatting is done on the host side when the 116 * trace is displayed. 117 * 118 * User Events can be used for very efficient application logging, and are shown 119 * as yellow labels in the main trace view. 120 * An advantage of User Events is that data can be plotted in the "User Event 121 * Signal Plot" view, visualizing any data you log as User Events, discrete 122 * states or control system signals (e.g. system inputs or outputs). 123 * 124 * You may group User Events into User Event Channels. The yellow User Event 125 * labels show the logged string, preceded by the channel name within brackets. 126 * 127 * Example: 128 * 129 * "[MyChannel] Hello World!" 130 * 131 * The User Event Channels are shown in the View Filter, which makes it easy to 132 * select what User Events you wish to display. User Event Channels are created 133 * using xTraceStringRegister(). 134 * 135 * Example: 136 * 137 * TraceStringHandle_t adc_uechannel = xTraceStringRegister("ADC User Events"); 138 * ... 139 * xTracePrintF(adc_uechannel, 140 * "ADC channel %d: %d volts", 141 * ch, adc_reading); 142 * 143 * All data arguments are assumed to be 32 bit wide. The following formats are 144 * supported: 145 * %d - signed integer. The following width and padding format is supported: "%05d" -> "-0042" and "%5d" -> " -42" 146 * %u - unsigned integer. The following width and padding format is supported: "%05u" -> "00042" and "%5u" -> " 42" 147 * %X - hexadecimal (uppercase). The following width and padding format is supported: "%04X" -> "002A" and "%4X" -> " 2A" 148 * %x - hexadecimal (lowercase). The following width and padding format is supported: "%04x" -> "002a" and "%4x" -> " 2a" 149 * %s - string (currently, this must be an earlier stored symbol name) 150 * 151 * Up to 15 data arguments are allowed, with a total size of maximum 60 byte 152 * including 8 byte for the base event fields and the format string. So with 153 * one data argument, the maximum string length is 48 chars. If this is exceeded 154 * the string is truncated (4 bytes at a time). 155 * 156 * @param[in] xChannel Channel. 157 * @param[in] szFormat Format. 158 * @param[in] ... 159 * 160 * @retval TRC_FAIL Failure 161 * @retval TRC_SUCCESS Success 162 */ 163 traceResult xTracePrintF(TraceStringHandle_t xChannel, const char* szFormat, ...); 164 165 /** 166 * @brief Generates "User Events" with formatted text and data. 167 * 168 * @param[in] xChannel Channel. 169 * @param[in] szFormat Format. 170 * @param[in] xVL Variable list arguments. 171 * 172 * @retval TRC_FAIL Failure 173 * @retval TRC_SUCCESS Success 174 */ 175 traceResult xTraceVPrintF(TraceStringHandle_t xChannel, const char* szFormat, va_list xVL); 176 177 #else /* (TRC_CFG_SCHEDULING_ONLY == 0) && (TRC_CFG_INCLUDE_USER_EVENTS == 1) */ 178 179 typedef struct TracePrintBuffer 180 { 181 uint32_t buffer[1]; 182 } TracePrintBuffer_t; 183 184 #define xTracePrintInitialize(p) ((void)p, p != 0 ? TRC_SUCCESS : TRC_FAIL) 185 186 #define xTracePrint(c, s) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)c, (void)s, TRC_SUCCESS) 187 188 #define xTracePrintF(c, s, ...) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)c, (void)s, TRC_SUCCESS) 189 190 #define xTraceConsoleChannelPrintF(s, ...) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)s, TRC_SUCCESS) 191 192 #define xTraceVPrintF(c, s, v) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)c, (void)s, (void)v, TRC_SUCCESS) 193 194 #endif /* (TRC_CFG_SCHEDULING_ONLY == 0) && (TRC_CFG_INCLUDE_USER_EVENTS == 1) */ 195 196 /** @} */ 197 198 #ifdef __cplusplus 199 } 200 #endif 201 202 #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ 203 204 #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ 205 206 207 #endif /* TRC_PRINT_H */ 208
