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 * Main configuration parameters for the trace recorder library. 9 * More settings can be found in trcStreamingConfig.h and trcSnapshotConfig.h. 10 */ 11 12 #ifndef TRC_CONFIG_H 13 #define TRC_CONFIG_H 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 #include "sdkconfig.h" 20 #include "trcPortDefines.h" 21 22 23 /******************************************************************************* 24 * Configuration Macro: TRC_CFG_HARDWARE_PORT 25 * 26 * Specify what hardware port to use (i.e., the "timestamping driver"). 27 * 28 * All ARM Cortex-M MCUs are supported by "TRC_HARDWARE_PORT_ARM_Cortex_M". 29 * This port uses the DWT cycle counter for Cortex-M3/M4/M7 devices, which is 30 * available on most such devices. In case your device don't have DWT support, 31 * you will get an error message opening the trace. In that case, you may 32 * force the recorder to use SysTick timestamping instead, using this define: 33 * 34 * #define TRC_CFG_ARM_CM_USE_SYSTICK 35 * 36 * For ARM Cortex-M0/M0+ devices, SysTick mode is used automatically. 37 * 38 * See trcHardwarePort.h for available ports and information on how to 39 * define your own port, if not already present. 40 ******************************************************************************/ 41 #define TRC_CFG_HARDWARE_PORT TRC_HARDWARE_PORT_XTensa_LX6 42 43 /******************************************************************************* 44 * Configuration Macro: TRC_CFG_RECORDER_MODE 45 * 46 * Specify what recording mode to use. Snapshot means that the data is saved in 47 * an internal RAM buffer, for later upload. Streaming means that the data is 48 * transferred continuously to the host PC. 49 * 50 * For more information, see http://percepio.com/2016/10/05/rtos-tracing/ 51 * and the Tracealyzer User Manual. 52 * 53 * Values: 54 * TRC_RECORDER_MODE_SNAPSHOT 55 * TRC_RECORDER_MODE_STREAMING 56 ******************************************************************************/ 57 #if CONFIG_PERCEPIO_RECORDER_TRC_RECORDER_MODE_SNAPSHOT == 1 58 #define TRC_CFG_RECORDER_MODE TRC_RECORDER_MODE_SNAPSHOT 59 #else 60 #define TRC_CFG_RECORDER_MODE TRC_RECORDER_MODE_STREAMING 61 #endif 62 63 64 /****************************************************************************** 65 * TRC_CFG_ESP_IDF_VERSION 66 * 67 * Specify what version of ESP-IDF that is used 68 * 69 * TRC_ESP_IDF_VERSION_4_2_0 If using ESP-IDF v4.2.0 70 * TRC_ESP_IDF_VERSION_4_3_0 If using ESP-IDF v4.3.0 or later 71 *****************************************************************************/ 72 #define TRC_CFG_ESP_IDF_VERSION TRC_ESP_IDF_VERSION_4_3_0 73 74 /******************************************************************************* 75 * TRC_CFG_SCHEDULING_ONLY 76 * 77 * Macro which should be defined as an integer value. 78 * 79 * If this setting is enabled (= 1), only scheduling events are recorded. 80 * If disabled (= 0), all events are recorded (unless filtered in other ways). 81 * 82 * Default value is 0 (= include additional events). 83 ******************************************************************************/ 84 #define TRC_CFG_SCHEDULING_ONLY CONFIG_PERCEPIO_RECORDER_CFG_SCHEDULING_ONLY 85 86 /****************************************************************************** 87 * TRC_CFG_INCLUDE_MEMMANG_EVENTS 88 * 89 * Macro which should be defined as either zero (0) or one (1). 90 * 91 * This controls if malloc and free calls should be traced. Set this to zero (0) 92 * to exclude malloc/free calls, or one (1) to include such events in the trace. 93 * 94 * Default value is 1. 95 *****************************************************************************/ 96 #define TRC_CFG_INCLUDE_MEMMANG_EVENTS CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_MEMMANG_EVENTS 97 98 /****************************************************************************** 99 * TRC_CFG_INCLUDE_USER_EVENTS 100 * 101 * Macro which should be defined as either zero (0) or one (1). 102 * 103 * If this is zero (0), all code related to User Events is excluded in order 104 * to reduce code size. Any attempts of storing User Events are then silently 105 * ignored. 106 * 107 * User Events are application-generated events, like "printf" but for the 108 * trace log, generated using vTracePrint and vTracePrintF. 109 * The formatting is done on host-side, by Tracealyzer. User Events are 110 * therefore much faster than a console printf and can often be used 111 * in timing critical code without problems. 112 * 113 * Note: In streaming mode, User Events are used to provide error messages 114 * and warnings from the recorder (in case of incorrect configuration) for 115 * display in Tracealyzer. Disabling user events will also disable these 116 * warnings. You can however still catch them by calling xTraceGetLastError 117 * or by putting breakpoints in prvTraceError and prvTraceWarning. 118 * 119 * Default value is 1. 120 *****************************************************************************/ 121 #define TRC_CFG_INCLUDE_USER_EVENTS CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_USER_EVENTS 122 123 /***************************************************************************** 124 * TRC_CFG_INCLUDE_ISR_TRACING 125 * 126 * Macro which should be defined as either zero (0) or one (1). 127 * 128 * If this is zero (0), the code for recording Interrupt Service Routines is 129 * excluded, in order to reduce code size. This means that any calls to 130 * vTraceStoreISRBegin/vTraceStoreISREnd will be ignored. 131 * This does not completely disable ISR tracing, in cases where an ISR is 132 * calling a traced kernel service. These events will still be recorded and 133 * show up in anonymous ISR instances in Tracealyzer, with names such as 134 * "ISR sending to <queue name>". 135 * To disable such tracing, please refer to vTraceSetFilterGroup and 136 * vTraceSetFilterMask. 137 * 138 * Default value is 1. 139 * 140 * Note: tracing ISRs requires that you insert calls to vTraceStoreISRBegin 141 * and vTraceStoreISREnd in your interrupt handlers. 142 *****************************************************************************/ 143 #define TRC_CFG_INCLUDE_ISR_TRACING CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_ISR_TRACING 144 145 /***************************************************************************** 146 * TRC_CFG_INCLUDE_READY_EVENTS 147 * 148 * Macro which should be defined as either zero (0) or one (1). 149 * 150 * If one (1), events are recorded when tasks enter scheduling state "ready". 151 * This allows Tracealyzer to show the initial pending time before tasks enter 152 * the execution state, and present accurate response times. 153 * If zero (0), "ready events" are not created, which allows for recording 154 * longer traces in the same amount of RAM. 155 * 156 * Default value is 1. 157 *****************************************************************************/ 158 #define TRC_CFG_INCLUDE_READY_EVENTS CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_READY_EVENTS 159 160 /***************************************************************************** 161 * TRC_CFG_INCLUDE_OSTICK_EVENTS 162 * 163 * Macro which should be defined as either zero (0) or one (1). 164 * 165 * If this is one (1), events will be generated whenever the OS clock is 166 * increased. If zero (0), OS tick events are not generated, which allows for 167 * recording longer traces in the same amount of RAM. 168 * 169 * Default value is 1. 170 *****************************************************************************/ 171 #define TRC_CFG_INCLUDE_OSTICK_EVENTS CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_OSTICK_EVENTS 172 173 /***************************************************************************** 174 * TRC_CFG_INCLUDE_EVENT_GROUP_EVENTS 175 * 176 * Macro which should be defined as either zero (0) or one (1). 177 * 178 * If this is zero (0), the trace will exclude any "event group" events. 179 * 180 * Default value is 0 (excluded) since dependent on event_groups.c 181 *****************************************************************************/ 182 #define TRC_CFG_INCLUDE_EVENT_GROUP_EVENTS CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_EVENT_GROUP_EVENTS 183 184 /***************************************************************************** 185 * TRC_CFG_INCLUDE_TIMER_EVENTS 186 * 187 * Macro which should be defined as either zero (0) or one (1). 188 * 189 * If this is zero (0), the trace will exclude any Timer events. 190 * 191 * Default value is 0 since dependent on timers.c 192 *****************************************************************************/ 193 #define TRC_CFG_INCLUDE_TIMER_EVENTS CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_TIMER_EVENTS 194 195 /***************************************************************************** 196 * TRC_CFG_INCLUDE_PEND_FUNC_CALL_EVENTS 197 * 198 * Macro which should be defined as either zero (0) or one (1). 199 * 200 * If this is zero (0), the trace will exclude any "pending function call" 201 * events, such as xTimerPendFunctionCall(). 202 * 203 * Default value is 0 since dependent on timers.c 204 *****************************************************************************/ 205 #define TRC_CFG_INCLUDE_PEND_FUNC_CALL_EVENTS CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_PEND_FUNC_CALL_EVENTS 206 207 /******************************************************************************* 208 * Configuration Macro: TRC_CFG_INCLUDE_STREAM_BUFFER_EVENTS 209 * 210 * Macro which should be defined as either zero (0) or one (1). 211 * 212 * If this is zero (0), the trace will exclude any stream buffer or message 213 * buffer events. 214 * 215 * Default value is 0 since dependent on stream_buffer.c (new in FreeRTOS v10) 216 ******************************************************************************/ 217 #define TRC_CFG_INCLUDE_STREAM_BUFFER_EVENTS CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_STREAM_BUFFER_EVENTS 218 219 /****************************************************************************** 220 * TRC_CFG_ENABLE_STACK_MONITOR 221 * 222 * If enabled (1), the recorder periodically reports the unused stack space of 223 * all active tasks. 224 * The stack monitoring runs in the Tracealyzer Control task, TzCtrl. This task 225 * is always created by the recorder when in streaming mode. 226 * In snapshot mode, the TzCtrl task is only used for stack monitoring and is 227 * not created unless this is enabled. 228 *****************************************************************************/ 229 #define TRC_CFG_ENABLE_STACK_MONITOR CONFIG_PERCEPIO_RECORDER_CFG_ENABLE_STACK_MONITOR 230 231 /****************************************************************************** 232 * TRC_CFG_STACK_MONITOR_MAX_TASKS 233 * 234 * Macro which should be defined as a non-zero integer value. 235 * 236 * This controls how many tasks that can be monitored by the stack monitor. 237 * If this is too small, some tasks will be excluded and a warning is shown. 238 * 239 * Default value is 10. 240 *****************************************************************************/ 241 #define TRC_CFG_STACK_MONITOR_MAX_TASKS CONFIG_PERCEPIO_RECORDER_CFG_STACK_MONITOR_MAX_TASKS 242 243 /****************************************************************************** 244 * TRC_CFG_STACK_MONITOR_MAX_REPORTS 245 * 246 * Macro which should be defined as a non-zero integer value. 247 * 248 * This defines how many tasks that will be subject to stack usage analysis for 249 * each execution of the Tracealyzer Control task (TzCtrl). Note that the stack 250 * monitoring cycles between the tasks, so this does not affect WHICH tasks that 251 * are monitored, but HOW OFTEN each task stack is analyzed. 252 * 253 * This setting can be combined with TRC_CFG_CTRL_TASK_DELAY to tune the 254 * frequency of the stack monitoring. This is motivated since the stack analysis 255 * can take some time to execute. 256 * However, note that the stack analysis runs in a separate task (TzCtrl) that 257 * can be executed on low priority. This way, you can avoid that the stack 258 * analysis disturbs any time-sensitive tasks. 259 * 260 * Default value is 1. 261 *****************************************************************************/ 262 #define TRC_CFG_STACK_MONITOR_MAX_REPORTS CONFIG_PERCEPIO_RECORDER_CFG_STACK_MONITOR_MAX_REPORTS 263 264 /******************************************************************************* 265 * Configuration Macro: TRC_CFG_CTRL_TASK_PRIORITY 266 * 267 * The scheduling priority of the Tracealyzer Control (TzCtrl) task. 268 * 269 * In streaming mode, TzCtrl is used to receive start/stop commands from 270 * Tracealyzer and in some cases also to transmit the trace data (for stream 271 * ports that uses the internal buffer, like TCP/IP). For such stream ports, 272 * make sure the TzCtrl priority is high enough to ensure reliable periodic 273 * execution and transfer of the data, but low enough to avoid disturbing any 274 * time-sensitive functions. 275 * 276 * In Snapshot mode, TzCtrl is only used for the stack usage monitoring and is 277 * not created if stack monitoring is disabled. TRC_CFG_CTRL_TASK_PRIORITY should 278 * be low, to avoid disturbing any time-sensitive tasks. 279 ******************************************************************************/ 280 #define TRC_CFG_CTRL_TASK_PRIORITY CONFIG_PERCEPIO_RECORDER_CFG_CTRL_TASK_PRIORITY 281 282 /******************************************************************************* 283 * Configuration Macro: TRC_CFG_CTRL_TASK_DELAY 284 * 285 * The delay between loops of the TzCtrl task (see TRC_CFG_CTRL_TASK_PRIORITY), 286 * which affects the frequency of the stack monitoring. 287 * 288 * In streaming mode, this also affects the trace data transfer if you are using 289 * a stream port leveraging the internal buffer (like TCP/IP). A shorter delay 290 * increases the CPU load of TzCtrl somewhat, but may improve the performance of 291 * of the trace streaming, especially if the trace buffer is small. 292 ******************************************************************************/ 293 #define TRC_CFG_CTRL_TASK_DELAY CONFIG_PERCEPIO_RECORDER_CFG_CTRL_TASK_DELAY 294 295 /******************************************************************************* 296 * Configuration Macro: TRC_CFG_CTRL_TASK_STACK_SIZE 297 * 298 * The stack size of the Tracealyzer Control (TzCtrl) task. 299 * See TRC_CFG_CTRL_TASK_PRIORITY for further information about TzCtrl. 300 ******************************************************************************/ 301 #define TRC_CFG_CTRL_TASK_STACK_SIZE CONFIG_PERCEPIO_RECORDER_CFG_CTRL_TASK_STACK_SIZE 302 303 /******************************************************************************* 304 * Configuration Macro: TRC_CFG_RECORDER_BUFFER_ALLOCATION 305 * 306 * Specifies how the recorder buffer is allocated (also in case of streaming, in 307 * port using the recorder's internal temporary buffer) 308 * 309 * Values: 310 * TRC_RECORDER_BUFFER_ALLOCATION_STATIC - Static allocation (internal) 311 * TRC_RECORDER_BUFFER_ALLOCATION_DYNAMIC - Malloc in vTraceEnable 312 * TRC_RECORDER_BUFFER_ALLOCATION_CUSTOM - Use vTraceSetRecorderDataBuffer 313 * 314 * Static and dynamic mode does the allocation for you, either in compile time 315 * (static) or in runtime (malloc). 316 * The custom mode allows you to control how and where the allocation is made, 317 * for details see TRC_ALLOC_CUSTOM_BUFFER and vTraceSetRecorderDataBuffer(). 318 ******************************************************************************/ 319 #if CONFIG_PERCEPIO_RECORDER_TRC_RECORDER_BUFFER_ALLOCATION_STATIC == 1 320 #define TRC_CFG_RECORDER_BUFFER_ALLOCATION TRC_RECORDER_BUFFER_ALLOCATION_STATIC 321 #elif CONFIG_PERCEPIO_RECORDER_TRC_RECORDER_BUFFER_ALLOCATION_DYNAMIC == 1 322 #define TRC_CFG_RECORDER_BUFFER_ALLOCATION TRC_RECORDER_BUFFER_ALLOCATION_DYNAMIC 323 #else 324 #define TRC_CFG_RECORDER_BUFFER_ALLOCATION TRC_RECORDER_BUFFER_ALLOCATION_CUSTOM 325 #endif 326 327 /****************************************************************************** 328 * TRC_CFG_MAX_ISR_NESTING 329 * 330 * Defines how many levels of interrupt nesting the recorder can handle, in 331 * case multiple ISRs are traced and ISR nesting is possible. If this 332 * is exceeded, the particular ISR will not be traced and the recorder then 333 * logs an error message. This setting is used to allocate an internal stack 334 * for keeping track of the previous execution context (4 byte per entry). 335 * 336 * This value must be a non-zero positive constant, at least 1. 337 * 338 * Default value: 8 339 *****************************************************************************/ 340 #define TRC_CFG_MAX_ISR_NESTING CONFIG_PERCEPIO_RECORDER_CFG_MAX_ISR_NESTING 341 342 /****************************************************************************** 343 * TRC_CFG_ACKNOWLEDGE_QUEUE_SET_SEND 344 * 345 * When using FreeRTOS v10.3.0 or v10.3.1, please make sure that the trace 346 * point in prvNotifyQueueSetContainer() in queue.c is renamed from 347 * traceQUEUE_SEND to traceQUEUE_SET_SEND in order to tell them apart from 348 * other traceQUEUE_SEND trace points. Then set this to TRC_ACKNOWLEDGED. 349 *****************************************************************************/ 350 #define TRC_CFG_ACKNOWLEDGE_QUEUE_SET_SEND 0 /* TRC_ACKNOWLEDGED */ 351 352 /******************************************************************************* 353 * TRC_CFG_RECORDER_DATA_INIT 354 * 355 * Macro which states whether the recorder data should have an initial value. 356 * 357 * In very specific cases where traced objects are created before main(), 358 * the recorder will need to be started even before that. In these cases, 359 * the recorder data would be initialized by vTraceEnable(TRC_INIT) but could 360 * then later be overwritten by the initialization value. 361 * If this is an issue for you, set TRC_CFG_RECORDER_DATA_INIT to 0. 362 * The following code can then be used before any traced objects are created: 363 * 364 * extern uint32_t RecorderEnabled; 365 * RecorderEnabled = 0; 366 * vTraceInitialize(); 367 * 368 * After the clocks are properly initialized, use vTraceEnable(...) to start 369 * the tracing. 370 * 371 * Default value is 1. 372 ******************************************************************************/ 373 #define TRC_CFG_RECORDER_DATA_INIT 1 374 375 /****************************************************************************** 376 * TRC_CFG_RECORDER_DATA_ATTRIBUTE 377 * 378 * When setting TRC_CFG_RECORDER_DATA_INIT to 0, you might also need to make 379 * sure certain recorder data is placed in a specific RAM section to avoid being 380 * zeroed out after initialization. Define TRC_CFG_RECORDER_DATA_ATTRIBUTE as 381 * that attribute. 382 * 383 * Example: 384 * #define TRC_CFG_RECORDER_DATA_ATTRIBUTE __attribute__((section(".bss.trace_recorder_data"))) 385 * 386 * Default value is empty. 387 *****************************************************************************/ 388 #define TRC_CFG_RECORDER_DATA_ATTRIBUTE 389 390 /****************************************************************************** 391 * TRC_CFG_PLATFORM_NUM_CORES 392 * 393 * Specifies the number of cores available in the target MCU. 394 *****************************************************************************/ 395 #ifndef CONFIG_FREERTOS_UNICORE 396 #define TRC_CFG_PLATFORM_NUM_CORES 2 397 #endif 398 399 /* Specific configuration, depending on Streaming/Snapshot mode */ 400 #if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_SNAPSHOT) 401 #include "trcSnapshotConfig.h" 402 #elif (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 403 #include "trcStreamingConfig.h" 404 #endif 405 406 #ifdef __cplusplus 407 } 408 #endif 409 410 #endif /* _TRC_CONFIG_H */ 411
