1 /*******************************************************************************
\r
2 * Trace Recorder Library for Tracealyzer v3.1.2
\r
3 * Percepio AB, www.percepio.com
\r
5 * trcSnapshotConfig.h
\r
7 * Configuration parameters for trace recorder library in snapshot mode.
\r
8 * Read more at http://percepio.com/2016/10/05/rtos-tracing/
\r
11 * This file is part of the trace recorder library (RECORDER), which is the
\r
12 * intellectual property of Percepio AB (PERCEPIO) and provided under a
\r
13 * license as follows.
\r
14 * The RECORDER may be used free of charge for the purpose of recording data
\r
15 * intended for analysis in PERCEPIO products. It may not be used or modified
\r
16 * for other purposes without explicit permission from PERCEPIO.
\r
17 * You may distribute the RECORDER in its original source code form, assuming
\r
18 * this text (terms of use, disclaimer, copyright notice) is unchanged. You are
\r
19 * allowed to distribute the RECORDER with minor modifications intended for
\r
20 * configuration or porting of the RECORDER, e.g., to allow using it on a
\r
21 * specific processor, processor family or with a specific communication
\r
22 * interface. Any such modifications should be documented directly below
\r
23 * this comment block.
\r
26 * The RECORDER is being delivered to you AS IS and PERCEPIO makes no warranty
\r
27 * as to its use or performance. PERCEPIO does not and cannot warrant the
\r
28 * performance or results you may obtain by using the RECORDER or documentation.
\r
29 * PERCEPIO make no warranties, express or implied, as to noninfringement of
\r
30 * third party rights, merchantability, or fitness for any particular purpose.
\r
31 * In no event will PERCEPIO, its technology partners, or distributors be liable
\r
32 * to you for any consequential, incidental or special damages, including any
\r
33 * lost profits or lost savings, even if a representative of PERCEPIO has been
\r
34 * advised of the possibility of such damages, or for any claim by any third
\r
35 * party. Some jurisdictions do not allow the exclusion or limitation of
\r
36 * incidental, consequential or special damages, or the exclusion of implied
\r
37 * warranties or limitations on how long an implied warranty may last, so the
\r
38 * above limitations may not apply to you.
\r
40 * Tabs are used for indent in this file (1 tab = 4 spaces)
\r
42 * Copyright Percepio AB, 2017.
\r
44 ******************************************************************************/
\r
46 #ifndef TRC_SNAPSHOT_CONFIG_H
\r
47 #define TRC_SNAPSHOT_CONFIG_H
\r
49 #define TRC_SNAPSHOT_MODE_RING_BUFFER (0x01)
\r
50 #define TRC_SNAPSHOT_MODE_STOP_WHEN_FULL (0x02)
\r
52 /******************************************************************************
\r
53 * TRC_CFG_SNAPSHOT_MODE
\r
55 * Macro which should be defined as one of:
\r
56 * - TRC_SNAPSHOT_MODE_RING_BUFFER
\r
57 * - TRC_SNAPSHOT_MODE_STOP_WHEN_FULL
\r
58 * Default is TRC_SNAPSHOT_MODE_RING_BUFFER.
\r
60 * With TRC_CFG_SNAPSHOT_MODE set to TRC_SNAPSHOT_MODE_RING_BUFFER, the
\r
61 * events are stored in a ring buffer, i.e., where the oldest events are
\r
62 * overwritten when the buffer becomes full. This allows you to get the last
\r
63 * events leading up to an interesting state, e.g., an error, without having
\r
64 * to store the whole run since startup.
\r
66 * When TRC_CFG_SNAPSHOT_MODE is TRC_SNAPSHOT_MODE_STOP_WHEN_FULL, the
\r
67 * recording is stopped when the buffer becomes full. This is useful for
\r
68 * recording events following a specific state, e.g., the startup sequence.
\r
69 *****************************************************************************/
\r
70 #define TRC_CFG_SNAPSHOT_MODE TRC_SNAPSHOT_MODE_RING_BUFFER
\r
72 /*******************************************************************************
\r
73 * TRC_CFG_SCHEDULING_ONLY
\r
75 * Macro which should be defined as an integer value.
\r
77 * If this setting is enabled (= 1), only scheduling events are recorded.
\r
78 * If disabled (= 0), all events are recorded.
\r
80 * For users of Tracealyzer Free Edition, that only displays scheduling events, this
\r
81 * option can be used to avoid storing other events.
\r
83 * Default value is 0 (store all enabled events).
\r
85 ******************************************************************************/
\r
86 #define TRC_CFG_SCHEDULING_ONLY 0
\r
88 /*******************************************************************************
\r
89 * TRC_CFG_EVENT_BUFFER_SIZE
\r
91 * Macro which should be defined as an integer value.
\r
93 * This defines the capacity of the event buffer, i.e., the number of records
\r
94 * it may store. Most events use one record (4 byte), although some events
\r
95 * require multiple 4-byte records. You should adjust this to the amount of RAM
\r
96 * available in the target system.
\r
98 * Default value is 1000, which means that 4000 bytes is allocated for the
\r
100 ******************************************************************************/
\r
101 #define TRC_CFG_EVENT_BUFFER_SIZE 15000
\r
103 /*******************************************************************************
\r
104 * TRC_CFG_NTASK, TRC_CFG_NISR, TRC_CFG_NQUEUE, TRC_CFG_NSEMAPHORE...
\r
106 * A group of macros which should be defined as integer values, zero or larger.
\r
108 * These define the capacity of the Object Property Table, i.e., the maximum
\r
109 * number of objects active at any given point, within each object class (e.g.,
\r
110 * task, queue, semaphore, ...).
\r
112 * If tasks or other objects are deleted in your system, this
\r
113 * setting does not limit the total amount of objects created, only the number
\r
114 * of objects that have been successfully created but not yet deleted.
\r
116 * Using too small values will cause vTraceError to be called, which stores an
\r
117 * error message in the trace that is shown when opening the trace file. The
\r
118 * error message can also be retrieved using xTraceGetLastError.
\r
120 * It can be wise to start with large values for these constants,
\r
121 * unless you are very confident on these numbers. Then do a recording and
\r
122 * check the actual usage by selecting View menu -> Trace Details ->
\r
123 * Resource Usage -> Object Table.
\r
124 ******************************************************************************/
\r
125 #define TRC_CFG_NTASK 150
\r
126 #define TRC_CFG_NISR 90
\r
127 #define TRC_CFG_NQUEUE 90
\r
128 #define TRC_CFG_NSEMAPHORE 90
\r
129 #define TRC_CFG_NMUTEX 90
\r
130 #define TRC_CFG_NTIMER 250
\r
131 #define TRC_CFG_NEVENTGROUP 90
\r
133 /******************************************************************************
\r
134 * TRC_CFG_INCLUDE_MEMMANG_EVENTS
\r
136 * Macro which should be defined as either zero (0) or one (1).
\r
138 * This controls if malloc and free calls should be traced. Set this to zero (0)
\r
139 * to exclude malloc/free calls, or one (1) to include such events in the trace.
\r
141 * Default value is 1.
\r
142 *****************************************************************************/
\r
143 #define TRC_CFG_INCLUDE_MEMMANG_EVENTS 1
\r
145 /******************************************************************************
\r
146 * TRC_CFG_INCLUDE_USER_EVENTS
\r
148 * Macro which should be defined as either zero (0) or one (1).
\r
150 * If this is zero (0) the code for creating User Events is excluded to
\r
151 * reduce code size. User Events are application-generated events, like
\r
152 * "printf" but for the trace log and the formatting is done offline, by the
\r
153 * Tracealyzer visualization tool. User Events are much faster than a printf
\r
154 * and can therefore be used in timing critical code.
\r
156 * Default value is 1.
\r
157 *****************************************************************************/
\r
158 #define TRC_CFG_INCLUDE_USER_EVENTS 1
\r
160 /*****************************************************************************
\r
161 * TRC_CFG_INCLUDE_ISR_TRACING
\r
163 * Macro which should be defined as either zero (0) or one (1).
\r
165 * If this is zero (0), the code for recording Interrupt Service Routines is
\r
166 * excluded, in order to reduce code size.
\r
168 * Default value is 1.
\r
170 * Note: tracing ISRs requires that you insert calls to vTraceStoreISRBegin
\r
171 * and vTraceStoreISREnd in your interrupt handlers.
\r
172 *****************************************************************************/
\r
173 #define TRC_CFG_INCLUDE_ISR_TRACING 1
\r
175 /*****************************************************************************
\r
176 * TRC_CFG_INCLUDE_READY_EVENTS
\r
178 * Macro which should be defined as either zero (0) or one (1).
\r
180 * If one (1), events are recorded when tasks enter scheduling state "ready".
\r
181 * This allows Tracealyzer to show the initial pending time before tasks enter
\r
182 * the execution state, and present accurate response times.
\r
183 * If zero (0), "ready events" are not created, which allows for recording
\r
184 * longer traces in the same amount of RAM.
\r
186 * Default value is 1.
\r
187 *****************************************************************************/
\r
188 #define TRC_CFG_INCLUDE_READY_EVENTS 1
\r
190 /*****************************************************************************
\r
191 * TRC_CFG_INCLUDE_OSTICK_EVENTS
\r
193 * Macro which should be defined as either zero (0) or one (1).
\r
195 * If this is one (1), events will be generated whenever the OS clock is
\r
196 * increased. If zero (0), OS tick events are not generated, which allows for
\r
197 * recording longer traces in the same amount of RAM.
\r
199 * Default value is 0.
\r
200 *****************************************************************************/
\r
201 #define TRC_CFG_INCLUDE_OSTICK_EVENTS 1
\r
203 /******************************************************************************
\r
204 * TRC_CFG_INCLUDE_FLOAT_SUPPORT
\r
206 * Macro which should be defined as either zero (0) or one (1).
\r
208 * If this is zero (0), the support for logging floating point values in
\r
209 * vTracePrintF is stripped out, in case floating point values are not used or
\r
210 * supported by the platform used.
\r
212 * Floating point values are only used in vTracePrintF and its subroutines, to
\r
213 * allow for storing float (%f) or double (%lf) arguments.
\r
215 * vTracePrintF can be used with integer and string arguments in either case.
\r
217 * Default value is 0.
\r
218 *****************************************************************************/
\r
219 #define TRC_CFG_INCLUDE_FLOAT_SUPPORT 0
\r
221 /******************************************************************************
\r
222 * TRC_CFG_INCLUDE_OBJECT_DELETE
\r
224 * Macro which should be defined as either zero (0) or one (1).
\r
226 * This must be enabled (1) if tasks, queues or other
\r
227 * traced kernel objects are deleted at runtime. If no deletes are made, this
\r
228 * can be set to 0 in order to exclude the delete-handling code.
\r
230 * Default value is 1.
\r
231 *****************************************************************************/
\r
232 #define TRC_CFG_INCLUDE_OBJECT_DELETE 1
\r
234 /*******************************************************************************
\r
235 * TRC_CFG_SYMBOL_TABLE_SIZE
\r
237 * Macro which should be defined as an integer value.
\r
239 * This defines the capacity of the symbol table, in bytes. This symbol table
\r
240 * stores User Events labels and names of deleted tasks, queues, or other kernel
\r
241 * objects. If you don't use User Events or delete any kernel
\r
242 * objects you set this to a very low value. The minimum recommended value is 4.
\r
243 * A size of zero (0) is not allowed since a zero-sized array may result in a
\r
244 * 32-bit pointer, i.e., using 4 bytes rather than 0.
\r
246 * Default value is 800.
\r
247 ******************************************************************************/
\r
248 #define TRC_CFG_SYMBOL_TABLE_SIZE 5000
\r
250 #if (TRC_CFG_SYMBOL_TABLE_SIZE == 0)
\r
251 #error "TRC_CFG_SYMBOL_TABLE_SIZE may not be zero!"
\r
254 /******************************************************************************
\r
255 * TRC_CFG_NAME_LEN_TASK, TRC_CFG_NAME_LEN_QUEUE, ...
\r
257 * Macros that specify the maximum lengths (number of characters) for names of
\r
258 * kernel objects, such as tasks and queues. If longer names are used, they will
\r
259 * be truncated when stored in the recorder.
\r
260 *****************************************************************************/
\r
261 #define TRC_CFG_NAME_LEN_TASK 15
\r
262 #define TRC_CFG_NAME_LEN_ISR 15
\r
263 #define TRC_CFG_NAME_LEN_QUEUE 15
\r
264 #define TRC_CFG_NAME_LEN_SEMAPHORE 15
\r
265 #define TRC_CFG_NAME_LEN_MUTEX 15
\r
266 #define TRC_CFG_NAME_LEN_TIMER 15
\r
267 #define TRC_CFG_NAME_LEN_EVENTGROUP 15
\r
269 /******************************************************************************
\r
270 *** ADVANCED SETTINGS ********************************************************
\r
271 ******************************************************************************
\r
272 * The remaining settings are not necessary to modify but allows for optimizing
\r
273 * the recorder setup for your specific needs, e.g., to exclude events that you
\r
274 * are not interested in, in order to get longer traces.
\r
275 *****************************************************************************/
\r
277 /******************************************************************************
\r
278 * TRC_CFG_HEAP_SIZE_BELOW_16M
\r
280 * An integer constant that can be used to reduce the buffer usage of memory
\r
281 * allocation events (malloc/free). This value should be 1 if the heap size is
\r
282 * below 16 MB (2^24 byte), and you can live with reported addresses showing the
\r
283 * lower 24 bits only. If 0, you get the full 32-bit addresses.
\r
285 * Default value is 0.
\r
286 ******************************************************************************/
\r
287 #define TRC_CFG_HEAP_SIZE_BELOW_16M 0
\r
289 /******************************************************************************
\r
290 * TRC_CFG_USE_IMPLICIT_IFE_RULES
\r
292 * Macro which should be defined as either zero (0) or one (1).
\r
295 * Tracealyzer groups the events into "instances" based on Instance Finish
\r
296 * Events (IFEs), produced either by default rules or calls to the recorder
\r
297 * functions vTraceInstanceFinishedNow and vTraceInstanceFinishedNext.
\r
299 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is one (1), the default IFE rules is
\r
300 * used, resulting in a "typical" grouping of events into instances.
\r
301 * If these rules don't give appropriate instances in your case, you can
\r
302 * override the default rules using vTraceInstanceFinishedNow/Next for one
\r
303 * or several tasks. The default IFE rules are then disabled for those tasks.
\r
305 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is zero (0), the implicit IFE rules are
\r
306 * disabled globally. You must then call vTraceInstanceFinishedNow or
\r
307 * vTraceInstanceFinishedNext to manually group the events into instances,
\r
308 * otherwise the tasks will appear a single long instance.
\r
310 * The default IFE rules count the following events as "instance finished":
\r
311 * - Task delay, delay until
\r
313 * - Blocking on "input" operations, i.e., when the task is waiting for the
\r
314 * next a message/signal/event. But only if this event is blocking.
\r
316 * For details, see trcSnapshotKernelPort.h and look for references to the
\r
317 * macro trcKERNEL_HOOKS_SET_TASK_INSTANCE_FINISHED.
\r
318 *****************************************************************************/
\r
319 #define TRC_CFG_USE_IMPLICIT_IFE_RULES 1
\r
321 /******************************************************************************
\r
322 * TRC_CFG_USE_16BIT_OBJECT_HANDLES
\r
324 * Macro which should be defined as either zero (0) or one (1).
\r
326 * If set to 0 (zero), the recorder uses 8-bit handles to identify kernel
\r
327 * objects such as tasks and queues. This limits the supported number of
\r
328 * concurrently active objects to 255 of each type (tasks, queues, mutexes,
\r
329 * etc.) Note: 255, not 256, since handle 0 is reserved.
\r
331 * If set to 1 (one), the recorder uses 16-bit handles to identify kernel
\r
332 * objects such as tasks and queues. This limits the supported number of
\r
333 * concurrent objects to 65535 of each type (object class). However, since the
\r
334 * object property table is limited to 64 KB, the practical limit is about
\r
335 * 3000 objects in total.
\r
337 * Default is 0 (8-bit handles)
\r
339 * NOTE: An object with handle above 255 will use an extra 4-byte record in
\r
340 * the event buffer whenever the object is referenced. Moreover, some internal
\r
341 * tables in the recorder gets slightly larger when using 16-bit handles.
\r
342 *****************************************************************************/
\r
343 #define TRC_CFG_USE_16BIT_OBJECT_HANDLES 0
\r
345 /******************************************************************************
\r
346 * TRC_CFG_USE_TRACE_ASSERT
\r
348 * Macro which should be defined as either zero (0) or one (1).
\r
351 * If this is one (1), the TRACE_ASSERT macro (used at various locations in the
\r
352 * trace recorder) will verify that a relevant condition is true.
\r
353 * If the condition is false, prvTraceError() will be called, which stops the
\r
354 * recording and stores an error message that is displayed when opening the
\r
355 * trace in Tracealyzer.
\r
357 * This is used on several places in the recorder code for sanity checks on
\r
358 * parameters. Can be switched off to reduce the footprint of the tracing, but
\r
359 * we recommend to have it enabled initially.
\r
360 *****************************************************************************/
\r
361 #define TRC_CFG_USE_TRACE_ASSERT 1
\r
363 /*******************************************************************************
\r
364 * TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER
\r
366 * Macro which should be defined as an integer value.
\r
368 * Set TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER to 1 to enable the
\r
369 * separate user event buffer (UB).
\r
370 * In this mode, user events are stored separately from other events,
\r
371 * e.g., RTOS events. Thereby you can get a much longer history of
\r
372 * user events as they don't need to share the buffer space with more
\r
375 * The UB is typically used with the snapshot ring-buffer mode, so the
\r
376 * recording can continue when the main buffer gets full. And since the
\r
377 * main buffer then overwrites the earliest events, Tracealyzer displays
\r
378 * "Unknown Actor" instead of task scheduling for periods with UB data only.
\r
380 * In UB mode, user events are structured as UB channels, which contains
\r
381 * a channel name and a default format string. Register a UB channel using
\r
382 * xTraceRegisterUBChannel.
\r
384 * Events and data arguments are written using vTraceUBEvent and
\r
385 * vTraceUBData. They are designed to provide efficient logging of
\r
386 * repeating events, using the same format string within each channel.
\r
390 * traceString chn1 = xTraceRegisterString("Channel 1");
\r
391 * traceString fmt1 = xTraceRegisterString("Event!");
\r
392 * traceUBChannel UBCh1 = xTraceRegisterUBChannel(chn1, fmt1);
\r
394 * traceString chn2 = xTraceRegisterString("Channel 2");
\r
395 * traceString fmt2 = xTraceRegisterString("X: %d, Y: %d");
\r
396 * traceUBChannel UBCh2 = xTraceRegisterUBChannel(chn2, fmt2);
\r
398 * // Result in "[Channel 1] Event!"
\r
399 * vTraceUBEvent(UBCh1);
\r
401 * // Result in "[Channel 2] X: 23, Y: 19"
\r
402 * vTraceUBData(UBCh2, 23, 19);
\r
404 * You can also use the other user event functions, like vTracePrintF.
\r
405 * as they are then rerouted to the UB instead of the main event buffer.
\r
406 * vTracePrintF then looks up the correct UB channel based on the
\r
407 * provided channel name and format string, or creates a new UB channel
\r
408 * if no match is found. The format string should therefore not contain
\r
409 * "random" messages but mainly format specifiers. Random strings should
\r
410 * be stored using %s and with the string as an argument.
\r
412 * // Creates a new UB channel ("Channel 2", "%Z: %d")
\r
413 * vTracePrintF(chn2, "%Z: %d", value1);
\r
415 * // Finds the existing UB channel
\r
416 * vTracePrintF(chn2, "%Z: %d", value2);
\r
418 ******************************************************************************/
\r
419 #define TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER 0
\r
421 /*******************************************************************************
\r
422 * TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE
\r
424 * Macro which should be defined as an integer value.
\r
426 * This defines the capacity of the user event buffer (UB), in number of slots.
\r
427 * A single user event can use multiple slots, depending on the arguments.
\r
429 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1.
\r
430 ******************************************************************************/
\r
431 #define TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE 200
\r
433 /*******************************************************************************
\r
434 * TRC_CFG_UB_CHANNELS
\r
436 * Macro which should be defined as an integer value.
\r
438 * This defines the number of User Event Buffer Channels (UB channels).
\r
439 * These are used to structure the events when using the separate user
\r
440 * event buffer, and contains both a User Event Channel (the name) and
\r
441 * a default format string for the channel.
\r
443 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1.
\r
444 ******************************************************************************/
\r
445 #define TRC_CFG_UB_CHANNELS 32
\r
447 /*******************************************************************************
\r
448 * TRC_CFG_ISR_TAILCHAINING_THRESHOLD
\r
450 * Macro which should be defined as an integer value.
\r
452 * If tracing multiple ISRs, this setting allows for accurate display of the
\r
453 * context-switching also in cases when the ISRs execute in direct sequence.
\r
455 * vTraceStoreISREnd normally assumes that the ISR returns to the previous
\r
456 * context, i.e., a task or a preempted ISR. But if another traced ISR
\r
457 * executes in direct sequence, Tracealyzer may incorrectly display a minimal
\r
458 * fragment of the previous context in between the ISRs.
\r
460 * By using TRC_CFG_ISR_TAILCHAINING_THRESHOLD you can avoid this. This is
\r
461 * however a threshold value that must be measured for your specific setup.
\r
462 * See http://percepio.com/2014/03/21/isr_tailchaining_threshold/
\r
464 * The default setting is 0, meaning "disabled" and that you may get an
\r
465 * extra fragments of the previous context in between tail-chained ISRs.
\r
467 * Note: This setting has separate definitions in trcSnapshotConfig.h and
\r
468 * trcStreamingConfig.h, since it is affected by the recorder mode.
\r
469 ******************************************************************************/
\r
470 #define TRC_CFG_ISR_TAILCHAINING_THRESHOLD 0
\r
472 #endif /*TRC_SNAPSHOT_CONFIG_H*/
\r
projects / freertos / blob