git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/FreeRTOS-Plus-Trace/Include/trcBase.h

   1 /*******************************************************************************\r
   2  * FreeRTOS+Trace v2.2.3 Recorder Library\r
   3  * Percepio AB, www.percepio.se\r
   4  *\r
   5  * trcBase.h\r
   6  *\r
   7  * Core functionallity of the FreeRTOS+Trace recorder library.\r
   8  *\r
   9  * Terms of Use\r
  10  * This software is copyright Percepio AB. The recorder library is free for\r
  11  * use together with Percepio products. You may distribute the recorder library\r
  12  * in its original form, including modifications in trcPort.c and trcPort.h\r
  13  * given that these modification are clearly marked as your own modifications\r
  14  * and documented in the initial comment section of these source files. \r
  15  * This software is the intellectual property of Percepio AB and may not be \r
  16  * sold or in other ways commercially redistributed without explicit written \r
  17  * permission by Percepio AB.\r
  18  *\r
  19  * Disclaimer \r
  20  * The trace tool and recorder library is being delivered to you AS IS and \r
  21  * Percepio AB makes no warranty as to its use or performance. Percepio AB does \r
  22  * not and cannot warrant the performance or results you may obtain by using the \r
  23  * software or documentation. Percepio AB make no warranties, express or \r
  24  * implied, as to noninfringement of third party rights, merchantability, or \r
  25  * fitness for any particular purpose. In no event will Percepio AB, its \r
  26  * technology partners, or distributors be liable to you for any consequential, \r
  27  * incidental or special damages, including any lost profits or lost savings, \r
  28  * even if a representative of Percepio AB has been advised of the possibility \r
  29  * of such damages, or for any claim by any third party. Some jurisdictions do \r
  30  * not allow the exclusion or limitation of incidental, consequential or special \r
  31  * damages, or the exclusion of implied warranties or limitations on how long an \r
  32  * implied warranty may last, so the above limitations may not apply to you.\r
  33  * \r
  34  * FreeRTOS+Trace is available as Free Edition and in two premium editions.\r
  35  * You may use the premium features during 30 days for evaluation.\r
  36  * Download FreeRTOS+Trace at http://www.percepio.se/index.php?page=downloads\r
  37  *\r
  38  * Copyright Percepio AB, 2012.\r
  39  * www.percepio.se\r
  40  ******************************************************************************/\r
  41 \r
  42 #ifndef TRCBASE_H\r
  43 #define TRCBASE_H\r
  44 \r
  45 #include <stdio.h>\r
  46 #include <string.h>\r
  47 #include <stdint.h>\r
  48 #include "FreeRTOS.h"\r
  49 #include "trcConfig.h"\r
  50 #include "trcTypes.h"\r
  51 #include "trcPort.h"\r
  52 \r
  53 \r
  54 #define NCLASSES 5\r
  55 #define VERSION 0x1AA1\r
  56 #define MINOR_VERSION 1\r
  57 #define STORE_MODE_STOP_WHEN_FULL 1\r
  58 #define STORE_MODE_RING_BUFFER 2\r
  59 #define TRACE_DATA_ALLOCATION_STATIC 1\r
  60 #define TRACE_DATA_ALLOCATION_DYNAMIC 2\r
  61 \r
  62 /******************************************************************************\r
  63  * Object Property Table\r
  64  * The Object Table contains name and other properties of the objects (tasks,\r
  65  * queues, mutexes, etc). The below data structures defines the properties of\r
  66  * each object class and are used to cast the byte buffer into a cleaner format.\r
  67  *\r
  68  * The values in the object table are continously overwritten and always \r
  69  * represent the current state. If a property is changed during runtime, the OLD \r
  70  * value should be stored in the trace buffer, not the new value (since the new \r
  71  * value is found in the Object Property Table).\r
  72  * For close events this mechanism is the old names are stored in the symbol\r
  73  * table), for "priority set" (the old priority is stored in the event data)\r
  74  * and for "isActive", where the value decides is the taskswitch event type\r
  75  * should be "new" or "resume".\r
  76  ******************************************************************************/\r
  77 \r
  78 /* The size of the Object Property Table entries, in bytes, per object */\r
  79 \r
  80 /* Queue properties (except name):     current number of message in queue */\r
  81 #define PropertyTableSizeQueue         (NameLenQueue + 1)      \r
  82 \r
  83 /* Semaphore properties (except name): state (signaled = 1, cleared = 0) */\r
  84 #define PropertyTableSizeSemaphore     (NameLenSemaphore + 1) \r
  85 \r
  86 /* Mutex properties (except name):     owner (task handle, 0 = free) */\r
  87 #define PropertyTableSizeMutex         (NameLenMutex + 1)         \r
  88 \r
  89 /* Task properties (except name):      Byte 0: Current priority\r
  90                                        Byte 1: state (if already active) \r
  91                                        Byte 2: InstanceFinishEvent_ServiceCode\r
  92                                        Byte 3: InstanceFinishEvent_ObjHandle */\r
  93 #define PropertyTableSizeTask         (NameLenTask + 4)\r
  94 \r
  95 /* ISR properties:                     Byte 0: priority\r
  96                                        Byte 1: state (if already active) */\r
  97 #define PropertyTableSizeISR          (NameLenISR + 2)\r
  98 \r
  99 /* The layout of the byte array representing the Object Property Table */\r
 100 #define StartIndexQueue            0\r
 101 #define StartIndexSemaphore        StartIndexQueue     + NQueue * PropertyTableSizeQueue\r
 102 #define StartIndexMutex            StartIndexSemaphore + NSemaphore * PropertyTableSizeSemaphore\r
 103 #define StartIndexTask             StartIndexMutex     + NMutex * PropertyTableSizeMutex\r
 104 #define StartIndexISR              StartIndexTask      + NTask * PropertyTableSizeTask\r
 105 #define DynObjTableSize            StartIndexISR       + NISR * PropertyTableSizeISR\r
 106 \r
 107 typedef struct\r
 108 {\r
 109     /* = NCLASSES */\r
 110     uint32_t NumberOfObjectClasses;\r
 111     \r
 112     uint32_t ObjectPropertyTableSizeInBytes;\r
 113         \r
 114     /* This is used to calculate the index in the dynamic object table \r
 115     (handle - 1 - nofStaticObjects = index)*/\r
 116     uint8_t NumberOfObjectsPerClass[ 4*((NCLASSES+3)/4)];      \r
 117 \r
 118     /* Allocation size rounded up to the closest multiple of 4 */    \r
 119     uint8_t NameLengthPerClass[ 4*((NCLASSES+3)/4) ];\r
 120     \r
 121     uint8_t TotalPropertyBytesPerClass[ 4*((NCLASSES+3)/4) ];\r
 122     \r
 123     /* Allocation size rounded up to the closest multiple of 2 */\r
 124     uint16_t StartIndexOfClass[ 2*((NCLASSES+1)/2) ];\r
 125 \r
 126     /* The actual handles issued, should be Initiated to all zeros */     \r
 127     uint8_t objbytes[ 4*((DynObjTableSize+3)/4) ];\r
 128 } ObjectPropertyTableType;\r
 129 \r
 130 /* Symbol table data structure */\r
 131 typedef struct\r
 132 {\r
 133     /* = SYMBOL_HISTORY_TABLE_SIZE_IN_BYTES */\r
 134     uint32_t symTableSize;                       \r
 135         \r
 136     /* Entry 0 is reserved. Any reference to entry 0 implies NULL*/\r
 137     uint32_t nextFreeSymbolIndex;         \r
 138         \r
 139     /* Size rounded up to closest multiple of 4, to avoid alignment issues*/\r
 140     uint8_t symbytes[4*((SYMBOL_TABLE_SIZE+3)/4)];           \r
 141         \r
 142     /* Used for lookups - Up to 64 linked lists within the symbol table \r
 143     connecting all entries with the same 6 bit checksum. \r
 144     This field holds the current list heads. Should be initiated to zeros */\r
 145     uint16_t latestEntryOfChecksum[64];              \r
 146 } symbolTableType;\r
 147 \r
 148 \r
 149 /*******************************************************************************\r
 150  * The data structures of the different events, all 4 bytes long \r
 151  ******************************************************************************/\r
 152 \r
 153 typedef struct\r
 154 {\r
 155     uint8_t type;                \r
 156     objectHandleType objHandle;\r
 157     uint16_t dts;    /* differential timestamp - time since last event */            \r
 158 } TSEvent;\r
 159 \r
 160 typedef struct\r
 161 {\r
 162     uint8_t type;\r
 163     uint8_t objHandle;\r
 164     uint16_t dts;\r
 165 } KernelCall;\r
 166 \r
 167 typedef struct\r
 168 {\r
 169     uint8_t type;\r
 170     objectHandleType objHandle;\r
 171     uint8_t param;\r
 172     uint8_t dts;                \r
 173 } KernelCallWithParamAndHandle;\r
 174 \r
 175 typedef struct\r
 176 {\r
 177     uint8_t type;\r
 178     uint8_t dts;                \r
 179     uint16_t param;\r
 180 } KernelCallWithParam16;\r
 181 \r
 182 typedef struct\r
 183 {\r
 184     uint8_t type;\r
 185     objectHandleType objHandle;    /* the handle of the closed object */\r
 186     uint16_t symbolIndex;          /* the name of the closed object */\r
 187 } ObjCloseNameEvent;\r
 188 \r
 189 typedef struct\r
 190 {\r
 191     uint8_t type;\r
 192     uint8_t arg1;            \r
 193     uint8_t arg2;        \r
 194     uint8_t arg3;        \r
 195 } ObjClosePropEvent;\r
 196 \r
 197 typedef struct\r
 198 {\r
 199     uint8_t type;\r
 200     uint8_t dts;                \r
 201     uint16_t payload;         /* the name of the user event */\r
 202 } UserEvent;\r
 203 \r
 204 typedef struct\r
 205 {\r
 206     uint8_t type;            \r
 207     \r
 208     /* 8 bits extra for storing DTS, if it does not fit in ordinary event \r
 209     (this one is always MSB if used) */\r
 210     uint8_t xts_8;            \r
 211     \r
 212     /* 16 bits extra for storing DTS, if it does not fit in ordinary event. */\r
 213     uint16_t xts_16;          \r
 214 } XTSEvent;\r
 215 \r
 216 \r
 217 /*******************************************************************************\r
 218  * The main datastructure, read by FreeRTOS+Trace from the RAM dump\r
 219  ******************************************************************************/\r
 220 \r
 221 typedef struct\r
 222 {    \r
 223     uint8_t startmarker0;\r
 224     uint8_t startmarker1;\r
 225     uint8_t startmarker2;\r
 226     uint8_t startmarker3;\r
 227     uint8_t startmarker4;\r
 228     uint8_t startmarker5;\r
 229     uint8_t startmarker6;\r
 230     uint8_t startmarker7;\r
 231     uint8_t startmarker8;\r
 232     uint8_t startmarker9;\r
 233     uint8_t startmarker10;\r
 234     uint8_t startmarker11;\r
 235 \r
 236     /* For FreeRTOS: 0x1AA1 */\r
 237     uint16_t version;     \r
 238     \r
 239     /* Currently 1 for v2.2.2 (0 earlier)*/\r
 240     uint8_t minor_version;\r
 241     \r
 242     /* This should be 0 if lower irq priority values implies higher priority \r
 243     levels, such as on ARM Cortex M. If the opposite scheme is used, i.e., \r
 244     if higher irq priority values means higher priority, this should be 1. */ \r
 245     uint8_t irq_priority_order;\r
 246             \r
 247     /* sizeof(RecorderDataType) - just for control */\r
 248     uint32_t filesize;     \r
 249         \r
 250     /* Current number of events recorded */\r
 251     uint32_t numEvents;\r
 252         \r
 253     /* The buffer size, in number of event records */\r
 254     uint32_t maxEvents;\r
 255         \r
 256     /* The event buffer index, where to write the next event */\r
 257     uint32_t nextFreeIndex;\r
 258         \r
 259     /* 1 if the buffer is full, 0 otherwise */\r
 260     uint32_t bufferIsFull;\r
 261 \r
 262     /* The frequency of the clock/timer/counter used as time base */\r
 263     uint32_t frequency;\r
 264 \r
 265     /* The absolute timestamp of the last stored event, in the native \r
 266     timebase, modulo frequency! */\r
 267     uint32_t absTimeLastEvent;    \r
 268     \r
 269     /* The number of seconds in total - lasts for 136 years */\r
 270     uint32_t absTimeLastEventSecond;    \r
 271     \r
 272     /* 1 if the recorder has been started, 0 if not yet started or stopped.\r
 273     This is a 32 bit variable due to alignment issues. */\r
 274     uint32_t recorderActive;      \r
 275 \r
 276     /* For storing a Team License key */\r
 277     uint8_t teamLicenceKey[32];\r
 278 \r
 279     /* 0xF0F0F0F0 - for control only */\r
 280     int32_t debugMarker0;                    \r
 281 \r
 282     /* The Object Property Table holds information about currently active\r
 283     tasks, queues, and other recorded objects. This is updated on each\r
 284     create call and includes object name and other properties. */\r
 285     ObjectPropertyTableType ObjectPropertyTable;\r
 286 \r
 287     /* 0xF1F1F1F1 - for control only */ \r
 288     int32_t debugMarker1;                    \r
 289 \r
 290     /* The Symbol Table stores strings for User Events and is also used to \r
 291     store names of deleted objects, which still may be in the trace but no \r
 292     longer are available. */        \r
 293     symbolTableType SymbolTable;\r
 294 \r
 295     /* For includsion of float support, and for endian detection of floats. \r
 296     The value should be (float)1 or (uint32_t)0 */    \r
 297 #if (INCLUDE_FLOAT_SUPPORT == 1)\r
 298     float exampleFloatEncoding;              \r
 299 #else\r
 300     uint32_t exampleFloatEncoding;              \r
 301 #endif\r
 302     /* This is non-zero if an internal error occured in the recorder, e.g., if\r
 303     one of the Nxxx constants was too small. The systemInfo string will then \r
 304     contain an error message that is displayed when attempting to view the \r
 305     trace file. */\r
 306     uint32_t internalErrorOccured;\r
 307     \r
 308     /* 0xF2F2F2F2 - for control only */ \r
 309     int32_t debugMarker2;                    \r
 310       \r
 311     /* Generic system information string, presented in the tool. Note that this \r
 312     is also used for storing any internal error messages from the recorder, so\r
 313     do not make TRACE_DESCRIPTION_MAX_LENGTH too small. 80 is recommended. */\r
 314     char systemInfo[TRACE_DESCRIPTION_MAX_LENGTH];                   \r
 315 \r
 316     /* 0xF3F3F3F3 - for control only */\r
 317     int32_t debugMarker3;                    \r
 318 \r
 319     /* The event data, in 4-byte records */\r
 320     uint8_t eventData[ EVENT_BUFFER_SIZE * 4 ];\r
 321 \r
 322     uint8_t endmarker0;\r
 323     uint8_t endmarker1;\r
 324     uint8_t endmarker2;\r
 325     uint8_t endmarker3;\r
 326     uint8_t endmarker4;\r
 327     uint8_t endmarker5;\r
 328     uint8_t endmarker6;\r
 329     uint8_t endmarker7;\r
 330     uint8_t endmarker8;\r
 331     uint8_t endmarker9;\r
 332     uint8_t endmarker10;\r
 333     uint8_t endmarker11;\r
 334 \r
 335 } RecorderDataType;\r
 336 \r
 337 extern RecorderDataType* RecorderDataPtr;\r
 338 \r
 339 /******************************************************************************\r
 340  * ObjectHandleStack\r
 341  * This data-structure is used to provide a mechanism for 1-byte trace object\r
 342  * handles. This way, only 1 byte is necessary instead of 4 bytes (a pointer)\r
 343  * when storing a reference to an object. This allows for up to 255 objects of\r
 344  * each object class - Task, ISR, Semaphore, CountingSemaphore, Mutex and Queue,\r
 345  * active at any given moment. There can be more "historic" objects, that have\r
 346  * been deleted - that number is only limited by the size of the symbol table.\r
 347  * Note that handle zero (0) is not used, it is a code for an invalid handle.\r
 348  *\r
 349  * This data structure keeps track of the FREE handles, not the handles in use.\r
 350  * This datastructure contains one stack per object class. When a handle is\r
 351  * allocated to an object, the next free handle is popped from the stack. When\r
 352  * a handle is released (on object delete), it is pushed back on the stack.\r
 353  * Note that there is no initialization code that pushed the free handles\r
 354  * initially, that is not necessary due to the following optimization:\r
 355  *\r
 356  * The stack of handles (objectHandles) is initially all zeros. Since zero\r
 357  * is not a valid handle, that is a signal of additional handles needed.\r
 358  * If a zero is received when popping a new handle, it is replaced by the\r
 359  * index of the popped handle instead.\r
 360  *\r
 361  *****************************************************************************/\r
 362 typedef struct\r
 363 {\r
 364     /* For each object class, the index of the next handle to allocate */\r
 365     int16_t indexOfNextAvailableHandle[ NCLASSES ];              \r
 366 \r
 367     /* The lowest index of this class (constant) */        \r
 368     int16_t lowestIndexOfClass[ NCLASSES ];                    \r
 369         \r
 370     /* The highest index of this class (constant) */\r
 371     int16_t highestIndexOfClass[ NCLASSES ];    \r
 372         \r
 373     /* The highest use count for this class (for statistics) */\r
 374     int16_t handleCountWaterMarksOfClass[ NCLASSES ];                \r
 375         \r
 376     /* The free object handles - a set of stacks within this array */\r
 377     objectHandleType objectHandles[ NTask+NISR+NSemaphore+NMutex+NQueue ];\r
 378 \r
 379 } objectHandleStackType;\r
 380 \r
 381 /* Internal data */\r
 382 \r
 383 extern objectHandleStackType objectHandleStacks;\r
 384 \r
 385 extern uint8_t taskFlags[NTask];\r
 386 \r
 387 /* Internal functions */\r
 388 \r
 389 uint32_t prvTraceGetDTS(uint32_t param_maxDTS);\r
 390 \r
 391 void prvTraceGetChecksum(const char *pname, uint8_t* pcrc, uint8_t* plength);\r
 392 \r
 393 traceLabel prvTraceCreateSymbolTableEntry(const char* name, \r
 394                                           uint8_t crc6, \r
 395                                           uint8_t len, \r
 396                                           traceLabel channel);\r
 397 \r
 398 traceLabel prvTraceLookupSymbolTableEntry(const char* name, \r
 399                                           uint8_t crc6, \r
 400                                           uint8_t len, \r
 401                                           traceLabel channel);\r
 402 \r
 403 traceLabel prvTraceOpenSymbol(const char* name, traceLabel userEventChannel);\r
 404 \r
 405 void prvTraceUpdateCounters(void);\r
 406 \r
 407 void prvCheckDataToBeOverwrittenForMultiEntryUserEvents(uint32_t nEntries);\r
 408 \r
 409 objectHandleType xTraceGetObjectHandle(traceObjectClass objectclass);\r
 410 \r
 411 void vTraceFreeObjectHandle(traceObjectClass objectclass, \r
 412                             objectHandleType handle);\r
 413 \r
 414 void vTraceSetObjectName(traceObjectClass objectclass, \r
 415                          objectHandleType handle, \r
 416                          const char* name);\r
 417 \r
 418 void* xTraceNextFreeEventBufferSlot(void);\r
 419 \r
 420 uint32_t uiIndexOfObject(objectHandleType objecthandle, \r
 421     uint8_t objectclass);\r
 422 \r
 423 \r
 424 /*******************************************************************************\r
 425  * vTraceError\r
 426  *\r
 427  * Called by various parts in the recorder. Stops the recorder and stores a \r
 428  * pointer to an error message, which is printed by the monitor task.\r
 429  ******************************************************************************/\r
 430 void vTraceError(char* msg);\r
 431 \r
 432 /*******************************************************************************\r
 433  * xTraceGetLastError\r
 434  *\r
 435  * Gives the last error message, if any. NULL if no error message is stored.\r
 436  * The message is cleared on read.\r
 437  ******************************************************************************/\r
 438 char* xTraceGetLastError(void);\r
 439 \r
 440 /*******************************************************************************\r
 441  * xTraceInitTraceData\r
 442  *\r
 443  * Allocates and initializes the recorder datastructure, based on the constants\r
 444  * in trcConfig.h. This allows for allocating the data on the heap, instead of\r
 445  * using a static declaration.\r
 446  ******************************************************************************/\r
 447 RecorderDataType* xTraceInitTraceData(void);\r
 448 \r
 449 /* Internal macros */\r
 450 \r
 451 #define PROPERTY_NAME_GET(objectclass, objecthandle) \\r
 452 (const char*)(& RecorderDataPtr->ObjectPropertyTable.objbytes \\r
 453 [uiIndexOfObject(objecthandle, objectclass)])\r
 454 \r
 455 #define PROPERTY_OBJECT_STATE(objectclass, handle) \\r
 456 RecorderDataPtr->ObjectPropertyTable.objbytes[uiIndexOfObject(handle, objectclass) \\r
 457 + RecorderDataPtr->ObjectPropertyTable.NameLengthPerClass[objectclass]]\r
 458 \r
 459 #define PROPERTY_ACTOR_PRIORITY(objectclass, handle) \\r
 460 RecorderDataPtr->ObjectPropertyTable.objbytes[uiIndexOfObject(handle, objectclass) \\r
 461 + RecorderDataPtr->ObjectPropertyTable.NameLengthPerClass[objectclass] + 1]\r
 462 \r
 463 #define PROPERTY_TASK_IFE_SERVICECODE(handle) \\r
 464 RecorderDataPtr->ObjectPropertyTable.objbytes \\r
 465 [uiIndexOfObject(handle, TRACE_CLASS_TASK) \\r
 466 + RecorderDataPtr->ObjectPropertyTable.NameLengthPerClass[TRACE_CLASS_TASK]+2]\r
 467 \r
 468 #define PROPERTY_TASK_IFE_OBJHANDLE(handle) \\r
 469 RecorderDataPtr->ObjectPropertyTable.objbytes \\r
 470 [uiIndexOfObject(handle, TRACE_CLASS_TASK) \\r
 471 +  RecorderDataPtr->ObjectPropertyTable.NameLengthPerClass[TRACE_CLASS_TASK]+3]\r
 472 \r
 473 #define TASK_FLAG_BITMASK_ExcludeTaskFromTrace 1\r
 474 #define TASK_FLAG_BITMASK_MarkNextEventAsTaskInstanceFinish 2\r
 475 \r
 476 #define SET_TASK_FLAG_ISEXCLUDED(taskHandle) taskFlags[taskHandle] |= 0x01\r
 477 #define CLEAR_TASK_FLAG_ISEXCLUDED(taskHandle) taskFlags[taskHandle] &= 0xFE\r
 478 #define GET_TASK_FLAG_ISEXCLUDED(taskHandle) (taskFlags[taskHandle] & 0x01)\r
 479 \r
 480 #define SET_TASK_FLAG_MARKIFE(taskHandle) taskFlags[taskHandle] |= 0x02\r
 481 #define CLEAR_TASK_FLAG_MARKIFE(taskHandle) taskFlags[taskHandle] &= 0xFD\r
 482 #define GET_TASK_FLAG_MARKIFE(taskHandle) (taskFlags[taskHandle] & 0x02)\r
 483 \r
 484 \r
 485 /* For debug printouts - the names of the object classes */\r
 486 extern char OBJECTCLASSNAME[NCLASSES][10];\r
 487 /*=\r
 488 {\r
 489         "QUEUE"\r
 490         "SEMAPHORE",\r
 491         "MUTEX",\r
 492         "TASK",\r
 493         "ISR"\r
 494 };*/\r
 495 \r
 496 #endif\r
 497 \r