git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace/config/trcSnapshotConfig.h

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