]> begriffs open source - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace/ConfigurationTemplate/trcConfig.h
Update to latest FreeRTOS+Trace recorder code.
[freertos] / FreeRTOS-Plus / Source / FreeRTOS-Plus-Trace / ConfigurationTemplate / trcConfig.h
1 /*******************************************************************************\r
2  * Tracealyzer v2.4.1 Recorder Library\r
3  * Percepio AB, www.percepio.com\r
4  *\r
5  * trcConfig.h\r
6  *\r
7  * Configuration parameters for the trace recorder library. Before using the \r
8  * trace recorder library, please check that the default settings are \r
9  * appropriate for your system, and if necessary adjust these. Most likely, you \r
10  * will need to adjust the NTask, NISR, NQueue, NMutex and NSemaphore values to \r
11  * reflect the number of such objects in your system. These may be \r
12  * over-approximated, although larger values values implies more RAM usage.\r
13  *\r
14  * Terms of Use\r
15  * This software is copyright Percepio AB. The recorder library is free for\r
16  * use together with Percepio products. You may distribute the recorder library\r
17  * in its original form, including modifications in trcHardwarePort.c/.h\r
18  * given that these modification are clearly marked as your own modifications\r
19  * and documented in the initial comment section of these source files. \r
20  * This software is the intellectual property of Percepio AB and may not be \r
21  * sold or in other ways commercially redistributed without explicit written \r
22  * permission by Percepio AB.\r
23  *\r
24  * Disclaimer \r
25  * The trace tool and recorder library is being delivered to you AS IS and \r
26  * Percepio AB makes no warranty as to its use or performance. Percepio AB does \r
27  * not and cannot warrant the performance or results you may obtain by using the \r
28  * software or documentation. Percepio AB make no warranties, express or \r
29  * implied, as to noninfringement of third party rights, merchantability, or \r
30  * fitness for any particular purpose. In no event will Percepio AB, its \r
31  * technology partners, or distributors be liable to you for any consequential, \r
32  * incidental or special damages, including any lost profits or lost savings, \r
33  * even if a representative of Percepio AB has been advised of the possibility \r
34  * of such damages, or for any claim by any third party. Some jurisdictions do \r
35  * not allow the exclusion or limitation of incidental, consequential or special \r
36  * damages, or the exclusion of implied warranties or limitations on how long an \r
37  * implied warranty may last, so the above limitations may not apply to you.\r
38  *\r
39  * Copyright Percepio AB, 2013.\r
40  * www.percepio.com\r
41  ******************************************************************************/\r
42 \r
43 #ifndef TRCCONFIG_H\r
44 #define TRCCONFIG_H\r
45 \r
46 /*******************************************************************************\r
47  * CONFIGURATION RELATED TO CAPACITY AND ALLOCATION \r
48  ******************************************************************************/\r
49 \r
50 /*******************************************************************************\r
51  * EVENT_BUFFER_SIZE\r
52  *\r
53  * Macro which should be defined as an integer value.\r
54  *\r
55  * This defines the capacity of the event buffer, i.e., the number of records\r
56  * it may store. Each registered event typically use one record (4 byte), but\r
57  * vTracePrintF may use multiple records depending on the number of data args.\r
58  ******************************************************************************/\r
59 \r
60 #define EVENT_BUFFER_SIZE 4000 /* Adjust wrt. to available RAM */\r
61 \r
62 \r
63 /*******************************************************************************\r
64  * USE_LINKER_PRAGMA\r
65  *\r
66  * Macro which should be defined as an integer value, default is 0.\r
67  *\r
68  * If this is 1, the header file "recorderdata_linker_pragma.h" is included just\r
69  * before the declaration of RecorderData (in trcBase.c), i.e., the trace data \r
70  * structure. This allows the user to specify a pragma with linker options. \r
71  *\r
72  * Example (for IAR Embedded Workbench and NXP LPC17xx):\r
73  * #pragma location="AHB_RAM_MEMORY"\r
74  * \r
75  * This example instructs the IAR linker to place RecorderData in another RAM \r
76  * bank, the AHB RAM. This can also be used for other compilers with a similar\r
77  * pragmas for linker options.\r
78  * \r
79  * Note that this only applies if using static allocation, see below.\r
80  ******************************************************************************/\r
81 \r
82 #define USE_LINKER_PRAGMA 0\r
83 \r
84 \r
85 /*******************************************************************************\r
86  * SYMBOL_TABLE_SIZE\r
87  *\r
88  * Macro which should be defined as an integer value.\r
89  *\r
90  * This defines the capacity of the symbol table, in bytes. This symbol table \r
91  * stores User Events labels and names of deleted tasks, queues, or other kernel\r
92  * objects. Note that the names of active objects not stored here but in the \r
93  * Object Table. Thus, if you don't use User Events or delete any kernel \r
94  * objects you set this to zero (0) to minimize RAM usage.\r
95  ******************************************************************************/\r
96 #define SYMBOL_TABLE_SIZE 1000\r
97 \r
98 /*******************************************************************************\r
99  * USE_SEPARATE_USER_EVENT_BUFFER\r
100  *\r
101  * Macro which should be defined as an integer value.\r
102  * Default is zero (0).\r
103  *\r
104  * This enables and disables the use of the separate user event buffer.\r
105  *\r
106  * Note: When using the separate user event buffer, you may get an artificial\r
107  * task instance named "Unknown actor". This is added as a placeholder when the \r
108  * user event history is longer than the task scheduling history.\r
109  ******************************************************************************/\r
110 #define USE_SEPARATE_USER_EVENT_BUFFER 0\r
111 \r
112 /*******************************************************************************\r
113  * USER_EVENT_BUFFER_SIZE\r
114  *\r
115  * Macro which should be defined as an integer value.\r
116  *\r
117  * This defines the capacity of the user event buffer, in number of slots.\r
118  * A single user event can use between 1 and X slots, depending on the data.\r
119  *\r
120  * Only in use if USE_SEPARATE_USER_EVENT_BUFFER is set to 1.\r
121  ******************************************************************************/\r
122 #define USER_EVENT_BUFFER_SIZE 500\r
123 \r
124 /*******************************************************************************\r
125  * USER_EVENT_CHANNELS\r
126  *\r
127  * Macro which should be defined as an integer value.\r
128  *\r
129  * This defines the number of allowed user event channels.\r
130  *\r
131  * Only in use if USE_SEPARATE_USER_EVENT_BUFFER is set to 1.\r
132  ******************************************************************************/\r
133 #define CHANNEL_FORMAT_PAIRS 32\r
134 \r
135 /*******************************************************************************\r
136  * NTask, NISR, NQueue, NSemaphore, NMutex\r
137  *\r
138  * A group of Macros which should be defined as an integer value of zero (0) \r
139  * or larger.\r
140  *\r
141  * This defines the capacity of the Object Property Table - the maximum number\r
142  * of objects active at any given point within each object class.\r
143  * \r
144  * NOTE: In case objects are deleted and created during runtime, this setting\r
145  * does not limit the total amount of objects, only the number of concurrently\r
146  * active objects. \r
147  *\r
148  * Using too small values will give an error message through the vTraceError\r
149  * routine, which makes the error message appear when opening the trace data\r
150  * in Tracealyzer. If you are using the recorder status monitor task,\r
151  * any error messages are displayed in console prints, assuming that the\r
152  * print macro has been defined properly (vConsolePrintMessage). \r
153  *\r
154  * It can be wise to start with very large values for these constants, \r
155  * unless you are very confident on these numbers. Then do a recording and\r
156  * check the actual usage in Tracealyzer. This is shown by selecting\r
157  * View -> Trace Details -> Resource Usage -> Object Table\r
158  * \r
159  * NOTE 2: Remember to account for all tasks created by the kernel, such as the \r
160  * IDLE task, timer task, and any tasks created by other 3rd party \r
161  * software components, such as communication stacks. The recorder also has an \r
162  * optional monitor task to account for, if this is used.\r
163  * Moreover, one task slot is used to indicate "(startup)", i.e., a fictive \r
164  * task that represent the time before the scheduler starts. \r
165  * NTask should thus be at least 2-3 slots larger than your application task count.\r
166  *\r
167  ******************************************************************************/\r
168 #define NTask             15\r
169 #define NISR              5\r
170 #define NQueue            5\r
171 #define NSemaphore        5\r
172 #define NMutex            5\r
173 \r
174 /* Maximum object name length for each class (includes zero termination) */\r
175 #define NameLenTask       15\r
176 #define NameLenISR        15\r
177 #define NameLenQueue      15\r
178 #define NameLenSemaphore  15\r
179 #define NameLenMutex      15\r
180 \r
181 /******************************************************************************\r
182  * TRACE_DESCRIPTION\r
183  *\r
184  * Macro which should be defined as a string.\r
185  *\r
186  * This string is stored in the trace and displayed in Tracealyzer. Can be\r
187  * used to store, e.g., system version or build date. This is also used to store\r
188  * internal error messages from the recorder, which if occurs overwrites the\r
189  * value defined here. This may be maximum 256 chars.\r
190  *****************************************************************************/\r
191 #define TRACE_DESCRIPTION "Tracealyzer Recorder Test Program"\r
192 \r
193 /******************************************************************************\r
194  * TRACE_DESCRIPTION_MAX_LENGTH\r
195  *\r
196  * The maximum length (including zero termination) for the TRACE_DESCRIPTION\r
197  * string. Since this string also is used for internal error messages from the \r
198  * recorder do not make it too short, as this may truncate the error messages.\r
199  * Default is 80. \r
200  * Maximum allowed length is 256 - the trace will fail to load if longer.\r
201  *****************************************************************************/\r
202 #define TRACE_DESCRIPTION_MAX_LENGTH 80\r
203 \r
204 \r
205 /******************************************************************************\r
206  * TRACE_DATA_ALLOCATION\r
207  *\r
208  * This defines how to allocate the recorder data structure, i.e., using a \r
209  * static declaration or using a dynamic allocation in runtime (malloc).\r
210  *\r
211  * Should be one of these two options:\r
212  * - TRACE_DATA_ALLOCATION_STATIC (default)\r
213  * - TRACE_DATA_ALLOCATION_DYNAMIC\r
214  *\r
215  * Using static allocation has the benefits of compile-time errors if the buffer \r
216  * is too large (too large constants in trcConfig.h) and no need to call the \r
217  * initialization routine (xTraceInitTraceData).\r
218  *\r
219  * Using dynamic allocation may give more flexibility in some cases.\r
220  *****************************************************************************/\r
221 \r
222 #define TRACE_DATA_ALLOCATION TRACE_DATA_ALLOCATION_STATIC\r
223 \r
224 \r
225 /******************************************************************************\r
226  * CONFIGURATION REGARDING WHAT CODE/FEATURES TO INCLUDE\r
227  *****************************************************************************/\r
228 \r
229 /******************************************************************************\r
230  * USE_TRACE_ASSERT\r
231  *\r
232  * Macro which should be defined as either zero (0) or one (1). \r
233  * Default is 0.\r
234  *\r
235  * If this is one (1), the TRACE_ASSERT macro will verify that a condition is \r
236  * true. If the condition is false, vTraceError() will be called.\r
237  *****************************************************************************/\r
238 #define USE_TRACE_ASSERT 0\r
239 \r
240 /******************************************************************************\r
241  * INCLUDE_FLOAT_SUPPORT\r
242  *\r
243  * Macro which should be defined as either zero (0) or one (1). \r
244  * Default is 1.\r
245  *\r
246  * If this is zero (0), all references to floating point values are removed,\r
247  * in case floating point values are not supported by the platform used.\r
248  * Floating point values are only used in vTracePrintF and its subroutines, to \r
249  * store float (%f) or double (%lf) argments. \r
250  *\r
251  * Note: vTracePrintF can still be used with integer and string arguments in\r
252  * either case.\r
253  *****************************************************************************/\r
254 #define INCLUDE_FLOAT_SUPPORT 1\r
255 \r
256 /******************************************************************************\r
257  * INCLUDE_USER_EVENTS\r
258  *\r
259  * Macro which should be defined as either zero (0) or one (1). \r
260  * Default is 1.\r
261  *\r
262  * If this is zero (0) the code for creating User Events is excluded to\r
263  * reduce code size. User Events are application-generated events, like \r
264  * "printf" but for the trace log instead of console output. User Events are \r
265  * much faster than a printf and can therefore be used in timing critical code.\r
266  * See vTraceUserEvent() and vTracePrintF() in trcUser.h\r
267  * \r
268  * Note that Tracealyzer Standard Edition or Professional Edition is required\r
269  * for User Events, they are not displayed in Tracealyzer Free Edition.\r
270  *****************************************************************************/\r
271 #define INCLUDE_USER_EVENTS 1\r
272 \r
273 /*****************************************************************************\r
274  * INCLUDE_READY_EVENTS\r
275  *\r
276  * Macro which should be defined as either zero (0) or one (1). \r
277  * Default is 1.\r
278  *\r
279  * If this is zero (0), the code for recording Ready events is \r
280  * excluded. Note, this will make it impossible to calculate the correct\r
281  * response times.\r
282  *****************************************************************************/\r
283 #define INCLUDE_READY_EVENTS 1\r
284 \r
285 /*****************************************************************************\r
286  * INCLUDE_NEW_TIME_EVENTS\r
287  *\r
288  * Macro which should be defined as either zero (0) or one (1). \r
289  * Default is 0.\r
290  *\r
291  * If this is zero (1), events will be generated whenever the os clock is\r
292  * increased.\r
293  *****************************************************************************/\r
294 #define INCLUDE_NEW_TIME_EVENTS 0\r
295 \r
296 /*****************************************************************************\r
297  * INCLUDE_ISR_TRACING\r
298  *\r
299  * Macro which should be defined as either zero (0) or one (1). \r
300  * Default is 1.\r
301  *\r
302  * If this is zero (0), the code for recording Interrupt Service Routines is \r
303  * excluded to reduce code size.\r
304  * \r
305  * Note, if the kernel has no central interrupt dispatcher, recording ISRs \r
306  * require that you insert calls to vTraceStoreISRBegin and vTraceStoreISREnd \r
307  * in your interrupt handlers.\r
308  *****************************************************************************/\r
309 #define INCLUDE_ISR_TRACING 1\r
310 \r
311 /******************************************************************************\r
312  * INCLUDE_OBJECT_DELETE\r
313  * \r
314  * Macro which should be defined as either zero (0) or one (1). \r
315  * Default is 1.\r
316  *\r
317  * This must be enabled (1) if tasks, queues or other \r
318  * traced kernel objects are deleted at runtime. If no deletes are made, this \r
319  * can be set to 0 in order to exclude the delete-handling code.\r
320  *****************************************************************************/\r
321 #define INCLUDE_OBJECT_DELETE 1\r
322 \r
323 /******************************************************************************\r
324  * CONFIGURATION RELATED TO BEHAVIOR\r
325  *****************************************************************************/\r
326 \r
327 /******************************************************************************\r
328  * TRACE_RECORDER_STORE_MODE\r
329  *\r
330  * Macro which should be defined as one of:\r
331  * - TRACE_STORE_MODE_RING_BUFFER\r
332  * - TRACE_STORE_MODE_STOP_WHEN_FULL\r
333  * Default is TRACE_STORE_MODE_RING_BUFFER.\r
334  *\r
335  * With TRACE_RECORDER_STORE_MODE set to TRACE_STORE_MODE_RING_BUFFER, the events are \r
336  * stored in a ring buffer, i.e., where the oldest events are overwritten when \r
337  * the buffer becomes full. This allows you to get the last events leading up \r
338  * to an interesting state, e.g., an error, without having a large trace buffer\r
339  * for string the whole run since startup. In this mode, the recorder can run\r
340  * "forever" as the buffer never gets full, i.e., in the sense that it always\r
341  * has room for more events.\r
342  *\r
343  * To fetch the trace in mode TRACE_STORE_MODE_RING_BUFFER, you need to first halt the\r
344  * system using your debugger and then do a RAM dump, or to explicitly stop the\r
345  * recorder using vTraceStop() and then store/upload the trace data using a\r
346  * task that you need to provide yourself. The trace data is found in the struct\r
347  * RecorderData, initialized in trcBase.c.\r
348  *\r
349  * Note that, if you upload the trace using a RAM dump, i.e., when the system is \r
350  * halted on a breakpoint or by a debugger command, there is no need to stop the \r
351  * recorder first.\r
352  *\r
353  * When TRACE_RECORDER_STORE_MODE is TRACE_STORE_MODE_STOP_WHEN_FULL, the recording is\r
354  * stopped when the buffer becomes full. When the recorder stops itself this way\r
355  * vTracePortEnd() is called which allows for custom actions, such as triggering\r
356  * a task that stores the trace buffer, i.e., in case taking a RAM dump\r
357  * using an on-chip debugger is not possible. In the Windows port, vTracePortEnd\r
358  * saves the trace to file directly, but this is not recommended in a real-time\r
359  * system since the scheduler is blocked during the processing of vTracePortEnd.\r
360  *****************************************************************************/\r
361 \r
362 #define TRACE_RECORDER_STORE_MODE TRACE_STORE_MODE_RING_BUFFER\r
363 \r
364 /******************************************************************************\r
365  * STOP_AFTER_N_EVENTS\r
366  *\r
367  * Macro which should be defined as an integer value, or not defined.\r
368  * Default is -1\r
369  *\r
370  * STOP_AFTER_N_EVENTS is intended for tests of the ring buffer mode (when\r
371  * RECORDER_STORE_MODE is STORE_MODE_RING_BUFFER). It stops the recording when\r
372  * the specified number of events has been observed. This value can be larger\r
373  * than the buffer size, to allow for test of the "wrapping around" that occurs\r
374  * in ring buffer mode . A negative value (or no definition of this macro)\r
375  * disables this feature.\r
376  *****************************************************************************/\r
377 #define STOP_AFTER_N_EVENTS -1\r
378 \r
379 /******************************************************************************\r
380  * USE_IMPLICIT_IFE_RULES\r
381  *\r
382  * Macro which should be defined as either zero (0) or one (1). \r
383  * Default is 1.\r
384  *\r
385  * ### Instance Finish Events (IFE) ###\r
386  *\r
387  * For tasks with "infinite" main loops (non-terminating tasks), the concept\r
388  * of a task instance has no clear definition, it is an application-specific\r
389  * thing. Tracealyzer allows you to define Instance Finish Events (IFEs),\r
390  * which marks the point in a cyclic task when the "task instance" ends.\r
391  * The IFE is a blocking kernel call, typically in the main loop of a task\r
392  * which typically reads a message queue, waits for a semaphore or performs\r
393  * an explicit delay.\r
394  *\r
395  * If USE_IMPLICIT_IFE_RULES is one (1), the kernel macros (trcKernelPort.h)\r
396  * will define what kernel calls are considered by default to be IFEs.\r
397  *\r
398  * However, Implicit IFEs only applies to blocking kernel calls. If a\r
399  * service reads a message without blocking, it does not create a new\r
400  * instance since no blocking occurred.\r
401  *\r
402  * Moreover, the actual IFE might sometimes be another blocking call. We \r
403  * therefore allow for user-defined Explicit IFEs by calling\r
404  *\r
405  *     vTraceTaskInstanceIsFinished()\r
406  *\r
407  * right before the kernel call considered as IFE. This does not create an\r
408  * additional event but instead stores the service code and object handle\r
409  * of the IFE call as properties of the task.\r
410  *\r
411  * If using Explicit IFEs and the task also calls an Implicit IFE, this may \r
412  * result in additional incorrect task instances.\r
413  * This is solved by disabling the Implicit IFEs for the task, by adding\r
414  * a call to\r
415  * \r
416  *     vTraceTaskSkipDefaultInstanceFinishedEvents()\r
417  * \r
418  * in the very beginning of that task. This allows you to combine Explicit IFEs\r
419  * for some tasks with Implicit IFEs for the rest of the tasks, if\r
420  * USE_IMPLICIT_IFE_RULES is 1.\r
421  *\r
422  * By setting USE_IMPLICIT_IFE_RULES to zero (0), the implicit IFEs are disabled\r
423  * for all tasks. Tasks will then be considered to have a single instance only, \r
424  * covering all execution fragments, unless you define an explicit IFE in each\r
425  * task by calling vTraceTaskInstanceIsFinished before the blocking call.\r
426  *****************************************************************************/\r
427 #define USE_IMPLICIT_IFE_RULES 1\r
428 \r
429 /******************************************************************************\r
430  * INCLUDE_SAVE_TO_FILE\r
431  *\r
432  * Macro which should be defined as either zero (0) or one (1).\r
433  * Default is 0.\r
434  *\r
435  * If enabled (1), the recorder will include code for saving the trace\r
436  * to a local file system.\r
437  ******************************************************************************/\r
438 #ifdef WIN32\r
439     #define INCLUDE_SAVE_TO_FILE 1\r
440 #else\r
441     #define INCLUDE_SAVE_TO_FILE 0\r
442 #endif\r
443 \r
444 /******************************************************************************\r
445  * TRACE_PROGRESS_MONITOR_TASK_PRIORITY\r
446  *\r
447  * Macro which sets the priority of the "recorder status monitor" task.\r
448  *\r
449  * This task, vTraceMonitorTask in trcUser.c, periodically writes\r
450  * the recorder status using the vTraceConsoleMessage macro, which is to\r
451  * be mapped to your console "printf" routine. The task is named TraceMon but \r
452  * is intentionally excluded from the demo trace.\r
453  *\r
454  * Default is tskIDLE_PRIORITY + 1\r
455  * Note that if your system constantly has a high CPU load from high-priority \r
456  * tasks, this might not be get a chance to execute.\r
457  * \r
458  * See vTraceMonitorTask in trcUser.c\r
459  *****************************************************************************/\r
460 #define TRACE_PROGRESS_MONITOR_TASK_PRIORITY (tskIDLE_PRIORITY + 1)\r
461 \r
462 /******************************************************************************\r
463  * TRACE_PROGRESS_MONITOR_TASK_STACKSIZE\r
464  *\r
465  * Macro which sets the stack size of the "recorder status monitor" task.\r
466  *\r
467  * This task, vTraceMonitorTask in trcUser.c, periodically writes\r
468  * the recorder status using the vTraceConsoleMessage macro, which is to\r
469  * be mapped to your console "printf" routine. The task is intentionally \r
470  * excluded from the demo trace.\r
471  *\r
472  * See vTraceMonitorTask in trcUser.c\r
473  *****************************************************************************/\r
474 #define TRACE_PROGRESS_MONITOR_TASK_STACKSIZE 500\r
475 \r
476 /******************************************************************************\r
477  * TRACE_PROGRESS_MONITOR_TASK_PERIOD\r
478  *\r
479  * Macro which sets the period of the "recorder status monitor" task.\r
480  *\r
481  * This task, vTraceMonitorTask in trcUser.c, periodically writes\r
482  * the recorder status using the vTraceConsoleMessage macro, which is to\r
483  * be mapped to your console "printf" routine. The task is named TraceMon but \r
484  * is intentionally excluded from the demo trace.\r
485  *\r
486  * Default is 1000 ticks (typically 1 second). On the Windows port, a lower \r
487  * value is suggested since the Windows port runs very slowly, often 20-40\r
488  * times slower than the simulated time.\r
489  *\r
490  * See vTraceMonitorTask in trcUser.c\r
491  *****************************************************************************/\r
492 #ifdef WIN32\r
493     #define TRACE_PROGRESS_MONITOR_TASK_PERIOD 100\r
494 #else\r
495     #define TRACE_PROGRESS_MONITOR_TASK_PERIOD 1000\r
496 #endif\r
497 \r
498 /******************************************************************************\r
499  * TEAM_LICENSE_CODE\r
500  *\r
501  * Macro which defines a string - the team license code.\r
502  * If no team license is available, this should be an empty string "".\r
503  * This should be maximum 32 chars, including zero-termination.\r
504  *****************************************************************************/\r
505 #define TEAM_LICENSE_CODE ""\r
506 \r
507 #endif\r
508 \r