1 /*
2  * Trace Recorder for Tracealyzer v4.5.1
3  * Copyright 2021 Percepio AB
4  * www.percepio.com
5  *
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Configuration parameters for trace recorder library in snapshot mode.
9  * Read more at http://percepio.com/2016/10/05/rtos-tracing/
10  */
11 
12 #ifndef TRC_SNAPSHOT_CONFIG_H
13 #define TRC_SNAPSHOT_CONFIG_H
14 
15 #define TRC_SNAPSHOT_MODE_RING_BUFFER		(0x01)
16 #define TRC_SNAPSHOT_MODE_STOP_WHEN_FULL	(0x02)
17 
18 /******************************************************************************
19  * TRC_CFG_SNAPSHOT_MODE
20  *
21  * Macro which should be defined as one of:
22  * - TRC_SNAPSHOT_MODE_RING_BUFFER
23  * - TRC_SNAPSHOT_MODE_STOP_WHEN_FULL
24  * Default is TRC_SNAPSHOT_MODE_RING_BUFFER.
25  *
26  * With TRC_CFG_SNAPSHOT_MODE set to TRC_SNAPSHOT_MODE_RING_BUFFER, the
27  * events are stored in a ring buffer, i.e., where the oldest events are
28  * overwritten when the buffer becomes full. This allows you to get the last
29  * events leading up to an interesting state, e.g., an error, without having
30  * to store the whole run since startup.
31  *
32  * When TRC_CFG_SNAPSHOT_MODE is TRC_SNAPSHOT_MODE_STOP_WHEN_FULL, the
33  * recording is stopped when the buffer becomes full. This is useful for
34  * recording events following a specific state, e.g., the startup sequence.
35  *****************************************************************************/
36 #define TRC_CFG_SNAPSHOT_MODE TRC_SNAPSHOT_MODE_RING_BUFFER
37 
38 /*******************************************************************************
39  * TRC_CFG_EVENT_BUFFER_SIZE
40  *
41  * Macro which should be defined as an integer value.
42  *
43  * This defines the capacity of the event buffer, i.e., the number of records
44  * it may store. Most events use one record (4 byte), although some events
45  * require multiple 4-byte records. You should adjust this to the amount of RAM
46  * available in the target system.
47  *
48  * Default value is 1000, which means that 4000 bytes is allocated for the
49  * event buffer.
50  ******************************************************************************/
51 #define TRC_CFG_EVENT_BUFFER_SIZE 15000
52 
53 /*******************************************************************************
54  * TRC_CFG_NTASK, TRC_CFG_NISR, TRC_CFG_NQUEUE, TRC_CFG_NSEMAPHORE...
55  *
56  * A group of macros which should be defined as integer values, zero or larger.
57  *
58  * These define the capacity of the Object Property Table, i.e., the maximum
59  * number of objects active at any given point, within each object class (e.g.,
60  * task, queue, semaphore, ...).
61  *
62  * If tasks or other objects are deleted in your system, this
63  * setting does not limit the total amount of objects created, only the number
64  * of objects that have been successfully created but not yet deleted.
65  *
66  * Using too small values will cause vTraceError to be called, which stores an
67  * error message in the trace that is shown when opening the trace file. The
68  * error message can also be retrieved using xTraceGetLastError.
69  *
70  * It can be wise to start with large values for these constants,
71  * unless you are very confident on these numbers. Then do a recording and
72  * check the actual usage by selecting View menu -> Trace Details ->
73  * Resource Usage -> Object Table.
74  ******************************************************************************/
75 #define TRC_CFG_NTASK			1
76 #define TRC_CFG_NISR			10
77 #define TRC_CFG_NQUEUE			1
78 #define TRC_CFG_NSEMAPHORE		1
79 #define TRC_CFG_NMUTEX			1
80 #define TRC_CFG_NTIMER			1
81 #define TRC_CFG_NEVENTGROUP		1
82 #define TRC_CFG_NSTREAMBUFFER	1
83 #define TRC_CFG_NMESSAGEBUFFER	1
84 
85 /******************************************************************************
86  * TRC_CFG_INCLUDE_FLOAT_SUPPORT
87  *
88  * Macro which should be defined as either zero (0) or one (1).
89  *
90  * If this is zero (0), the support for logging floating point values in
91  * vTracePrintF is stripped out, in case floating point values are not used or
92  * supported by the platform used.
93  *
94  * Floating point values are only used in vTracePrintF and its subroutines, to
95  * allow for storing float (%f) or double (%lf) arguments.
96  *
97  * vTracePrintF can be used with integer and string arguments in either case.
98  *
99  * Default value is 0.
100  *****************************************************************************/
101 #define TRC_CFG_INCLUDE_FLOAT_SUPPORT 0
102 
103 /*******************************************************************************
104  * TRC_CFG_SYMBOL_TABLE_SIZE
105  *
106  * Macro which should be defined as an integer value.
107  *
108  * This defines the capacity of the symbol table, in bytes. This symbol table
109  * stores User Events labels and names of deleted tasks, queues, or other kernel
110  * objects. If you don't use User Events or delete any kernel
111  * objects you set this to a very low value. The minimum recommended value is 4.
112  * A size of zero (0) is not allowed since a zero-sized array may result in a
113  * 32-bit pointer, i.e., using 4 bytes rather than 0.
114  *
115  * Default value is 800.
116  ******************************************************************************/
117 #define TRC_CFG_SYMBOL_TABLE_SIZE 10000
118 
119 #if (TRC_CFG_SYMBOL_TABLE_SIZE == 0)
120 #error "TRC_CFG_SYMBOL_TABLE_SIZE may not be zero!"
121 #endif
122 
123 /******************************************************************************
124  * TRC_CFG_NAME_LEN_TASK, TRC_CFG_NAME_LEN_QUEUE, ...
125  *
126  * Macros that specify the maximum lengths (number of characters) for names of
127  * kernel objects, such as tasks and queues. If longer names are used, they will
128  * be truncated when stored in the recorder.
129  *****************************************************************************/
130 #define TRC_CFG_NAME_LEN_TASK			15
131 #define TRC_CFG_NAME_LEN_ISR			15
132 #define TRC_CFG_NAME_LEN_QUEUE			7
133 #define TRC_CFG_NAME_LEN_SEMAPHORE		7
134 #define TRC_CFG_NAME_LEN_MUTEX			7
135 #define TRC_CFG_NAME_LEN_TIMER			7
136 #define TRC_CFG_NAME_LEN_EVENTGROUP 	7
137 #define TRC_CFG_NAME_LEN_STREAMBUFFER 	7
138 #define TRC_CFG_NAME_LEN_MESSAGEBUFFER 	7
139 
140 /******************************************************************************
141  *** ADVANCED SETTINGS ********************************************************
142  ******************************************************************************
143  * The remaining settings are not necessary to modify but allows for optimizing
144  * the recorder setup for your specific needs, e.g., to exclude events that you
145  * are not interested in, in order to get longer traces.
146  *****************************************************************************/
147 
148 /******************************************************************************
149 * TRC_CFG_HEAP_SIZE_BELOW_16M
150 *
151 * An integer constant that can be used to reduce the buffer usage of memory
152 * allocation events (malloc/free). This value should be 1 if the heap size is
153 * below 16 MB (2^24 byte), and you can live with reported addresses showing the
154 * lower 24 bits only. If 0, you get the full 32-bit addresses.
155 *
156 * Default value is 0.
157 ******************************************************************************/
158 #define TRC_CFG_HEAP_SIZE_BELOW_16M 0
159 
160 /******************************************************************************
161  * TRC_CFG_USE_IMPLICIT_IFE_RULES
162  *
163  * Macro which should be defined as either zero (0) or one (1).
164  * Default is 1.
165  *
166  * Tracealyzer groups the events into "instances" based on Instance Finish
167  * Events (IFEs), produced either by default rules or calls to the recorder
168  * functions vTraceInstanceFinishedNow and vTraceInstanceFinishedNext.
169  *
170  * If TRC_CFG_USE_IMPLICIT_IFE_RULES is one (1), the default IFE rules is
171  * used, resulting in a "typical" grouping of events into instances.
172  * If these rules don't give appropriate instances in your case, you can
173  * override the default rules using vTraceInstanceFinishedNow/Next for one
174  * or several tasks. The default IFE rules are then disabled for those tasks.
175  *
176  * If TRC_CFG_USE_IMPLICIT_IFE_RULES is zero (0), the implicit IFE rules are
177  * disabled globally. You must then call vTraceInstanceFinishedNow or
178  * vTraceInstanceFinishedNext to manually group the events into instances,
179  * otherwise the tasks will appear a single long instance.
180  *
181  * The default IFE rules count the following events as "instance finished":
182  * - Task delay, delay until
183  * - Task suspend
184  * - Blocking on "input" operations, i.e., when the task is waiting for the
185  *   next a message/signal/event. But only if this event is blocking.
186  *
187  * For details, see trcSnapshotKernelPort.h and look for references to the
188  * macro trcKERNEL_HOOKS_SET_TASK_INSTANCE_FINISHED.
189  *****************************************************************************/
190 #define TRC_CFG_USE_IMPLICIT_IFE_RULES 1
191 
192 /******************************************************************************
193  * TRC_CFG_USE_16BIT_OBJECT_HANDLES
194  *
195  * Macro which should be defined as either zero (0) or one (1).
196  *
197  * If set to 0 (zero), the recorder uses 8-bit handles to identify kernel
198  * objects such as tasks and queues. This limits the supported number of
199  * concurrently active objects to 255 of each type (tasks, queues, mutexes,
200  * etc.) Note: 255, not 256, since handle 0 is reserved.
201  *
202  * If set to 1 (one), the recorder uses 16-bit handles to identify kernel
203  * objects such as tasks and queues. This limits the supported number of
204  * concurrent objects to 65535 of each type (object class). However, since the
205  * object property table is limited to 64 KB, the practical limit is about
206  * 3000 objects in total.
207  *
208  * Default is 0 (8-bit handles)
209  *
210  * NOTE: An object with handle above 255 will use an extra 4-byte record in
211  * the event buffer whenever the object is referenced. Moreover, some internal
212  * tables in the recorder gets slightly larger when using 16-bit handles.
213  *****************************************************************************/
214 #define TRC_CFG_USE_16BIT_OBJECT_HANDLES 0
215 
216 /******************************************************************************
217  * TRC_CFG_USE_TRACE_ASSERT
218  *
219  * Macro which should be defined as either zero (0) or one (1).
220  * Default is 1.
221  *
222  * If this is one (1), the TRACE_ASSERT macro (used at various locations in the
223  * trace recorder) will verify that a relevant condition is true.
224  * If the condition is false, prvTraceError() will be called, which stops the
225  * recording and stores an error message that is displayed when opening the
226  * trace in Tracealyzer.
227  *
228  * This is used on several places in the recorder code for sanity checks on
229  * parameters. Can be switched off to reduce the footprint of the tracing, but
230  * we recommend to have it enabled initially.
231  *****************************************************************************/
232 #define TRC_CFG_USE_TRACE_ASSERT 1
233 
234 /*******************************************************************************
235  * TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER
236  *
237  * Macro which should be defined as an integer value.
238  *
239  * Set TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER to 1 to enable the
240  * separate user event buffer (UB).
241  * In this mode, user events are stored separately from other events,
242  * e.g., RTOS events. Thereby you can get a much longer history of
243  * user events as they don't need to share the buffer space with more
244  * frequent events.
245  *
246  * The UB is typically used with the snapshot ring-buffer mode, so the
247  * recording can continue when the main buffer gets full. And since the
248  * main buffer then overwrites the earliest events, Tracealyzer displays
249  * "Unknown Actor" instead of task scheduling for periods with UB data only.
250  *
251  * In UB mode, user events are structured as UB channels, which contains
252  * a channel name and a default format string. Register a UB channel using
253  * xTraceRegisterUBChannel.
254  *
255  * Events and data arguments are written using vTraceUBEvent and
256  * vTraceUBData. They are designed to provide efficient logging of
257  * repeating events, using the same format string within each channel.
258  *
259  * Examples:
260  *
261  *  traceString chn1 = xTraceRegisterString("Channel 1");
262  *  traceString fmt1 = xTraceRegisterString("Event!");
263  *  traceUBChannel UBCh1 = xTraceRegisterUBChannel(chn1, fmt1);
264  *
265  *  traceString chn2 = xTraceRegisterString("Channel 2");
266  *  traceString fmt2 = xTraceRegisterString("X: %d, Y: %d");
267  *	traceUBChannel UBCh2 = xTraceRegisterUBChannel(chn2, fmt2);
268  *
269  *  // Result in "[Channel 1] Event!"
270  *	vTraceUBEvent(UBCh1);
271  *
272  *  // Result in "[Channel 2] X: 23, Y: 19"
273  *	vTraceUBData(UBCh2, 23, 19);
274  *
275  * You can also use the other user event functions, like vTracePrintF.
276  * as they are then rerouted to the UB instead of the main event buffer.
277  * vTracePrintF then looks up the correct UB channel based on the
278  * provided channel name and format string, or creates a new UB channel
279  * if no match is found. The format string should therefore not contain
280  * "random" messages but mainly format specifiers. Random strings should
281  * be stored using %s and with the string as an argument.
282  *
283  *  // Creates a new UB channel ("Channel 2", "%Z: %d")
284  *  vTracePrintF(chn2, "%Z: %d", value1);
285  *
286  *  // Finds the existing UB channel
287  *  vTracePrintF(chn2, "%Z: %d", value2);
288 
289  ******************************************************************************/
290 #define TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER 0
291 
292 /*******************************************************************************
293  * TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE
294  *
295  * Macro which should be defined as an integer value.
296  *
297  * This defines the capacity of the user event buffer (UB), in number of slots.
298  * A single user event can use multiple slots, depending on the arguments.
299  *
300  * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1.
301  ******************************************************************************/
302 #define TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE 200
303 
304 /*******************************************************************************
305  * TRC_CFG_UB_CHANNELS
306  *
307  * Macro which should be defined as an integer value.
308  *
309  * This defines the number of User Event Buffer Channels (UB channels).
310  * These are used to structure the events when using the separate user
311  * event buffer, and contains both a User Event Channel (the name) and
312  * a default format string for the channel.
313  *
314  * Only applicable if TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER is 1.
315  ******************************************************************************/
316 #define TRC_CFG_UB_CHANNELS 32
317 
318 /*******************************************************************************
319  * TRC_CFG_ISR_TAILCHAINING_THRESHOLD
320  *
321  * Macro which should be defined as an integer value.
322  *
323  * If tracing multiple ISRs, this setting allows for accurate display of the
324  * context-switching also in cases when the ISRs execute in direct sequence.
325  *
326  * vTraceStoreISREnd normally assumes that the ISR returns to the previous
327  * context, i.e., a task or a preempted ISR. But if another traced ISR
328  * executes in direct sequence, Tracealyzer may incorrectly display a minimal
329  * fragment of the previous context in between the ISRs.
330  *
331  * By using TRC_CFG_ISR_TAILCHAINING_THRESHOLD you can avoid this. This is
332  * however a threshold value that must be measured for your specific setup.
333  * See http://percepio.com/2014/03/21/isr_tailchaining_threshold/
334  *
335  * The default setting is 0, meaning "disabled" and that you may get an
336  * extra fragments of the previous context in between tail-chained ISRs.
337  *
338  * Note: This setting has separate definitions in trcSnapshotConfig.h and
339  * trcStreamingConfig.h, since it is affected by the recorder mode.
340  ******************************************************************************/
341 #define TRC_CFG_ISR_TAILCHAINING_THRESHOLD 0
342 
343 #endif /*TRC_SNAPSHOT_CONFIG_H*/
344