]> git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace/config/trcSnapshotConfig.h
Update to the latest trace recorder library.
[freertos] / FreeRTOS-Plus / Source / FreeRTOS-Plus-Trace / config / trcSnapshotConfig.h
1 /*******************************************************************************\r
2  * Trace Recorder Library for Tracealyzer v3.1.2\r
3  * Percepio AB, www.percepio.com\r
4  *\r
5  * trcSnapshotConfig.h\r
6  *\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
9  *\r
10  * Terms of Use\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
24  *\r
25  * Disclaimer\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
39  *\r
40  * Tabs are used for indent in this file (1 tab = 4 spaces)\r
41  *\r
42  * Copyright Percepio AB, 2017.\r
43  * www.percepio.com\r
44  ******************************************************************************/\r
45 \r
46 #ifndef TRC_SNAPSHOT_CONFIG_H\r
47 #define TRC_SNAPSHOT_CONFIG_H\r
48 \r
49 #define TRC_SNAPSHOT_MODE_RING_BUFFER           (0x01)\r
50 #define TRC_SNAPSHOT_MODE_STOP_WHEN_FULL        (0x02)\r
51 \r
52 /******************************************************************************\r
53  * TRC_CFG_SNAPSHOT_MODE\r
54  *\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
59  *\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
65  *\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
71 \r
72 /*******************************************************************************\r
73  * TRC_CFG_SCHEDULING_ONLY\r
74  *\r
75  * Macro which should be defined as an integer value.\r
76  *\r
77  * If this setting is enabled (= 1), only scheduling events are recorded.\r
78  * If disabled (= 0), all events are recorded.\r
79  *\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
82  *\r
83  * Default value is 0 (store all enabled events).\r
84  *\r
85  ******************************************************************************/\r
86 #define TRC_CFG_SCHEDULING_ONLY 0\r
87 \r
88 /*******************************************************************************\r
89  * TRC_CFG_EVENT_BUFFER_SIZE\r
90  *\r
91  * Macro which should be defined as an integer value.\r
92  *\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
97  * \r
98  * Default value is 1000, which means that 4000 bytes is allocated for the\r
99  * event buffer.\r
100  ******************************************************************************/\r
101 #define TRC_CFG_EVENT_BUFFER_SIZE 1000\r
102 \r
103 /*******************************************************************************\r
104  * TRC_CFG_NTASK, TRC_CFG_NISR, TRC_CFG_NQUEUE, TRC_CFG_NSEMAPHORE...\r
105  *\r
106  * A group of macros which should be defined as integer values, zero or larger.\r
107  *\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
111  * \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
115  *\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
119  *\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                   10\r
126 #define TRC_CFG_NISR                    5\r
127 #define TRC_CFG_NQUEUE                  10\r
128 #define TRC_CFG_NSEMAPHORE              10\r
129 #define TRC_CFG_NMUTEX                  10\r
130 #define TRC_CFG_NTIMER                  5\r
131 #define TRC_CFG_NEVENTGROUP             5\r
132 \r
133 /******************************************************************************\r
134  * TRC_CFG_INCLUDE_MEMMANG_EVENTS\r
135  * \r
136  * Macro which should be defined as either zero (0) or one (1). \r
137  *\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
140  *\r
141  * Default value is 1.\r
142  *****************************************************************************/\r
143 #define TRC_CFG_INCLUDE_MEMMANG_EVENTS 1\r
144 \r
145 /******************************************************************************\r
146  * TRC_CFG_INCLUDE_USER_EVENTS\r
147  *\r
148  * Macro which should be defined as either zero (0) or one (1). \r
149  *\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
155  * \r
156  * Default value is 1.\r
157  *****************************************************************************/\r
158 #define TRC_CFG_INCLUDE_USER_EVENTS 1\r
159 \r
160 /*****************************************************************************\r
161  * TRC_CFG_INCLUDE_ISR_TRACING\r
162  *\r
163  * Macro which should be defined as either zero (0) or one (1). \r
164  *\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
167  *\r
168  * Default value is 1.\r
169  * \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
174 \r
175 /*****************************************************************************\r
176  * TRC_CFG_INCLUDE_READY_EVENTS\r
177  *\r
178  * Macro which should be defined as either zero (0) or one (1). \r
179  *\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
185  *\r
186  * Default value is 1.\r
187  *****************************************************************************/\r
188 #define TRC_CFG_INCLUDE_READY_EVENTS 1\r
189 \r
190 /*****************************************************************************\r
191  * TRC_CFG_INCLUDE_OSTICK_EVENTS\r
192  *\r
193  * Macro which should be defined as either zero (0) or one (1). \r
194  *\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
198  *\r
199  * Default value is 0.\r
200  *****************************************************************************/\r
201 #define TRC_CFG_INCLUDE_OSTICK_EVENTS 0\r
202 \r
203 /******************************************************************************\r
204  * TRC_CFG_INCLUDE_FLOAT_SUPPORT\r
205  *\r
206  * Macro which should be defined as either zero (0) or one (1). \r
207  *\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
211  *\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
214  *\r
215  * vTracePrintF can be used with integer and string arguments in either case.\r
216  *\r
217  * Default value is 0.\r
218  *****************************************************************************/\r
219 #define TRC_CFG_INCLUDE_FLOAT_SUPPORT 0\r
220 \r
221 /******************************************************************************\r
222  * TRC_CFG_INCLUDE_OBJECT_DELETE\r
223  * \r
224  * Macro which should be defined as either zero (0) or one (1). \r
225  *\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
229  *\r
230  * Default value is 1.\r
231  *****************************************************************************/\r
232 #define TRC_CFG_INCLUDE_OBJECT_DELETE 1\r
233 \r
234 /*******************************************************************************\r
235  * TRC_CFG_SYMBOL_TABLE_SIZE\r
236  *\r
237  * Macro which should be defined as an integer value.\r
238  *\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
245  *\r
246  * Default value is 800.\r
247  ******************************************************************************/\r
248 #define TRC_CFG_SYMBOL_TABLE_SIZE 800\r
249 \r
250 #if (TRC_CFG_SYMBOL_TABLE_SIZE == 0)\r
251 #error "TRC_CFG_SYMBOL_TABLE_SIZE may not be zero!"\r
252 #endif\r
253 \r
254 /******************************************************************************\r
255  * TRC_CFG_NAME_LEN_TASK, TRC_CFG_NAME_LEN_QUEUE, ...\r
256  *\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
268 \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
276 \r
277 /******************************************************************************\r
278 * TRC_CFG_HEAP_SIZE_BELOW_16M\r
279 *\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
284 *\r
285 * Default value is 0.\r
286 ******************************************************************************/\r
287 #define TRC_CFG_HEAP_SIZE_BELOW_16M 0\r
288 \r
289 /******************************************************************************\r
290  * TRC_CFG_USE_IMPLICIT_IFE_RULES\r
291  *\r
292  * Macro which should be defined as either zero (0) or one (1). \r
293  * Default is 1.\r
294  *\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
298  *\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
304  *\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
309  * \r
310  * The default IFE rules count the following events as "instance finished":\r
311  * - Task delay, delay until\r
312  * - Task suspend\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
315  *\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
320 \r
321 /******************************************************************************\r
322  * TRC_CFG_USE_16BIT_OBJECT_HANDLES\r
323  *\r
324  * Macro which should be defined as either zero (0) or one (1).\r
325  * \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
330  *\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
336  * \r
337  * Default is 0 (8-bit handles)\r
338  *\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
344 \r
345 /******************************************************************************\r
346  * TRC_CFG_USE_TRACE_ASSERT\r
347  *\r
348  * Macro which should be defined as either zero (0) or one (1). \r
349  * Default is 1.\r
350  *\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
356  *\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
362 \r
363 /*******************************************************************************\r
364  * TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER\r
365  *\r
366  * Macro which should be defined as an integer value.\r
367  *\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
373  * frequent events. \r
374  *\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
379  *  \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
383  *\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
387  *\r
388  * Examples:\r
389  *\r
390  *  traceString chn1 = xTraceRegisterString("Channel 1");\r
391  *  traceString fmt1 = xTraceRegisterString("Event!");\r
392  *  traceUBChannel UBCh1 = xTraceRegisterUBChannel(chn1, fmt1);\r
393  *                                              \r
394  *  traceString chn2 = xTraceRegisterString("Channel 2");\r
395  *  traceString fmt2 = xTraceRegisterString("X: %d, Y: %d");\r
396  *      traceUBChannel UBCh2 = xTraceRegisterUBChannel(chn2, fmt2);\r
397  *      \r
398  *  // Result in "[Channel 1] Event!"\r
399  *      vTraceUBEvent(UBCh1); \r
400  *\r
401  *  // Result in "[Channel 2] X: 23, Y: 19"\r
402  *      vTraceUBData(UBCh2, 23, 19);\r
403  *\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
411  *\r
412  *  // Creates a new UB channel ("Channel 2", "%Z: %d")\r
413  *  vTracePrintF(chn2, "%Z: %d", value1);\r
414  *  \r
415  *  // Finds the existing UB channel\r
416  *  vTracePrintF(chn2, "%Z: %d", value2);\r
417  \r
418  ******************************************************************************/\r
419 #define TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER 0\r
420 \r
421 /*******************************************************************************\r
422  * TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE\r
423  *\r
424  * Macro which should be defined as an integer value.\r
425  *\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
428  *\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
432 \r
433 /*******************************************************************************\r
434  * TRC_CFG_UB_CHANNELS\r
435  *\r
436  * Macro which should be defined as an integer value.\r
437  *\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
442  *\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
446 \r
447 /*******************************************************************************\r
448  * TRC_CFG_ISR_TAILCHAINING_THRESHOLD\r
449  *\r
450  * Macro which should be defined as an integer value.\r
451  *\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
454  * \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
459  *\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
463  *\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
466  *\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
471 \r
472 #endif /*TRC_SNAPSHOT_CONFIG_H*/\r