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