1 /*******************************************************************************
\r
2 * Trace Recorder Library for Tracealyzer v4.1.1
\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, 2018.
\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_EVENT_BUFFER_SIZE
\r
75 * Macro which should be defined as an integer value.
\r
77 * This defines the capacity of the event buffer, i.e., the number of records
\r
78 * it may store. Most events use one record (4 byte), although some events
\r
79 * require multiple 4-byte records. You should adjust this to the amount of RAM
\r
80 * available in the target system.
\r
82 * Default value is 1000, which means that 4000 bytes is allocated for the
\r
84 ******************************************************************************/
\r
85 #define TRC_CFG_EVENT_BUFFER_SIZE 1000
\r
87 /*******************************************************************************
\r
88 * TRC_CFG_NTASK, TRC_CFG_NISR, TRC_CFG_NQUEUE, TRC_CFG_NSEMAPHORE...
\r
90 * A group of macros which should be defined as integer values, zero or larger.
\r
92 * These define the capacity of the Object Property Table, i.e., the maximum
\r
93 * number of objects active at any given point, within each object class (e.g.,
\r
94 * task, queue, semaphore, ...).
\r
96 * If tasks or other objects are deleted in your system, this
\r
97 * setting does not limit the total amount of objects created, only the number
\r
98 * of objects that have been successfully created but not yet deleted.
\r
100 * Using too small values will cause vTraceError to be called, which stores an
\r
101 * error message in the trace that is shown when opening the trace file. The
\r
102 * error message can also be retrieved using xTraceGetLastError.
\r
104 * It can be wise to start with large values for these constants,
\r
105 * unless you are very confident on these numbers. Then do a recording and
\r
106 * check the actual usage by selecting View menu -> Trace Details ->
\r
107 * Resource Usage -> Object Table.
\r
108 ******************************************************************************/
\r
109 #define TRC_CFG_NTASK 15
\r
110 #define TRC_CFG_NISR 5
\r
111 #define TRC_CFG_NQUEUE 10
\r
112 #define TRC_CFG_NSEMAPHORE 10
\r
113 #define TRC_CFG_NMUTEX 10
\r
114 #define TRC_CFG_NTIMER 5
\r
115 #define TRC_CFG_NEVENTGROUP 5
\r
116 #define TRC_CFG_NSTREAMBUFFER 5
\r
117 #define TRC_CFG_NMESSAGEBUFFER 5
\r
119 /******************************************************************************
\r
120 * TRC_CFG_INCLUDE_FLOAT_SUPPORT
\r
122 * Macro which should be defined as either zero (0) or one (1).
\r
124 * If this is zero (0), the support for logging floating point values in
\r
125 * vTracePrintF is stripped out, in case floating point values are not used or
\r
126 * supported by the platform used.
\r
128 * Floating point values are only used in vTracePrintF and its subroutines, to
\r
129 * allow for storing float (%f) or double (%lf) arguments.
\r
131 * vTracePrintF can be used with integer and string arguments in either case.
\r
133 * Default value is 0.
\r
134 *****************************************************************************/
\r
135 #define TRC_CFG_INCLUDE_FLOAT_SUPPORT 0
\r
137 /*******************************************************************************
\r
138 * TRC_CFG_SYMBOL_TABLE_SIZE
\r
140 * Macro which should be defined as an integer value.
\r
142 * This defines the capacity of the symbol table, in bytes. This symbol table
\r
143 * stores User Events labels and names of deleted tasks, queues, or other kernel
\r
144 * objects. If you don't use User Events or delete any kernel
\r
145 * objects you set this to a very low value. The minimum recommended value is 4.
\r
146 * A size of zero (0) is not allowed since a zero-sized array may result in a
\r
147 * 32-bit pointer, i.e., using 4 bytes rather than 0.
\r
149 * Default value is 800.
\r
150 ******************************************************************************/
\r
151 #define TRC_CFG_SYMBOL_TABLE_SIZE 800
\r
153 #if (TRC_CFG_SYMBOL_TABLE_SIZE == 0)
\r
154 #error "TRC_CFG_SYMBOL_TABLE_SIZE may not be zero!"
\r
157 /******************************************************************************
\r
158 * TRC_CFG_NAME_LEN_TASK, TRC_CFG_NAME_LEN_QUEUE, ...
\r
160 * Macros that specify the maximum lengths (number of characters) for names of
\r
161 * kernel objects, such as tasks and queues. If longer names are used, they will
\r
162 * be truncated when stored in the recorder.
\r
163 *****************************************************************************/
\r
164 #define TRC_CFG_NAME_LEN_TASK 15
\r
165 #define TRC_CFG_NAME_LEN_ISR 15
\r
166 #define TRC_CFG_NAME_LEN_QUEUE 15
\r
167 #define TRC_CFG_NAME_LEN_SEMAPHORE 15
\r
168 #define TRC_CFG_NAME_LEN_MUTEX 15
\r
169 #define TRC_CFG_NAME_LEN_TIMER 15
\r
170 #define TRC_CFG_NAME_LEN_EVENTGROUP 15
\r
171 #define TRC_CFG_NAME_LEN_STREAMBUFFER 15
\r
172 #define TRC_CFG_NAME_LEN_MESSAGEBUFFER 15
\r
174 /******************************************************************************
\r
175 *** ADVANCED SETTINGS ********************************************************
\r
176 ******************************************************************************
\r
177 * The remaining settings are not necessary to modify but allows for optimizing
\r
178 * the recorder setup for your specific needs, e.g., to exclude events that you
\r
179 * are not interested in, in order to get longer traces.
\r
180 *****************************************************************************/
\r
182 /******************************************************************************
\r
183 * TRC_CFG_HEAP_SIZE_BELOW_16M
\r
185 * An integer constant that can be used to reduce the buffer usage of memory
\r
186 * allocation events (malloc/free). This value should be 1 if the heap size is
\r
187 * below 16 MB (2^24 byte), and you can live with reported addresses showing the
\r
188 * lower 24 bits only. If 0, you get the full 32-bit addresses.
\r
190 * Default value is 0.
\r
191 ******************************************************************************/
\r
192 #define TRC_CFG_HEAP_SIZE_BELOW_16M 0
\r
194 /******************************************************************************
\r
195 * TRC_CFG_USE_IMPLICIT_IFE_RULES
\r
197 * Macro which should be defined as either zero (0) or one (1).
\r
200 * Tracealyzer groups the events into "instances" based on Instance Finish
\r
201 * Events (IFEs), produced either by default rules or calls to the recorder
\r
202 * functions vTraceInstanceFinishedNow and vTraceInstanceFinishedNext.
\r
204 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is one (1), the default IFE rules is
\r
205 * used, resulting in a "typical" grouping of events into instances.
\r
206 * If these rules don't give appropriate instances in your case, you can
\r
207 * override the default rules using vTraceInstanceFinishedNow/Next for one
\r
208 * or several tasks. The default IFE rules are then disabled for those tasks.
\r
210 * If TRC_CFG_USE_IMPLICIT_IFE_RULES is zero (0), the implicit IFE rules are
\r
211 * disabled globally. You must then call vTraceInstanceFinishedNow or
\r
212 * vTraceInstanceFinishedNext to manually group the events into instances,
\r
213 * otherwise the tasks will appear a single long instance.
\r
215 * The default IFE rules count the following events as "instance finished":
\r
216 * - Task delay, delay until
\r
218 * - Blocking on "input" operations, i.e., when the task is waiting for the
\r
219 * next a message/signal/event. But only if this event is blocking.
\r
221 * For details, see trcSnapshotKernelPort.h and look for references to the
\r
222 * macro trcKERNEL_HOOKS_SET_TASK_INSTANCE_FINISHED.
\r
223 *****************************************************************************/
\r
224 #define TRC_CFG_USE_IMPLICIT_IFE_RULES 1
\r
226 /******************************************************************************
\r
227 * TRC_CFG_USE_16BIT_OBJECT_HANDLES
\r
229 * Macro which should be defined as either zero (0) or one (1).
\r
231 * If set to 0 (zero), the recorder uses 8-bit handles to identify kernel
\r
232 * objects such as tasks and queues. This limits the supported number of
\r
233 * concurrently active objects to 255 of each type (tasks, queues, mutexes,
\r
234 * etc.) Note: 255, not 256, since handle 0 is reserved.
\r
236 * If set to 1 (one), the recorder uses 16-bit handles to identify kernel
\r
237 * objects such as tasks and queues. This limits the supported number of
\r
238 * concurrent objects to 65535 of each type (object class). However, since the
\r
239 * object property table is limited to 64 KB, the practical limit is about
\r
240 * 3000 objects in total.
\r
242 * Default is 0 (8-bit handles)
\r
244 * NOTE: An object with handle above 255 will use an extra 4-byte record in
\r
245 * the event buffer whenever the object is referenced. Moreover, some internal
\r
246 * tables in the recorder gets slightly larger when using 16-bit handles.
\r
247 *****************************************************************************/
\r
248 #define TRC_CFG_USE_16BIT_OBJECT_HANDLES 0
\r
250 /******************************************************************************
\r
251 * TRC_CFG_USE_TRACE_ASSERT
\r
253 * Macro which should be defined as either zero (0) or one (1).
\r
256 * If this is one (1), the TRACE_ASSERT macro (used at various locations in the
\r
257 * trace recorder) will verify that a relevant condition is true.
\r
258 * If the condition is false, prvTraceError() will be called, which stops the
\r
259 * recording and stores an error message that is displayed when opening the
\r
260 * trace in Tracealyzer.
\r
262 * This is used on several places in the recorder code for sanity checks on
\r
263 * parameters. Can be switched off to reduce the footprint of the tracing, but
\r
264 * we recommend to have it enabled initially.
\r
265 *****************************************************************************/
\r
266 #define TRC_CFG_USE_TRACE_ASSERT 1
\r
268 /*******************************************************************************
\r
269 * TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER
\r
271 * Macro which should be defined as an integer value.
\r
273 * Set TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER to 1 to enable the
\r
274 * separate user event buffer (UB).
\r
275 * In this mode, user events are stored separately from other events,
\r
276 * e.g., RTOS events. Thereby you can get a much longer history of
\r
277 * user events as they don't need to share the buffer space with more
\r
280 * The UB is typically used with the snapshot ring-buffer mode, so the
\r
281 * recording can continue when the main buffer gets full. And since the
\r
282 * main buffer then overwrites the earliest events, Tracealyzer displays
\r
283 * "Unknown Actor" instead of task scheduling for periods with UB data only.
\r
285 * In UB mode, user events are structured as UB channels, which contains
\r
286 * a channel name and a default format string. Register a UB channel using
\r
287 * xTraceRegisterUBChannel.
\r
289 * Events and data arguments are written using vTraceUBEvent and
\r
290 * vTraceUBData. They are designed to provide efficient logging of
\r
291 * repeating events, using the same format string within each channel.
\r
295 * traceString chn1 = xTraceRegisterString("Channel 1");
\r
296 * traceString fmt1 = xTraceRegisterString("Event!");
\r
297 * traceUBChannel UBCh1 = xTraceRegisterUBChannel(chn1, fmt1);
\r
299 * traceString chn2 = xTraceRegisterString("Channel 2");
\r
300 * traceString fmt2 = xTraceRegisterString("X: %d, Y: %d");
\r
301 * traceUBChannel UBCh2 = xTraceRegisterUBChannel(chn2, fmt2);
\r
303 * // Result in "[Channel 1] Event!"
\r
304 * vTraceUBEvent(UBCh1);
\r
306 * // Result in "[Channel 2] X: 23, Y: 19"
\r
307 * vTraceUBData(UBCh2, 23, 19);
\r
309 * You can also use the other user event functions, like vTracePrintF.
\r
310 * as they are then rerouted to the UB instead of the main event buffer.
\r
311 * vTracePrintF then looks up the correct UB channel based on the
\r
312 * provided channel name and format string, or creates a new UB channel
\r
313 * if no match is found. The format string should therefore not contain
\r
314 * "random" messages but mainly format specifiers. Random strings should
\r
315 * be stored using %s and with the string as an argument.
\r
317 * // Creates a new UB channel ("Channel 2", "%Z: %d")
\r
318 * vTracePrintF(chn2, "%Z: %d", value1);
\r
320 * // Finds the existing UB channel
\r
321 * vTracePrintF(chn2, "%Z: %d", value2);
\r
323 ******************************************************************************/
\r
324 #define TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER 0
\r
326 /*******************************************************************************
\r
327 * TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE
\r
329 * Macro which should be defined as an integer value.
\r
331 * This defines the capacity of the user event buffer (UB), in number of slots.
\r
332 * A single user event can use multiple slots, depending on the arguments.
\r
334 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1.
\r
335 ******************************************************************************/
\r
336 #define TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE 200
\r
338 /*******************************************************************************
\r
339 * TRC_CFG_UB_CHANNELS
\r
341 * Macro which should be defined as an integer value.
\r
343 * This defines the number of User Event Buffer Channels (UB channels).
\r
344 * These are used to structure the events when using the separate user
\r
345 * event buffer, and contains both a User Event Channel (the name) and
\r
346 * a default format string for the channel.
\r
348 * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1.
\r
349 ******************************************************************************/
\r
350 #define TRC_CFG_UB_CHANNELS 32
\r
352 /*******************************************************************************
\r
353 * TRC_CFG_ISR_TAILCHAINING_THRESHOLD
\r
355 * Macro which should be defined as an integer value.
\r
357 * If tracing multiple ISRs, this setting allows for accurate display of the
\r
358 * context-switching also in cases when the ISRs execute in direct sequence.
\r
360 * vTraceStoreISREnd normally assumes that the ISR returns to the previous
\r
361 * context, i.e., a task or a preempted ISR. But if another traced ISR
\r
362 * executes in direct sequence, Tracealyzer may incorrectly display a minimal
\r
363 * fragment of the previous context in between the ISRs.
\r
365 * By using TRC_CFG_ISR_TAILCHAINING_THRESHOLD you can avoid this. This is
\r
366 * however a threshold value that must be measured for your specific setup.
\r
367 * See http://percepio.com/2014/03/21/isr_tailchaining_threshold/
\r
369 * The default setting is 0, meaning "disabled" and that you may get an
\r
370 * extra fragments of the previous context in between tail-chained ISRs.
\r
372 * Note: This setting has separate definitions in trcSnapshotConfig.h and
\r
373 * trcStreamingConfig.h, since it is affected by the recorder mode.
\r
374 ******************************************************************************/
\r
375 #define TRC_CFG_ISR_TAILCHAINING_THRESHOLD 0
\r
377 #endif /*TRC_SNAPSHOT_CONFIG_H*/
\r