1 /* 2 * Trace Recorder for Tracealyzer v4.5.1 3 * Copyright 2021 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 #define TRC_SNAPSHOT_MODE_RING_BUFFER (0x01) 16 #define TRC_SNAPSHOT_MODE_STOP_WHEN_FULL (0x02) 17 18 /****************************************************************************** 19 * TRC_CFG_SNAPSHOT_MODE 20 * 21 * 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 * TRC_CFG_EVENT_BUFFER_SIZE 40 * 41 * Macro which should be defined as an integer value. 42 * 43 * This defines the capacity of the event buffer, i.e., the number of records 44 * it may store. Most events use one record (4 byte), although some events 45 * require multiple 4-byte records. You should adjust this to the amount of RAM 46 * available in the target system. 47 * 48 * Default value is 1000, which means that 4000 bytes is allocated for the 49 * event buffer. 50 ******************************************************************************/ 51 #define TRC_CFG_EVENT_BUFFER_SIZE 1000 52 53 /******************************************************************************* 54 * TRC_CFG_NTASK, TRC_CFG_NISR, TRC_CFG_NQUEUE, TRC_CFG_NSEMAPHORE... 55 * 56 * A group of macros which should be defined as integer values, zero or larger. 57 * 58 * These define the capacity of the Object Property Table, i.e., the maximum 59 * number of objects active at any given point, within each object class (e.g., 60 * task, queue, semaphore, ...). 61 * 62 * If tasks or other objects are deleted in your system, this 63 * setting does not limit the total amount of objects created, only the number 64 * of objects that have been successfully created but not yet deleted. 65 * 66 * Using too small values will cause vTraceError to be called, which stores an 67 * error message in the trace that is shown when opening the trace file. The 68 * error message can also be retrieved using xTraceGetLastError. 69 * 70 * It can be wise to start with large values for these constants, 71 * unless you are very confident on these numbers. Then do a recording and 72 * check the actual usage by selecting View menu -> Trace Details -> 73 * Resource Usage -> Object Table. 74 ******************************************************************************/ 75 #define TRC_CFG_NTASK 15 76 #define TRC_CFG_NISR 5 77 #define TRC_CFG_NQUEUE 10 78 #define TRC_CFG_NSEMAPHORE 10 79 #define TRC_CFG_NMUTEX 10 80 #define TRC_CFG_NFLAG 5 81 #define TRC_CFG_NMEM 5 82 #define TRC_CFG_NTASK_SEM TRC_CFG_NTASK 83 #define TRC_CFG_NTASK_Q TRC_CFG_NTASK 84 85 /****************************************************************************** 86 * TRC_CFG_INCLUDE_FLOAT_SUPPORT 87 * 88 * Macro which should be defined as either zero (0) or one (1). 89 * 90 * If this is zero (0), the support for logging floating point values in 91 * vTracePrintF is stripped out, in case floating point values are not used or 92 * supported by the platform used. 93 * 94 * Floating point values are only used in vTracePrintF and its subroutines, to 95 * allow for storing float (%f) or double (%lf) arguments. 96 * 97 * vTracePrintF can be used with integer and string arguments in either case. 98 * 99 * Default value is 0. 100 *****************************************************************************/ 101 #define TRC_CFG_INCLUDE_FLOAT_SUPPORT 0 102 103 /******************************************************************************* 104 * TRC_CFG_SYMBOL_TABLE_SIZE 105 * 106 * Macro which should be defined as an integer value. 107 * 108 * This defines the capacity of the symbol table, in bytes. This symbol table 109 * stores User Events labels and names of deleted tasks, queues, or other kernel 110 * objects. If you don't use User Events or delete any kernel 111 * objects you set this to a very low value. The minimum recommended value is 4. 112 * A size of zero (0) is not allowed since a zero-sized array may result in a 113 * 32-bit pointer, i.e., using 4 bytes rather than 0. 114 * 115 * Default value is 800. 116 ******************************************************************************/ 117 #define TRC_CFG_SYMBOL_TABLE_SIZE 800 118 119 #if (TRC_CFG_SYMBOL_TABLE_SIZE == 0) 120 #error "TRC_CFG_SYMBOL_TABLE_SIZE may not be zero!" 121 #endif 122 123 /****************************************************************************** 124 * TRC_CFG_NAME_LEN_TASK, TRC_CFG_NAME_LEN_QUEUE, ... 125 * 126 * Macros that specify the maximum lengths (number of characters) for names of 127 * kernel objects, such as tasks and queues. If longer names are used, they will 128 * be truncated when stored in the recorder. 129 *****************************************************************************/ 130 #define TRC_CFG_NAME_LEN_TASK 15 131 #define TRC_CFG_NAME_LEN_ISR 15 132 #define TRC_CFG_NAME_LEN_QUEUE 15 133 #define TRC_CFG_NAME_LEN_SEMAPHORE 15 134 #define TRC_CFG_NAME_LEN_MUTEX 15 135 #define TRC_CFG_NAME_LEN_FLAG 32 136 #define TRC_CFG_NAME_LEN_MEM 32 137 #define TRC_CFG_NAME_LEN_TASK_SEM 32 138 #define TRC_CFG_NAME_LEN_TASK_Q 32 139 140 /****************************************************************************** 141 *** ADVANCED SETTINGS ******************************************************** 142 ****************************************************************************** 143 * The remaining settings are not necessary to modify but allows for optimizing 144 * the recorder setup for your specific needs, e.g., to exclude events that you 145 * are not interested in, in order to get longer traces. 146 *****************************************************************************/ 147 148 /****************************************************************************** 149 * TRC_CFG_HEAP_SIZE_BELOW_16M 150 * 151 * An integer constant that can be used to reduce the buffer usage of memory 152 * allocation events (malloc/free). This value should be 1 if the heap size is 153 * below 16 MB (2^24 byte), and you can live with reported addresses showing the 154 * lower 24 bits only. If 0, you get the full 32-bit addresses. 155 * 156 * Default value is 0. 157 ******************************************************************************/ 158 #define TRC_CFG_HEAP_SIZE_BELOW_16M 0 159 160 /****************************************************************************** 161 * TRC_CFG_USE_IMPLICIT_IFE_RULES 162 * 163 * Macro which should be defined as either zero (0) or one (1). 164 * Default is 1. 165 * 166 * Tracealyzer groups the events into "instances" based on Instance Finish 167 * Events (IFEs), produced either by default rules or calls to the recorder 168 * functions vTraceInstanceFinishedNow and vTraceInstanceFinishedNext. 169 * 170 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is one (1), the default IFE rules is 171 * used, resulting in a "typical" grouping of events into instances. 172 * If these rules don't give appropriate instances in your case, you can 173 * override the default rules using vTraceInstanceFinishedNow/Next for one 174 * or several tasks. The default IFE rules are then disabled for those tasks. 175 * 176 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is zero (0), the implicit IFE rules are 177 * disabled globally. You must then call vTraceInstanceFinishedNow or 178 * vTraceInstanceFinishedNext to manually group the events into instances, 179 * otherwise the tasks will appear a single long instance. 180 * 181 * The default IFE rules count the following events as "instance finished": 182 * - Task delay, delay until 183 * - Task suspend 184 * - Blocking on "input" operations, i.e., when the task is waiting for the 185 * next a message/signal/event. But only if this event is blocking. 186 * 187 * For details, see trcSnapshotKernelPort.h and look for references to the 188 * macro trcKERNEL_HOOKS_SET_TASK_INSTANCE_FINISHED. 189 *****************************************************************************/ 190 #define TRC_CFG_USE_IMPLICIT_IFE_RULES 1 191 192 /****************************************************************************** 193 * TRC_CFG_USE_16BIT_OBJECT_HANDLES 194 * 195 * Macro which should be defined as either zero (0) or one (1). 196 * 197 * If set to 0 (zero), the recorder uses 8-bit handles to identify kernel 198 * objects such as tasks and queues. This limits the supported number of 199 * concurrently active objects to 255 of each type (tasks, queues, mutexes, 200 * etc.) Note: 255, not 256, since handle 0 is reserved. 201 * 202 * If set to 1 (one), the recorder uses 16-bit handles to identify kernel 203 * objects such as tasks and queues. This limits the supported number of 204 * concurrent objects to 65535 of each type (object class). However, since the 205 * object property table is limited to 64 KB, the practical limit is about 206 * 3000 objects in total. 207 * 208 * Default is 0 (8-bit handles) 209 * 210 * NOTE: An object with handle above 255 will use an extra 4-byte record in 211 * the event buffer whenever the object is referenced. Moreover, some internal 212 * tables in the recorder gets slightly larger when using 16-bit handles. 213 *****************************************************************************/ 214 #define TRC_CFG_USE_16BIT_OBJECT_HANDLES 0 215 216 /****************************************************************************** 217 * TRC_CFG_USE_TRACE_ASSERT 218 * 219 * Macro which should be defined as either zero (0) or one (1). 220 * Default is 1. 221 * 222 * If this is one (1), the TRACE_ASSERT macro (used at various locations in the 223 * trace recorder) will verify that a relevant condition is true. 224 * If the condition is false, prvTraceError() will be called, which stops the 225 * recording and stores an error message that is displayed when opening the 226 * trace in Tracealyzer. 227 * 228 * This is used on several places in the recorder code for sanity checks on 229 * parameters. Can be switched off to reduce the footprint of the tracing, but 230 * we recommend to have it enabled initially. 231 *****************************************************************************/ 232 #define TRC_CFG_USE_TRACE_ASSERT 1 233 234 /******************************************************************************* 235 * TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER 236 * 237 * Macro which should be defined as an integer value. 238 * 239 * Set TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER to 1 to enable the 240 * separate user event buffer (UB). 241 * In this mode, user events are stored separately from other events, 242 * e.g., RTOS events. Thereby you can get a much longer history of 243 * user events as they don't need to share the buffer space with more 244 * frequent events. 245 * 246 * The UB is typically used with the snapshot ring-buffer mode, so the 247 * recording can continue when the main buffer gets full. And since the 248 * main buffer then overwrites the earliest events, Tracealyzer displays 249 * "Unknown Actor" instead of task scheduling for periods with UB data only. 250 * 251 * In UB mode, user events are structured as UB channels, which contains 252 * a channel name and a default format string. Register a UB channel using 253 * xTraceRegisterUBChannel. 254 * 255 * Events and data arguments are written using vTraceUBEvent and 256 * vTraceUBData. They are designed to provide efficient logging of 257 * repeating events, using the same format string within each channel. 258 * 259 * Examples: 260 * 261 * traceString chn1 = xTraceRegisterString("Channel 1"); 262 * traceString fmt1 = xTraceRegisterString("Event!"); 263 * traceUBChannel UBCh1 = xTraceRegisterUBChannel(chn1, fmt1); 264 * 265 * traceString chn2 = xTraceRegisterString("Channel 2"); 266 * traceString fmt2 = xTraceRegisterString("X: %d, Y: %d"); 267 * traceUBChannel UBCh2 = xTraceRegisterUBChannel(chn2, fmt2); 268 * 269 * // Result in "[Channel 1] Event!" 270 * vTraceUBEvent(UBCh1); 271 * 272 * // Result in "[Channel 2] X: 23, Y: 19" 273 * vTraceUBData(UBCh2, 23, 19); 274 * 275 * You can also use the other user event functions, like vTracePrintF. 276 * as they are then rerouted to the UB instead of the main event buffer. 277 * vTracePrintF then looks up the correct UB channel based on the 278 * provided channel name and format string, or creates a new UB channel 279 * if no match is found. The format string should therefore not contain 280 * "random" messages but mainly format specifiers. Random strings should 281 * be stored using %s and with the string as an argument. 282 * 283 * // Creates a new UB channel ("Channel 2", "%Z: %d") 284 * vTracePrintF(chn2, "%Z: %d", value1); 285 * 286 * // Finds the existing UB channel 287 * vTracePrintF(chn2, "%Z: %d", value2); 288 289 ******************************************************************************/ 290 #define TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER 0 291 292 /******************************************************************************* 293 * TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE 294 * 295 * Macro which should be defined as an integer value. 296 * 297 * This defines the capacity of the user event buffer (UB), in number of slots. 298 * A single user event can use multiple slots, depending on the arguments. 299 * 300 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1. 301 ******************************************************************************/ 302 #define TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE 200 303 304 /******************************************************************************* 305 * TRC_CFG_UB_CHANNELS 306 * 307 * Macro which should be defined as an integer value. 308 * 309 * This defines the number of User Event Buffer Channels (UB channels). 310 * These are used to structure the events when using the separate user 311 * event buffer, and contains both a User Event Channel (the name) and 312 * a default format string for the channel. 313 * 314 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1. 315 ******************************************************************************/ 316 #define TRC_CFG_UB_CHANNELS 32 317 318 /******************************************************************************* 319 * TRC_CFG_ISR_TAILCHAINING_THRESHOLD 320 * 321 * Macro which should be defined as an integer value. 322 * 323 * If tracing multiple ISRs, this setting allows for accurate display of the 324 * context-switching also in cases when the ISRs execute in direct sequence. 325 * 326 * vTraceStoreISREnd normally assumes that the ISR returns to the previous 327 * context, i.e., a task or a preempted ISR. But if another traced ISR 328 * executes in direct sequence, Tracealyzer may incorrectly display a minimal 329 * fragment of the previous context in between the ISRs. 330 * 331 * By using TRC_CFG_ISR_TAILCHAINING_THRESHOLD you can avoid this. This is 332 * however a threshold value that must be measured for your specific setup. 333 * See http://percepio.com/2014/03/21/isr_tailchaining_threshold/ 334 * 335 * The default setting is 0, meaning "disabled" and that you may get an 336 * extra fragments of the previous context in between tail-chained ISRs. 337 * 338 * Note: This setting has separate definitions in trcSnapshotConfig.h and 339 * trcStreamingConfig.h, since it is affected by the recorder mode. 340 ******************************************************************************/ 341 #define TRC_CFG_ISR_TAILCHAINING_THRESHOLD 0 342 343 #endif /*TRC_SNAPSHOT_CONFIG_H*/ 344
