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