1 /* 2 * Trace Recorder for Tracealyzer v4.8.1 3 * Copyright 2023 Percepio AB 4 * www.percepio.com 5 * 6 * SPDX-License-Identifier: Apache-2.0 7 * 8 * Configuration parameters for trace recorder library in snapshot mode. 9 * Read more at http://percepio.com/2016/10/05/rtos-tracing/ 10 */ 11 12 #ifndef TRC_SNAPSHOT_CONFIG_H 13 #define TRC_SNAPSHOT_CONFIG_H 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * @def TRC_CFG_SNAPSHOT_MODE 21 * @brief Macro which should be defined as one of: 22 * - TRC_SNAPSHOT_MODE_RING_BUFFER 23 * - TRC_SNAPSHOT_MODE_STOP_WHEN_FULL 24 * Default is TRC_SNAPSHOT_MODE_RING_BUFFER. 25 * 26 * With TRC_CFG_SNAPSHOT_MODE set to TRC_SNAPSHOT_MODE_RING_BUFFER, the 27 * events are stored in a ring buffer, i.e., where the oldest events are 28 * overwritten when the buffer becomes full. This allows you to get the last 29 * events leading up to an interesting state, e.g., an error, without having 30 * to store the whole run since startup. 31 * 32 * When TRC_CFG_SNAPSHOT_MODE is TRC_SNAPSHOT_MODE_STOP_WHEN_FULL, the 33 * recording is stopped when the buffer becomes full. This is useful for 34 * recording events following a specific state, e.g., the startup sequence. 35 */ 36 #define TRC_CFG_SNAPSHOT_MODE TRC_SNAPSHOT_MODE_RING_BUFFER 37 38 /** 39 * @def TRC_CFG_EVENT_BUFFER_SIZE 40 * @brief Macro which should be defined as an integer value. 41 * 42 * This defines the capacity of the event buffer, i.e., the number of records 43 * it may store. Most events use one record (4 byte), although some events 44 * require multiple 4-byte records. You should adjust this to the amount of RAM 45 * available in the target system. 46 * 47 * Default value is 1000, which means that 4000 bytes is allocated for the 48 * event buffer. 49 */ 50 #define TRC_CFG_EVENT_BUFFER_SIZE 1000 51 52 /** 53 * @def TRC_CFG_INCLUDE_FLOAT_SUPPORT 54 * @brief Macro which should be defined as either zero (0) or one (1). 55 * 56 * If this is zero (0), the support for logging floating point values in 57 * vTracePrintF is stripped out, in case floating point values are not used or 58 * supported by the platform used. 59 * 60 * Floating point values are only used in vTracePrintF and its subroutines, to 61 * allow for storing float (%f) or double (%lf) arguments. 62 * 63 * vTracePrintF can be used with integer and string arguments in either case. 64 * 65 * Default value is 0. 66 */ 67 #define TRC_CFG_INCLUDE_FLOAT_SUPPORT 0 68 69 /** 70 * @def TRC_CFG_SYMBOL_TABLE_SIZE 71 * @brief Macro which should be defined as an integer value. 72 * 73 * This defines the capacity of the symbol table, in bytes. This symbol table 74 * stores User Events labels and names of deleted tasks, queues, or other kernel 75 * objects. If you don't use User Events or delete any kernel 76 * objects you set this to a very low value. The minimum recommended value is 4. 77 * A size of zero (0) is not allowed since a zero-sized array may result in a 78 * 32-bit pointer, i.e., using 4 bytes rather than 0. 79 * 80 * Default value is 800. 81 */ 82 #define TRC_CFG_SYMBOL_TABLE_SIZE 800 83 84 #if (TRC_CFG_SYMBOL_TABLE_SIZE == 0) 85 #error "TRC_CFG_SYMBOL_TABLE_SIZE may not be zero!" 86 #endif 87 88 /****************************************************************************** 89 *** ADVANCED SETTINGS ******************************************************** 90 ****************************************************************************** 91 * The remaining settings are not necessary to modify but allows for optimizing 92 * the recorder setup for your specific needs, e.g., to exclude events that you 93 * are not interested in, in order to get longer traces. 94 *****************************************************************************/ 95 96 /** 97 * @def TRC_CFG_HEAP_SIZE_BELOW_16M 98 * @brief An integer constant that can be used to reduce the buffer usage of memory 99 * allocation events (malloc/free). This value should be 1 if the heap size is 100 * below 16 MB (2^24 byte), and you can live with reported addresses showing the 101 * lower 24 bits only. If 0, you get the full 32-bit addresses. 102 * 103 * Default value is 0. 104 */ 105 #define TRC_CFG_HEAP_SIZE_BELOW_16M 0 106 107 /** 108 * @def TRC_CFG_USE_IMPLICIT_IFE_RULES 109 * @brief Macro which should be defined as either zero (0) or one (1). 110 * Default is 1. 111 * 112 * Tracealyzer groups the events into "instances" based on Instance Finish 113 * Events (IFEs), produced either by default rules or calls to the recorder 114 * functions xTraceTaskInstanceFinishedNow and xTraceTaskInstanceFinishedNext. 115 * 116 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is one (1), the default IFE rules is 117 * used, resulting in a "typical" grouping of events into instances. 118 * If these rules don't give appropriate instances in your case, you can 119 * override the default rules using xTraceTaskInstanceFinishedNow/Next for one 120 * or several tasks. The default IFE rules are then disabled for those tasks. 121 * 122 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is zero (0), the implicit IFE rules are 123 * disabled globally. You must then call xTraceTaskInstanceFinishedNow or 124 * xTraceTaskInstanceFinishedNext to manually group the events into instances, 125 * otherwise the tasks will appear a single long instance. 126 * 127 * The default IFE rules count the following events as "instance finished": 128 * - Task delay, delay until 129 * - Task suspend 130 * - Blocking on "input" operations, i.e., when the task is waiting for the 131 * next a message/signal/event. But only if this event is blocking. 132 */ 133 #define TRC_CFG_USE_IMPLICIT_IFE_RULES 1 134 135 /** 136 * @def TRC_CFG_USE_16BIT_OBJECT_HANDLES 137 * @brief Macro which should be defined as either zero (0) or one (1). 138 * 139 * If set to 0 (zero), the recorder uses 8-bit handles to identify kernel 140 * objects such as tasks and queues. This limits the supported number of 141 * concurrently active objects to 255 of each type (tasks, queues, mutexes, 142 * etc.) Note: 255, not 256, since handle 0 is reserved. 143 * 144 * If set to 1 (one), the recorder uses 16-bit handles to identify kernel 145 * objects such as tasks and queues. This limits the supported number of 146 * concurrent objects to 65535 of each type (object class). However, since the 147 * object property table is limited to 64 KB, the practical limit is about 148 * 3000 objects in total. 149 * 150 * Default is 0 (8-bit handles) 151 * 152 * NOTE: An object with handle above 255 will use an extra 4-byte record in 153 * the event buffer whenever the object is referenced. Moreover, some internal 154 * tables in the recorder gets slightly larger when using 16-bit handles. 155 */ 156 #define TRC_CFG_USE_16BIT_OBJECT_HANDLES 0 157 158 /** 159 * @def TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER 160 * @brief Macro which should be defined as an integer value. 161 * 162 * Set TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER to 1 to enable the 163 * separate user event buffer (UB). 164 * In this mode, user events are stored separately from other events, 165 * e.g., RTOS events. Thereby you can get a much longer history of 166 * user events as they don't need to share the buffer space with more 167 * frequent events. 168 * 169 * The UB is typically used with the snapshot ring-buffer mode, so the 170 * recording can continue when the main buffer gets full. And since the 171 * main buffer then overwrites the earliest events, Tracealyzer displays 172 * "Unknown Actor" instead of task scheduling for periods with UB data only. 173 * 174 * In UB mode, user events are structured as UB channels, which contains 175 * a channel name and a default format string. Register a UB channel using 176 * xTraceRegisterUBChannel. 177 * 178 * Events and data arguments are written using vTraceUBEvent and 179 * vTraceUBData. They are designed to provide efficient logging of 180 * repeating events, using the same format string within each channel. 181 * 182 * Examples: 183 * TraceStringHandle_t chn1; 184 * TraceStringHandle_t fmt1; 185 * xTraceStringRegister("Channel 1", &chn1); 186 * xTraceStringRegister("Event!", &fmt1); 187 * traceUBChannel UBCh1 = xTraceRegisterUBChannel(chn1, fmt1); 188 * 189 * TraceStringHandle_t chn2; 190 * TraceStringHandle_t fmt2; 191 * xTraceStringRegister("Channel 2", &chn2); 192 * xTraceStringRegister("X: %d, Y: %d", &fmt2); 193 * traceUBChannel UBCh2 = xTraceRegisterUBChannel(chn2, fmt2); 194 * 195 * // Result in "[Channel 1] Event!" 196 * vTraceUBEvent(UBCh1); 197 * 198 * // Result in "[Channel 2] X: 23, Y: 19" 199 * vTraceUBData(UBCh2, 23, 19); 200 * 201 * You can also use the other user event functions, like xTracePrintF. 202 * as they are then rerouted to the UB instead of the main event buffer. 203 * vTracePrintF then looks up the correct UB channel based on the 204 * provided channel name and format string, or creates a new UB channel 205 * if no match is found. The format string should therefore not contain 206 * "random" messages but mainly format specifiers. Random strings should 207 * be stored using %s and with the string as an argument. 208 * 209 * // Creates a new UB channel ("Channel 2", "%Z: %d") 210 * xTracePrintF(chn2, "%Z: %d", value1); 211 * 212 * // Finds the existing UB channel 213 * xTracePrintF(chn2, "%Z: %d", value2); 214 */ 215 #define TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER 0 216 217 /** 218 * @def TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE 219 * @brief Macro which should be defined as an integer value. 220 * 221 * This defines the capacity of the user event buffer (UB), in number of slots. 222 * A single user event can use multiple slots, depending on the arguments. 223 * 224 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1. 225 */ 226 #define TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE 200 227 228 /** 229 * @def TRC_CFG_UB_CHANNELS 230 * @brief Macro which should be defined as an integer value. 231 * 232 * This defines the number of User Event Buffer Channels (UB channels). 233 * These are used to structure the events when using the separate user 234 * event buffer, and contains both a User Event Channel (the name) and 235 * a default format string for the channel. 236 * 237 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1. 238 */ 239 #define TRC_CFG_UB_CHANNELS 32 240 241 #ifdef __cplusplus 242 } 243 #endif 244 245 #endif /*TRC_SNAPSHOT_CONFIG_H*/ 246
