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