1 /*******************************************************************************
2 * Trace Recorder Library for Tracealyzer v3.1.2
3 * Percepio AB, www.percepio.com
7 * Configuration parameters for trace recorder library in snapshot mode.
8 * Read more at http://percepio.com/2016/10/05/rtos-tracing/
11 * This file is part of the trace recorder library (RECORDER), which is the
12 * intellectual property of Percepio AB (PERCEPIO) and provided under a
14 * The RECORDER may be used free of charge for the purpose of recording data
15 * intended for analysis in PERCEPIO products. It may not be used or modified
16 * for other purposes without explicit permission from PERCEPIO.
17 * You may distribute the RECORDER in its original source code form, assuming
18 * this text (terms of use, disclaimer, copyright notice) is unchanged. You are
19 * allowed to distribute the RECORDER with minor modifications intended for
20 * configuration or porting of the RECORDER, e.g., to allow using it on a
21 * specific processor, processor family or with a specific communication
22 * interface. Any such modifications should be documented directly below
26 * The RECORDER is being delivered to you AS IS and PERCEPIO makes no warranty
27 * as to its use or performance. PERCEPIO does not and cannot warrant the
28 * performance or results you may obtain by using the RECORDER or documentation.
29 * PERCEPIO make no warranties, express or implied, as to noninfringement of
30 * third party rights, merchantability, or fitness for any particular purpose.
31 * In no event will PERCEPIO, its technology partners, or distributors be liable
32 * to you for any consequential, incidental or special damages, including any
33 * lost profits or lost savings, even if a representative of PERCEPIO has been
34 * advised of the possibility of such damages, or for any claim by any third
35 * party. Some jurisdictions do not allow the exclusion or limitation of
36 * incidental, consequential or special damages, or the exclusion of implied
37 * warranties or limitations on how long an implied warranty may last, so the
38 * above limitations may not apply to you.
40 * Tabs are used for indent in this file (1 tab = 4 spaces)
42 * Copyright Percepio AB, 2017.
44 ******************************************************************************/
46 #ifndef TRC_SNAPSHOT_CONFIG_H
47 #define TRC_SNAPSHOT_CONFIG_H
49 #define TRC_SNAPSHOT_MODE_RING_BUFFER (0x01)
50 #define TRC_SNAPSHOT_MODE_STOP_WHEN_FULL (0x02)
52 /******************************************************************************
53 * TRC_CFG_SNAPSHOT_MODE
55 * Macro which should be defined as one of:
56 * - TRC_SNAPSHOT_MODE_RING_BUFFER
57 * - TRC_SNAPSHOT_MODE_STOP_WHEN_FULL
58 * Default is TRC_SNAPSHOT_MODE_RING_BUFFER.
60 * With TRC_CFG_SNAPSHOT_MODE set to TRC_SNAPSHOT_MODE_RING_BUFFER, the
61 * events are stored in a ring buffer, i.e., where the oldest events are
62 * overwritten when the buffer becomes full. This allows you to get the last
63 * events leading up to an interesting state, e.g., an error, without having
64 * to store the whole run since startup.
66 * When TRC_CFG_SNAPSHOT_MODE is TRC_SNAPSHOT_MODE_STOP_WHEN_FULL, the
67 * recording is stopped when the buffer becomes full. This is useful for
68 * recording events following a specific state, e.g., the startup sequence.
69 *****************************************************************************/
70 #define TRC_CFG_SNAPSHOT_MODE TRC_SNAPSHOT_MODE_RING_BUFFER
72 /*******************************************************************************
73 * TRC_CFG_EVENT_BUFFER_SIZE
75 * Macro which should be defined as an integer value.
77 * This defines the capacity of the event buffer, i.e., the number of records
78 * it may store. Most events use one record (4 byte), although some events
79 * require multiple 4-byte records. You should adjust this to the amount of RAM
80 * available in the target system.
82 * Default value is 1000, which means that 4000 bytes is allocated for the
84 ******************************************************************************/
85 #define TRC_CFG_EVENT_BUFFER_SIZE 15000
87 /*******************************************************************************
88 * TRC_CFG_NTASK, TRC_CFG_NISR, TRC_CFG_NQUEUE, TRC_CFG_NSEMAPHORE...
90 * A group of macros which should be defined as integer values, zero or larger.
92 * These define the capacity of the Object Property Table, i.e., the maximum
93 * number of objects active at any given point, within each object class (e.g.,
94 * task, queue, semaphore, ...).
96 * If tasks or other objects are deleted in your system, this
97 * setting does not limit the total amount of objects created, only the number
98 * of objects that have been successfully created but not yet deleted.
100 * Using too small values will cause vTraceError to be called, which stores an
101 * error message in the trace that is shown when opening the trace file. The
102 * error message can also be retrieved using xTraceGetLastError.
104 * It can be wise to start with large values for these constants,
105 * unless you are very confident on these numbers. Then do a recording and
106 * check the actual usage by selecting View menu -> Trace Details ->
107 * Resource Usage -> Object Table.
108 ******************************************************************************/
109 #define TRC_CFG_NTASK 150
110 #define TRC_CFG_NISR 90
111 #define TRC_CFG_NQUEUE 90
112 #define TRC_CFG_NSEMAPHORE 90
113 #define TRC_CFG_NMUTEX 90
114 #define TRC_CFG_NTIMER 250
115 #define TRC_CFG_NEVENTGROUP 90
116 #define TRC_CFG_NSTREAMBUFFER 5
117 #define TRC_CFG_NMESSAGEBUFFER 5
120 /******************************************************************************
121 * TRC_CFG_INCLUDE_FLOAT_SUPPORT
123 * Macro which should be defined as either zero (0) or one (1).
125 * If this is zero (0), the support for logging floating point values in
126 * vTracePrintF is stripped out, in case floating point values are not used or
127 * supported by the platform used.
129 * Floating point values are only used in vTracePrintF and its subroutines, to
130 * allow for storing float (%f) or double (%lf) arguments.
132 * vTracePrintF can be used with integer and string arguments in either case.
134 * Default value is 0.
135 *****************************************************************************/
136 #define TRC_CFG_INCLUDE_FLOAT_SUPPORT 0
138 /*******************************************************************************
139 * TRC_CFG_SYMBOL_TABLE_SIZE
141 * Macro which should be defined as an integer value.
143 * This defines the capacity of the symbol table, in bytes. This symbol table
144 * stores User Events labels and names of deleted tasks, queues, or other kernel
145 * objects. If you don't use User Events or delete any kernel
146 * objects you set this to a very low value. The minimum recommended value is 4.
147 * A size of zero (0) is not allowed since a zero-sized array may result in a
148 * 32-bit pointer, i.e., using 4 bytes rather than 0.
150 * Default value is 800.
151 ******************************************************************************/
152 #define TRC_CFG_SYMBOL_TABLE_SIZE 5000
154 #if (TRC_CFG_SYMBOL_TABLE_SIZE == 0)
155 #error "TRC_CFG_SYMBOL_TABLE_SIZE may not be zero!"
158 /******************************************************************************
159 * TRC_CFG_NAME_LEN_TASK, TRC_CFG_NAME_LEN_QUEUE, ...
161 * Macros that specify the maximum lengths (number of characters) for names of
162 * kernel objects, such as tasks and queues. If longer names are used, they will
163 * be truncated when stored in the recorder.
164 *****************************************************************************/
165 #define TRC_CFG_NAME_LEN_TASK 15
166 #define TRC_CFG_NAME_LEN_ISR 15
167 #define TRC_CFG_NAME_LEN_QUEUE 15
168 #define TRC_CFG_NAME_LEN_SEMAPHORE 15
169 #define TRC_CFG_NAME_LEN_MUTEX 15
170 #define TRC_CFG_NAME_LEN_TIMER 15
171 #define TRC_CFG_NAME_LEN_EVENTGROUP 15
172 #define TRC_CFG_NAME_LEN_STREAMBUFFER 15
173 #define TRC_CFG_NAME_LEN_MESSAGEBUFFER 15
175 /******************************************************************************
176 *** ADVANCED SETTINGS ********************************************************
177 ******************************************************************************
178 * The remaining settings are not necessary to modify but allows for optimizing
179 * the recorder setup for your specific needs, e.g., to exclude events that you
180 * are not interested in, in order to get longer traces.
181 *****************************************************************************/
183 /******************************************************************************
184 * TRC_CFG_HEAP_SIZE_BELOW_16M
186 * An integer constant that can be used to reduce the buffer usage of memory
187 * allocation events (malloc/free). This value should be 1 if the heap size is
188 * below 16 MB (2^24 byte), and you can live with reported addresses showing the
189 * lower 24 bits only. If 0, you get the full 32-bit addresses.
191 * Default value is 0.
192 ******************************************************************************/
193 #define TRC_CFG_HEAP_SIZE_BELOW_16M 0
195 /******************************************************************************
196 * TRC_CFG_USE_IMPLICIT_IFE_RULES
198 * Macro which should be defined as either zero (0) or one (1).
201 * Tracealyzer groups the events into "instances" based on Instance Finish
202 * Events (IFEs), produced either by default rules or calls to the recorder
203 * functions vTraceInstanceFinishedNow and vTraceInstanceFinishedNext.
205 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is one (1), the default IFE rules is
206 * used, resulting in a "typical" grouping of events into instances.
207 * If these rules don't give appropriate instances in your case, you can
208 * override the default rules using vTraceInstanceFinishedNow/Next for one
209 * or several tasks. The default IFE rules are then disabled for those tasks.
211 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is zero (0), the implicit IFE rules are
212 * disabled globally. You must then call vTraceInstanceFinishedNow or
213 * vTraceInstanceFinishedNext to manually group the events into instances,
214 * otherwise the tasks will appear a single long instance.
216 * The default IFE rules count the following events as "instance finished":
217 * - Task delay, delay until
219 * - Blocking on "input" operations, i.e., when the task is waiting for the
220 * next a message/signal/event. But only if this event is blocking.
222 * For details, see trcSnapshotKernelPort.h and look for references to the
223 * macro trcKERNEL_HOOKS_SET_TASK_INSTANCE_FINISHED.
224 *****************************************************************************/
225 #define TRC_CFG_USE_IMPLICIT_IFE_RULES 1
227 /******************************************************************************
228 * TRC_CFG_USE_16BIT_OBJECT_HANDLES
230 * Macro which should be defined as either zero (0) or one (1).
232 * If set to 0 (zero), the recorder uses 8-bit handles to identify kernel
233 * objects such as tasks and queues. This limits the supported number of
234 * concurrently active objects to 255 of each type (tasks, queues, mutexes,
235 * etc.) Note: 255, not 256, since handle 0 is reserved.
237 * If set to 1 (one), the recorder uses 16-bit handles to identify kernel
238 * objects such as tasks and queues. This limits the supported number of
239 * concurrent objects to 65535 of each type (object class). However, since the
240 * object property table is limited to 64 KB, the practical limit is about
241 * 3000 objects in total.
243 * Default is 0 (8-bit handles)
245 * NOTE: An object with handle above 255 will use an extra 4-byte record in
246 * the event buffer whenever the object is referenced. Moreover, some internal
247 * tables in the recorder gets slightly larger when using 16-bit handles.
248 *****************************************************************************/
249 #define TRC_CFG_USE_16BIT_OBJECT_HANDLES 0
251 /******************************************************************************
252 * TRC_CFG_USE_TRACE_ASSERT
254 * Macro which should be defined as either zero (0) or one (1).
257 * If this is one (1), the TRACE_ASSERT macro (used at various locations in the
258 * trace recorder) will verify that a relevant condition is true.
259 * If the condition is false, prvTraceError() will be called, which stops the
260 * recording and stores an error message that is displayed when opening the
261 * trace in Tracealyzer.
263 * This is used on several places in the recorder code for sanity checks on
264 * parameters. Can be switched off to reduce the footprint of the tracing, but
265 * we recommend to have it enabled initially.
266 *****************************************************************************/
267 #define TRC_CFG_USE_TRACE_ASSERT 1
269 /*******************************************************************************
270 * TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER
272 * Macro which should be defined as an integer value.
274 * Set TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER to 1 to enable the
275 * separate user event buffer (UB).
276 * In this mode, user events are stored separately from other events,
277 * e.g., RTOS events. Thereby you can get a much longer history of
278 * user events as they don't need to share the buffer space with more
281 * The UB is typically used with the snapshot ring-buffer mode, so the
282 * recording can continue when the main buffer gets full. And since the
283 * main buffer then overwrites the earliest events, Tracealyzer displays
284 * "Unknown Actor" instead of task scheduling for periods with UB data only.
286 * In UB mode, user events are structured as UB channels, which contains
287 * a channel name and a default format string. Register a UB channel using
288 * xTraceRegisterUBChannel.
290 * Events and data arguments are written using vTraceUBEvent and
291 * vTraceUBData. They are designed to provide efficient logging of
292 * repeating events, using the same format string within each channel.
296 * traceString chn1 = xTraceRegisterString("Channel 1");
297 * traceString fmt1 = xTraceRegisterString("Event!");
298 * traceUBChannel UBCh1 = xTraceRegisterUBChannel(chn1, fmt1);
300 * traceString chn2 = xTraceRegisterString("Channel 2");
301 * traceString fmt2 = xTraceRegisterString("X: %d, Y: %d");
302 * traceUBChannel UBCh2 = xTraceRegisterUBChannel(chn2, fmt2);
304 * // Result in "[Channel 1] Event!"
305 * vTraceUBEvent(UBCh1);
307 * // Result in "[Channel 2] X: 23, Y: 19"
308 * vTraceUBData(UBCh2, 23, 19);
310 * You can also use the other user event functions, like vTracePrintF.
311 * as they are then rerouted to the UB instead of the main event buffer.
312 * vTracePrintF then looks up the correct UB channel based on the
313 * provided channel name and format string, or creates a new UB channel
314 * if no match is found. The format string should therefore not contain
315 * "random" messages but mainly format specifiers. Random strings should
316 * be stored using %s and with the string as an argument.
318 * // Creates a new UB channel ("Channel 2", "%Z: %d")
319 * vTracePrintF(chn2, "%Z: %d", value1);
321 * // Finds the existing UB channel
322 * vTracePrintF(chn2, "%Z: %d", value2);
324 ******************************************************************************/
325 #define TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER 0
327 /*******************************************************************************
328 * TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE
330 * Macro which should be defined as an integer value.
332 * This defines the capacity of the user event buffer (UB), in number of slots.
333 * A single user event can use multiple slots, depending on the arguments.
335 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1.
336 ******************************************************************************/
337 #define TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE 200
339 /*******************************************************************************
340 * TRC_CFG_UB_CHANNELS
342 * Macro which should be defined as an integer value.
344 * This defines the number of User Event Buffer Channels (UB channels).
345 * These are used to structure the events when using the separate user
346 * event buffer, and contains both a User Event Channel (the name) and
347 * a default format string for the channel.
349 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1.
350 ******************************************************************************/
351 #define TRC_CFG_UB_CHANNELS 32
353 /*******************************************************************************
354 * TRC_CFG_ISR_TAILCHAINING_THRESHOLD
356 * Macro which should be defined as an integer value.
358 * If tracing multiple ISRs, this setting allows for accurate display of the
359 * context-switching also in cases when the ISRs execute in direct sequence.
361 * vTraceStoreISREnd normally assumes that the ISR returns to the previous
362 * context, i.e., a task or a preempted ISR. But if another traced ISR
363 * executes in direct sequence, Tracealyzer may incorrectly display a minimal
364 * fragment of the previous context in between the ISRs.
366 * By using TRC_CFG_ISR_TAILCHAINING_THRESHOLD you can avoid this. This is
367 * however a threshold value that must be measured for your specific setup.
368 * See http://percepio.com/2014/03/21/isr_tailchaining_threshold/
370 * The default setting is 0, meaning "disabled" and that you may get an
371 * extra fragments of the previous context in between tail-chained ISRs.
373 * Note: This setting has separate definitions in trcSnapshotConfig.h and
374 * trcStreamingConfig.h, since it is affected by the recorder mode.
375 ******************************************************************************/
376 #define TRC_CFG_ISR_TAILCHAINING_THRESHOLD 0
378 #endif /*TRC_SNAPSHOT_CONFIG_H*/