1 /*******************************************************************************
\r
2 * FreeRTOS+Trace v2.3.0 Recorder Library
\r
3 * Percepio AB, www.percepio.com
\r
7 * Configuration parameters for the trace recorder library. Before using the
\r
8 * trace recorder library, please check that the default settings are
\r
9 * appropriate for your system, and if necessary adjust these. Most likely, you
\r
10 * will need to adjust the NTask, NISR, NQueue, NMutex and NSemaphore values to
\r
11 * reflect the number of such objects in your system. These may be
\r
12 * overapproximated, although larger values values implies more RAM usage.
\r
15 * This software is copyright Percepio AB. The recorder library is free for
\r
16 * use together with Percepio products. You may distribute the recorder library
\r
17 * in its original form, including modifications in trcPort.c and trcPort.h
\r
18 * given that these modification are clearly marked as your own modifications
\r
19 * and documented in the initial comment section of these source files.
\r
20 * This software is the intellectual property of Percepio AB and may not be
\r
21 * sold or in other ways commercially redistributed without explicit written
\r
22 * permission by Percepio AB.
\r
25 * The trace tool and recorder library is being delivered to you AS IS and
\r
26 * Percepio AB makes no warranty as to its use or performance. Percepio AB does
\r
27 * not and cannot warrant the performance or results you may obtain by using the
\r
28 * software or documentation. Percepio AB make no warranties, express or
\r
29 * implied, as to noninfringement of third party rights, merchantability, or
\r
30 * fitness for any particular purpose. In no event will Percepio AB, its
\r
31 * technology partners, or distributors be liable to you for any consequential,
\r
32 * incidental or special damages, including any lost profits or lost savings,
\r
33 * even if a representative of Percepio AB has been advised of the possibility
\r
34 * of such damages, or for any claim by any third party. Some jurisdictions do
\r
35 * not allow the exclusion or limitation of incidental, consequential or special
\r
36 * damages, or the exclusion of implied warranties or limitations on how long an
\r
37 * implied warranty may last, so the above limitations may not apply to you.
\r
39 * FreeRTOS+Trace is available as Free Edition and in two premium editions.
\r
40 * You may use the premium features during 30 days for evaluation.
\r
41 * Download FreeRTOS+Trace at http://www.percepio.com/products/downloads/
\r
43 * Copyright Percepio AB, 2012.
\r
45 ******************************************************************************/
\r
50 /*******************************************************************************
\r
51 * CONFIGURATION RELATED TO CAPACITY AND ALLOCATION
\r
52 ******************************************************************************/
\r
54 /*******************************************************************************
\r
57 * Macro which should be defined as an integer value.
\r
59 * This defines the capacity of the event buffer, i.e., the number of records
\r
60 * it may store. Each registered event typically use one record (4 byte), but
\r
61 * vTracePrintF may use multiple records depending on the number of data args.
\r
62 ******************************************************************************/
\r
64 #define EVENT_BUFFER_SIZE 10000 /* Adjust wrt. to available RAM */
\r
66 /*******************************************************************************
\r
69 * Macro which should be defined as an integer value.
\r
71 * This defines the capacity of the symbol table, in bytes. This symbol table
\r
72 * stores User Events labels and names of deleted tasks, queues, or other kernel
\r
73 * objects. Note that the names of active objects not stored here but in the
\r
74 * Object Table. Thus, if you don't use User Events or delete any kernel
\r
75 * objects you set this to zero (0) to minimize RAM usage.
\r
76 ******************************************************************************/
\r
77 #define SYMBOL_TABLE_SIZE 1000
\r
79 /*******************************************************************************
\r
80 * NTask, NISR, NQueue, NSemaphore, NMutex
\r
82 * A group of Macros which should be defined as an integer value of zero (0)
\r
85 * This defines the capacity of the Object Property Table - the maximum number
\r
86 * of objects active at any given point within each object class.
\r
88 * NOTE: In case objects are deleted and created during runtime, this setting
\r
89 * does not limit the total amount of objects, only the number of concurrently
\r
92 * Using too small values will give an error message through the vTraceError
\r
93 * routine, which makes the error message appear when opening the trace data
\r
94 * in FreeRTOS+Trace. If you are using the recorder status monitor task,
\r
95 * any error messages are displayed in console prints, assuming that the
\r
96 * print macro has been defined properly (vConsolePrintMessage).
\r
98 * It can be wise to start with very large values for these constants,
\r
99 * unless you are very confident on these numbers. Then do a recording and
\r
100 * check the actual usage in FreeRTOS+Trace. This is shown by selecting
\r
101 * View -> Trace Details -> Resource Usage -> Object Table
\r
103 * NOTE 2: Remember to account for all tasks created by FreeRTOS, such as the
\r
104 * IDLE task, the FreeRTOS timer task, and any tasks created by other 3rd party
\r
105 * software components, such as communication stacks. The recorder also has an
\r
106 * optional monitor task to account for, if this is used.
\r
107 * Moreover, one task slot is used to indicate "(startup)", i.e., a fictive
\r
108 * task that represent the time before the FreeRTOS scheduler starts.
\r
109 * NTask should thus be at least 2-3 slots larger than your application task count.
\r
111 * NOTE 3: The FreeRTOS timer task creates a Queue, that should be accounted
\r
113 ******************************************************************************/
\r
117 #define NSemaphore 10
\r
120 /* Maximum object name length for each class (includes zero termination) */
\r
121 #define NameLenTask configMAX_TASK_NAME_LEN
\r
122 #define NameLenISR 10
\r
123 #define NameLenQueue 15
\r
124 #define NameLenSemaphore 15
\r
125 #define NameLenMutex 15
\r
127 /******************************************************************************
\r
128 * TRACE_DESCRIPTION
\r
130 * Macro which should be defined as a string.
\r
132 * This string is stored in the trace and displayed in FreeRTOS+Trace. Can be
\r
133 * used to store, e.g., system version or build date. This is also used to store
\r
134 * internal error messages from the recorder, which if occurs overwrites the
\r
135 * value defined here. This may be maximum 256 chars.
\r
136 *****************************************************************************/
\r
137 #define TRACE_DESCRIPTION "FreeRTOS+Trace Demo"
\r
139 /******************************************************************************
\r
140 * TRACE_DESCRIPTION_MAX_LENGTH
\r
142 * The maximum length (including zero termination) for the TRACE_DESCRIPTION
\r
143 * string. Since this string also is used for internal error messages from the
\r
144 * recorder do not make it too short, as this may truncate the error messages.
\r
146 * Maximum allowed length is 256 - the trace will fail to load if longer.
\r
147 *****************************************************************************/
\r
148 #define TRACE_DESCRIPTION_MAX_LENGTH 80
\r
151 /******************************************************************************
\r
152 * TRACE_DATA_ALLOCATION
\r
154 * This defines how to allocate the recorder data structure, i.e., using a
\r
155 * static declaration or using a dynamic allocation in runtime (malloc).
\r
157 * Should be one of these two options:
\r
158 * - TRACE_DATA_ALLOCATION_STATIC (default)
\r
159 * - TRACE_DATA_ALLOCATION_DYNAMIC
\r
161 * Using static allocation has the benefits of compile-time errors if the buffer
\r
162 * is too large (too large constants in trcConfig.h) and no need to call the
\r
163 * initialization routine (xTraceInitTraceData).
\r
165 * Using dynamic allocation may give more flexibility in some cases.
\r
166 *****************************************************************************/
\r
168 #define TRACE_DATA_ALLOCATION TRACE_DATA_ALLOCATION_STATIC
\r
171 /******************************************************************************
\r
172 * CONFIGURATION REGARDING WHAT CODE/FEATURES TO INCLUDE
\r
173 *****************************************************************************/
\r
175 /******************************************************************************
\r
176 * INCLUDE_FLOAT_SUPPORT
\r
178 * Macro which should be defined as either zero (0) or one (1).
\r
181 * If this is zero (0), all references to floating point values are removed,
\r
182 * in case floating point values are not supported by the platform used.
\r
183 * Floating point values are only used in vTracePrintF and its subroutines, to
\r
184 * store float (%f) or double (%lf) argments.
\r
186 * Note: vTracePrintF can still be used with integer and string arguments in
\r
188 *****************************************************************************/
\r
189 #define INCLUDE_FLOAT_SUPPORT 1
\r
191 /******************************************************************************
\r
192 * INCLUDE_USER_EVENTS
\r
194 * Macro which should be defined as either zero (0) or one (1).
\r
197 * If this is zero (0) the code for creating User Events is excluded to
\r
198 * reduce code size. User Events are application-generated events, like
\r
199 * "printf" but for the trace log instead of console output. User Events are
\r
200 * much faster than a printf and can therefore be used in timing critical code.
\r
201 * See vTraceUserEvent() and vTracePrintF() in trcUser.h
\r
203 * Note that FreeRTOS+Trace Standard Edition or Professional Edition is required
\r
204 * for User Events, they are not displayed in FreeRTOS+Trace Free Edition.
\r
205 *****************************************************************************/
\r
206 #define INCLUDE_USER_EVENTS 1
\r
208 /*****************************************************************************
\r
209 * INCLUDE_READY_EVENTS
\r
211 * Macro which should be defined as either zero (0) or one (1).
\r
214 * If this is zero (0), the code for recording Ready events is
\r
215 * excluded. Note, this will make it impossible to calculate the correct
\r
217 *****************************************************************************/
\r
218 #define INCLUDE_READY_EVENTS 1
\r
220 /*****************************************************************************
\r
221 * INCLUDE_ISR_TRACING
\r
223 * Macro which should be defined as either zero (0) or one (1).
\r
226 * If this is zero (0), the code for recording Interrupt Service Routines is
\r
227 * excluded to reduce code size. Note, recording ISRs require that you insert
\r
228 * calls to vTraceStoreISRBegin and vTraceStoreISREnd in your interrupt handlers.
\r
229 * There is no automatic recording of ISRs like for task scheduling, since
\r
230 * FreeRTOS does not have a central interrupt dispatcher.
\r
231 *****************************************************************************/
\r
232 #define INCLUDE_ISR_TRACING 1
\r
234 /******************************************************************************
\r
235 * INCLUDE_OBJECT_DELETE
\r
237 * Macro which should be defined as either zero (0) or one (1).
\r
240 * This must be enabled (1) if tasks, queues or other
\r
241 * traced kernel objects are deleted at runtime, e.g., using vTaskDelete or
\r
242 * vQueueDelete. If no deletes are made, this can be set to 0 in order to
\r
243 * exclude the delete-handling code.
\r
244 *****************************************************************************/
\r
245 #ifdef INCLUDE_OBJECT_DELETE
\r
246 #undef INCLUDE_OBJECT_DELETE
\r
249 #define INCLUDE_OBJECT_DELETE 1
\r
251 /******************************************************************************
\r
252 * CONFIGURATION RELATED TO BEHAVIOR
\r
253 *****************************************************************************/
\r
255 /******************************************************************************
\r
256 * RECORDER_STORE_MODE
\r
258 * Macro which should be defined as one of:
\r
259 * - STORE_MODE_RING_BUFFER
\r
260 * - STORE_MODE_STOP_WHEN_FULL
\r
261 * Default is STORE_MODE_RING_BUFFER.
\r
263 * With RECORDER_STORE_MODE set to STORE_MODE_RING_BUFFER, the events are stored
\r
264 * in a ring buffer, i.e., where the oldest events are overwritten when the
\r
265 * buffer becomes full. This allows you to get the last events leading up to an
\r
266 * interesting state, e.g., an error, without having a large trace buffer for
\r
267 * string the whole run since startup. In this mode, the recorder can run
\r
268 * "forever" as the buffer never gets full, i.e., in the sense that it always
\r
269 * has room for more events.
\r
271 * To fetch the trace in mode STORE_MODE_RING_BUFFER, you need to first halt the
\r
272 * system using your debugger and then do a RAM dump, or to explicitly stop the
\r
273 * recorder using vTraceStop() and then store/upload the trace data using a
\r
274 * FreeRTOS task that you need to provide yourself. The trace data is found in
\r
275 * the struct RecorderData, initialized in trcBase.c.
\r
277 * Note that, if you upload the trace using a RAM dump, i.e., when the system is
\r
278 * halted on a breakpoint or by a debugger command, there is no need to stop the
\r
281 * When RECORDER_STORE_MODE is STORE_MODE_STOP_WHEN_FULL, the recording is
\r
282 * stopped when the buffer becomes full. When the recorder stops itself this way
\r
283 * vTracePortEnd() is called which allows for custom actions, such as triggering
\r
284 * a task that stores the trace buffer, i.e., in case taking a RAM dump
\r
285 * using an on-chip debugger is not possible. In the Windows port, vTracePortEnd
\r
286 * saves the trace to file directly, but this is not recommended in a real-time
\r
287 * system since the scheduler is blocked during the processing of vTracePortEnd.
\r
288 *****************************************************************************/
\r
290 #define RECORDER_STORE_MODE STORE_MODE_RING_BUFFER
\r
292 /* Default in the Win32 demo */
\r
293 #define RECORDER_STORE_MODE STORE_MODE_STOP_WHEN_FULL
\r
296 /******************************************************************************
\r
297 * STOP_AFTER_N_EVENTS
\r
299 * Macro which should be defined as an integer value, or not defined.
\r
302 * STOP_AFTER_N_EVENTS is intended for tests of the ring buffer mode (when
\r
303 * RECORDER_STORE_MODE is STORE_MODE_RING_BUFFER). It stops the recording when
\r
304 * the specified number of events has been observed. This value can be larger
\r
305 * than the buffer size, to allow for test of the "wrapping around" that occurs
\r
306 * in ring buffer mode . A negative value (or no definition of this macro)
\r
307 * disables this feature.
\r
308 *****************************************************************************/
\r
309 #define STOP_AFTER_N_EVENTS -1
\r
311 /******************************************************************************
\r
312 * USE_IMPLICIT_IFE_RULES
\r
314 * Macro which should be defined as either zero (0) or one (1).
\r
317 * ### Instance Finish Events (IFE) ###
\r
319 * For tasks with "infinite" main loops (non-terminating tasks), the concept
\r
320 * of a task instance has no clear definition, it is an application-specific
\r
321 * thing. FreeRTOS+Trace allows you to define Instance Finish Events (IFEs),
\r
322 * which marks the point in a cyclic task when the "task instance" ends.
\r
323 * The IFE is a blocking kernel call, typically in the main loop of a task
\r
324 * which typically reads a message queue, waits for a semaphore or performs
\r
325 * an explicit delay.
\r
327 * If USE_IMPLICIT_IFE_RULES is one (1), the following FreeRTOS kernel calls
\r
328 * are considered by default to be IFEs (Implicit IFEs):
\r
330 * - vTaskDelayUntil
\r
332 * - xQueueReceive (blocking cases only)
\r
333 * - xSemaphoreTake (blocking cases only)
\r
335 * However, Implicit IFEs only applies to blocking kernel calls. If an
\r
336 * xQueueReceive reads a message without blocking, it does not create a new
\r
337 * instance since no blocking occurred.
\r
339 * Moreover, the actual IFE might sometimes be another blocking call such as
\r
340 * xQueueSend or xSemaphoreGive. We therefore allow for user-defined
\r
341 * Explicit IFEs by calling
\r
343 * vTraceTaskInstanceIsFinished()
\r
345 * right before the kernel call considered as IFE. This does not create an
\r
346 * additional event but instead stores the service code and object handle
\r
347 * of the IFE call as properties of the task.
\r
349 * If using Explicit IFEs and the task also calls an Implicit IFE like
\r
350 * vTaskDelay, this may result in additional incorrect task instances.
\r
351 * This is solved by disabling the Implicit IFEs for the task, by adding
\r
354 * vTraceTaskSkipDefaultInstanceFinishedEvents()
\r
356 * in the very beginning of that task. This allows you to combine Explicit IFEs
\r
357 * for some tasks with Implicit IFEs for the rest of the tasks, if
\r
358 * USE_IMPLICIT_IFE_RULES is 1.
\r
360 * By setting USE_IMPLICIT_IFE_RULES to zero (0), the implicit IFEs are disabled
\r
361 * for all tasks. Tasks will then be considered to have a single instance only,
\r
362 * covering all execution fragments, unless you define an explicit IFE in each
\r
363 * task by calling vTraceTaskInstanceIsFinished before the blocking call.
\r
364 *****************************************************************************/
\r
365 #define USE_IMPLICIT_IFE_RULES 1
\r
367 /******************************************************************************
\r
368 * INCLUDE_SAVE_TO_FILE
\r
370 * Macro which should be defined as either zero (0) or one (1).
\r
373 * If enabled (1), the recorder will include code for saving the trace
\r
374 * to a local file system.
\r
375 ******************************************************************************/
\r
377 #define INCLUDE_SAVE_TO_FILE 1
\r
379 #define INCLUDE_SAVE_TO_FILE 0
\r
382 /******************************************************************************
\r
383 * TRACE_PROGRESS_MONITOR_TASK_PRIORITY
\r
385 * Macro which sets the priority of the "recorder status monitor" task.
\r
387 * This task, vTraceMonitorTask in trcUser.c, periodically writes
\r
388 * the recorder status using the vTraceConsoleMessage macro, which is to
\r
389 * be mapped to your console "printf" routine. The task is named TraceMon but
\r
390 * is intentionally excluded from the demo trace.
\r
392 * Default is tskIDLE_PRIORITY + 1
\r
393 * Note that if your system constantly has a high CPU load from high-priority
\r
394 * tasks, this might not be get a chance to execute.
\r
396 * See vTraceMonitorTask in trcUser.c
\r
397 *****************************************************************************/
\r
398 #define TRACE_PROGRESS_MONITOR_TASK_PRIORITY (tskIDLE_PRIORITY + 1)
\r
400 /******************************************************************************
\r
401 * TRACE_PROGRESS_MONITOR_TASK_STACKSIZE
\r
403 * Macro which sets the stack size of the "recorder status monitor" task.
\r
405 * This task, vTraceMonitorTask in trcUser.c, periodically writes
\r
406 * the recorder status using the vTraceConsoleMessage macro, which is to
\r
407 * be mapped to your console "printf" routine. The task is intentionally
\r
408 * excluded from the demo trace.
\r
410 * See vTraceMonitorTask in trcUser.c
\r
411 *****************************************************************************/
\r
412 #define TRACE_PROGRESS_MONITOR_TASK_STACKSIZE 500
\r
414 /******************************************************************************
\r
415 * TRACE_PROGRESS_MONITOR_TASK_PERIOD
\r
417 * Macro which sets the period of the "recorder status monitor" task.
\r
419 * This task, vTraceMonitorTask in trcUser.c, periodically writes
\r
420 * the recorder status using the vTraceConsoleMessage macro, which is to
\r
421 * be mapped to your console "printf" routine. The task is named TraceMon but
\r
422 * is intentionally excluded from the demo trace.
\r
424 * Default is 1000 FreeRTOS ticks (typically 1 second). On the Windows port, a
\r
425 * lower value is suggested since the Windows port runs very slowly, often 20-40
\r
426 * times slower than the simulated FreeRTOS time.
\r
428 * See vTraceMonitorTask in trcUser.c
\r
429 *****************************************************************************/
\r
431 #define TRACE_PROGRESS_MONITOR_TASK_PERIOD 100
\r
433 #define TRACE_PROGRESS_MONITOR_TASK_PERIOD 1000
\r
436 /******************************************************************************
\r
437 * TEAM_LICENSE_CODE
\r
439 * Macro which defines a string - the team license code.
\r
440 * If no team license is available, this should be an empty string "".
\r
441 * This should be maximum 32 chars, including zero-termination.
\r
442 *****************************************************************************/
\r
443 #define TEAM_LICENSE_CODE ""
\r