git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Demo/FreeRTOS_Plus_UDP_and_CLI_LPC1830_GCC/ThirdParty/TraceRecorderSrc/Configuration - template/trcConfig.h

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