git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace/trcUser.c

   1 /*******************************************************************************\r
   2  * Tracealyzer v2.6.0 Recorder Library\r
   3  * Percepio AB, www.percepio.com\r
   4  *\r
   5  * trcUser.c\r
   6  *\r
   7  * The public API of the 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 trcHardwarePort.c/.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  * Copyright Percepio AB, 2013.\r
  35  * www.percepio.com\r
  36  ******************************************************************************/\r
  37 #include "FreeRTOS.h"\r
  38 #include "task.h"\r
  39 \r
  40 #include "trcUser.h"\r
  41 \r
  42 #if (USE_TRACEALYZER_RECORDER == 1)\r
  43 \r
  44 #include <string.h>\r
  45 #include <stdarg.h>\r
  46 #include <stdint.h>\r
  47 \r
  48 TRACE_STOP_HOOK vTraceStopHookPtr = (TRACE_STOP_HOOK)0;\r
  49 \r
  50 extern uint8_t inExcludedTask;\r
  51 extern uint8_t nISRactive;\r
  52 extern objectHandleType handle_of_last_logged_task;\r
  53 extern uint32_t dts_min;\r
  54 extern uint32_t hwtc_count_max_after_tick;\r
  55 extern uint32_t hwtc_count_sum_after_tick;\r
  56 extern uint32_t hwtc_count_sum_after_tick_counter;\r
  57 extern char* traceErrorMessage;\r
  58 \r
  59 /*** private functions *******************************************************/\r
  60 void vTracePrintF_Helper(traceLabel eventLabel, const char* formatStr, va_list vl);\r
  61 \r
  62 #if (USE_SEPARATE_USER_EVENT_BUFFER == 1)\r
  63 void vTraceChannelPrintF_Helper(UserEventChannel channelPair, va_list vl);\r
  64 static void prvTraceUserEventHelper1(UserEventChannel channel, traceLabel eventLabel, traceLabel formatLabel, va_list vl);\r
  65 static void prvTraceUserEventHelper2(UserEventChannel channel, uint32_t* data, uint32_t noOfSlots);\r
  66 #endif\r
  67 /*****************************************************************************/\r
  68 \r
  69 \r
  70 \r
  71 /*******************************************************************************\r
  72  * vTraceInitTraceData\r
  73  *\r
  74  * Allocates, if necessary, and initializes the recorder data structure, based\r
  75  * on the constants in trcConfig.h.\r
  76  ******************************************************************************/\r
  77 void vTraceInitTraceData(void)\r
  78 {\r
  79         prvTraceInitTraceData();\r
  80 }\r
  81 \r
  82 /*******************************************************************************\r
  83  * vTraceSetRecorderData\r
  84  *\r
  85  * If custom allocation is used, this function must be called so the recorder\r
  86  * library knows where to save the trace data.\r
  87  ******************************************************************************/\r
  88 #if TRACE_DATA_ALLOCATION == TRACE_DATA_ALLOCATION_CUSTOM\r
  89 void vTraceSetRecorderData(void* pRecorderData)\r
  90 {\r
  91         TRACE_ASSERT(pRecorderData != NULL, "vTraceSetTraceData, pRecorderData == NULL", );\r
  92         RecorderDataPtr = pRecorderData;\r
  93 }\r
  94 #endif\r
  95 \r
  96 /*******************************************************************************\r
  97  * vTraceClear\r
  98  *\r
  99  * Resets the recorder. Only necessary if a restart is desired - this is not\r
 100  * needed in the startup initialization.\r
 101  ******************************************************************************/\r
 102 void vTraceClear(void)\r
 103 {\r
 104     TRACE_SR_ALLOC_CRITICAL_SECTION();\r
 105     trcCRITICAL_SECTION_BEGIN();\r
 106 \r
 107     RecorderDataPtr->absTimeLastEvent = 0;\r
 108     RecorderDataPtr->nextFreeIndex = 0;\r
 109     RecorderDataPtr->numEvents = 0;\r
 110     RecorderDataPtr->bufferIsFull = 0;\r
 111         traceErrorMessage = NULL;\r
 112         RecorderDataPtr->internalErrorOccured = 0;\r
 113 \r
 114     trcCRITICAL_SECTION_END();\r
 115 \r
 116 }\r
 117 \r
 118 /*******************************************************************************\r
 119  * uiTraceStart\r
 120  *\r
 121  * Starts the recorder. The recorder will not be started if an error has been\r
 122  * indicated using vTraceError, e.g. if any of the Nx constants in trcConfig.h\r
 123  * has a too small value (NTASK, NQUEUE, etc).\r
 124  *\r
 125  * Returns 1 if the recorder was started successfully.\r
 126  * Returns 0 if the recorder start was prevented due to a previous internal\r
 127  * error. In that case, check vTraceGetLastError to get the error message.\r
 128  * Any error message is also presented when opening a trace file.\r
 129  ******************************************************************************/\r
 130 \r
 131 uint32_t uiTraceStart(void)\r
 132 {\r
 133         objectHandleType handle;\r
 134     TRACE_SR_ALLOC_CRITICAL_SECTION();\r
 135 \r
 136         handle = 0;\r
 137 \r
 138         if (RecorderDataPtr == NULL)\r
 139         {\r
 140                 vTraceError("RecorderDataPtr is NULL. Call vTraceInitTraceData() before starting trace.");\r
 141                 return 0;\r
 142         }\r
 143     if (traceErrorMessage == NULL)\r
 144     {\r
 145         trcCRITICAL_SECTION_BEGIN();\r
 146         RecorderDataPtr->recorderActive = 1;\r
 147 \r
 148                 handle = TRACE_GET_TASK_NUMBER(TRACE_GET_CURRENT_TASK());\r
 149                 if (handle == 0)\r
 150                 {\r
 151                         /* This occurs if the scheduler is not yet started.\r
 152                         This creates a dummy "(startup)" task entry internally in the\r
 153                         recorder */\r
 154                         handle = xTraceGetObjectHandle(TRACE_CLASS_TASK);\r
 155                         vTraceSetObjectName(TRACE_CLASS_TASK, handle, "(startup)");\r
 156 \r
 157                         vTraceSetPriorityProperty(TRACE_CLASS_TASK, handle, 0);\r
 158                 }\r
 159 \r
 160         vTraceStoreTaskswitch(handle); /* Register the currently running task */\r
 161         trcCRITICAL_SECTION_END();\r
 162     }\r
 163 \r
 164     return RecorderDataPtr->recorderActive;\r
 165 }\r
 166 \r
 167 /*******************************************************************************\r
 168  * vTraceStart\r
 169  *\r
 170  * Starts the recorder. The recorder will not be started if an error has been\r
 171  * indicated using vTraceError, e.g. if any of the Nx constants in trcConfig.h\r
 172  * has a too small value (NTASK, NQUEUE, etc).\r
 173  *\r
 174  * This function is obsolete, but has been saved for backwards compatibility.\r
 175  * We recommend using uiTraceStart instead.\r
 176  ******************************************************************************/\r
 177 void vTraceStart(void)\r
 178 {\r
 179     (void)uiTraceStart();\r
 180 }\r
 181 \r
 182 /*******************************************************************************\r
 183  * vTraceStop\r
 184  *\r
 185  * Stops the recorder. The recording can be resumed by calling vTraceStart.\r
 186  * This does not reset the recorder. Use vTraceClear if that is desired.\r
 187  ******************************************************************************/\r
 188 void vTraceStop(void)\r
 189 {\r
 190     RecorderDataPtr->recorderActive = 0;\r
 191         \r
 192         if (vTraceStopHookPtr != (TRACE_STOP_HOOK)0)\r
 193         {\r
 194                 (*vTraceStopHookPtr)();                      /* Call an application level call back function. */\r
 195         }\r
 196 }\r
 197 \r
 198 /*******************************************************************************\r
 199  * xTraceGetLastError\r
 200  *\r
 201  * Gives the last error message, if any. NULL if no error message is stored.\r
 202  * Any error message is also presented when opening a trace file.\r
 203  ******************************************************************************/\r
 204 char* xTraceGetLastError(void)\r
 205 {\r
 206         return traceErrorMessage;\r
 207 }\r
 208 \r
 209 /*******************************************************************************\r
 210 * vTraceClearError\r
 211 *\r
 212 * Removes any previous error message generated by recorder calling vTraceError. \r
 213 * By calling this function, it may be possible to start/restart the trace \r
 214 * despite errors in the recorder, but there is no guarantee that the trace \r
 215 * recorder will work correctly in that case, depending on the type of error.\r
 216 ******************************************************************************/\r
 217 void vTraceClearError(int resetErrorMessage)\r
 218 {\r
 219         ( void ) resetErrorMessage;\r
 220         traceErrorMessage = NULL;       \r
 221         RecorderDataPtr->internalErrorOccured = 0;\r
 222 }\r
 223 \r
 224 /*******************************************************************************\r
 225  * vTraceGetTraceBuffer\r
 226  *\r
 227  * Returns a pointer to the recorder data structure. Use this together with\r
 228  * uiTraceGetTraceBufferSize if you wish to implement an own store/upload\r
 229  * solution, e.g., in case a debugger connection is not available for uploading\r
 230  * the data.\r
 231  ******************************************************************************/\r
 232 void* vTraceGetTraceBuffer(void)\r
 233 {\r
 234     return RecorderDataPtr;\r
 235 }\r
 236 \r
 237 /*******************************************************************************\r
 238  * uiTraceGetTraceBufferSize\r
 239  *\r
 240  * Gets the size of the recorder data structure. For use together with\r
 241  * vTraceGetTraceBuffer if you wish to implement an own store/upload solution,\r
 242  * e.g., in case a debugger connection is not available for uploading the data.\r
 243  ******************************************************************************/\r
 244 uint32_t uiTraceGetTraceBufferSize(void)\r
 245 {\r
 246     return sizeof(RecorderDataType);\r
 247 }\r
 248 \r
 249 /******************************************************************************\r
 250  * vTraceTaskInstanceIsFinished\r
 251  *\r
 252  * This defines an explicit Instance Finish Event for the current task. It tells\r
 253  * the recorder that the current instance of this task is finished at the \r
 254  * context-switch. This function should be called right before the API function \r
 255  * call considered to be the Instance Finish Event.\r
 256  *****************************************************************************/\r
 257 void vTraceTaskInstanceIsFinished()\r
 258 {\r
 259     if (handle_of_last_logged_task)\r
 260     {\r
 261                 TRACE_PROPERTY_OBJECT_STATE(TRACE_CLASS_TASK, handle_of_last_logged_task) = 0;\r
 262     }\r
 263 }\r
 264 \r
 265 /*******************************************************************************\r
 266  * Interrupt recording functions\r
 267  ******************************************************************************/\r
 268 \r
 269 #if (INCLUDE_ISR_TRACING == 1)\r
 270 \r
 271 #define MAX_ISR_NESTING 16\r
 272 static uint8_t isrstack[MAX_ISR_NESTING];\r
 273 \r
 274 /*******************************************************************************\r
 275  * vTraceSetISRProperties\r
 276  *\r
 277  * Registers an Interrupt Service Routine in the recorder library, This must be\r
 278  * called before using vTraceStoreISRBegin to store ISR events. This is\r
 279  * typically called in the startup of the system, before the scheduler is\r
 280  * started.\r
 281  *\r
 282  * Example:\r
 283  *     #define ID_ISR_TIMER1 1       // lowest valid ID is 1\r
 284  *     #define PRIO_OF_ISR_TIMER1 3  // the hardware priority of the interrupt\r
 285  *     ...\r
 286  *     vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
 287  *     ...\r
 288  *     void ISR_handler()\r
 289  *     {\r
 290  *         vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
 291  *         ...\r
 292  *         vTraceStoreISREnd();\r
 293  *     }\r
 294  *\r
 295  * NOTE: To safely record ISRs, you need to make sure that all traced\r
 296  * interrupts actually are disabled by trcCRITICAL_SECTION_BEGIN(). However,\r
 297  * in some ports this does not disable high priority interrupts!\r
 298  * If an ISR calls vTraceStoreISRBegin while the recorder is busy, it will\r
 299  * stop the recording and give an error message.\r
 300  ******************************************************************************/\r
 301 void vTraceSetISRProperties(objectHandleType handle, const char* name, char priority)\r
 302 {\r
 303         TRACE_ASSERT(handle <= RecorderDataPtr->ObjectPropertyTable.NumberOfObjectsPerClass[TRACE_CLASS_ISR], "vTraceSetISRProperties: Invalid value for handle", );\r
 304         TRACE_ASSERT(name != NULL, "vTraceSetISRProperties: name == NULL", );\r
 305         TRACE_ASSERT(priority >= 0, "vTraceSetISRProperties: Invalid value for priority", );\r
 306 \r
 307     vTraceSetObjectName(TRACE_CLASS_ISR, handle, name);\r
 308     vTraceSetPriorityProperty(TRACE_CLASS_ISR, handle, priority);\r
 309 }\r
 310 \r
 311 #if (SELECTED_PORT == PORT_ARM_CortexM)\r
 312 /******************************************************************************\r
 313  * (Advanced...)\r
 314  *\r
 315  * ISR_TAILCHAINING_THRESHOLD (For Cortex-M devices only)\r
 316  *\r
 317  * ARM Cortex-M devices may execute ISRs back-to-back (tail-chained) without \r
 318  * resuming the previous context in between. Since this is decided in \r
 319  * hardware, we can only detect this indirectly, in the following manner:\r
 320  *\r
 321  * When entering vTraceStoreISRBegin, we check the number of CPU cycles since \r
 322  * the last return of vTraceStoreISREnd. If less or equal to the constant\r
 323  * ISR_TAILCHAINING_THRESHOLD it is assumed that the ISRs executed back-to-back\r
 324  * (tail-chained). In that case, the previously stored RESUME event \r
 325  * (pointed to by ptrLastISRExitEvent) is then deleted to avoid showing a \r
 326  * fragment of the previous context in between the ISR events. The delete is\r
 327  * made by replacing the event code with a XTS16L event, that serves to keep\r
 328  * the differential timestamp from the earlier event.\r
 329  *\r
 330  * The value of ISR_TAILCHAINING_THRESHOLD depends on the interrupt latency of \r
 331  * the processor, on the compiler and on the compiler settings, but should be \r
 332  * around 70 cycles. The default value is 66 cycles, which should be correct when \r
 333  * using GCC with optimizations disabled (-O0) and Cortex-M3/M4.\r
 334  *\r
 335  * To measure this value, see MEASURE_ISR_TAILCHAINING_THRESHOLD below.\r
 336  *\r
 337  * If this value set too low, tail-chained ISRs will incorrectly be shown \r
 338  * separated, with a short fragment of the previous task or ISR in between.\r
 339  * If this value is set too high, you get the opposite effect - separate ISRs \r
 340  * will appear to execute tail-chained and will appear to have higher execution \r
 341  * time and response time (maximum ISR_TAILCHAINING_THRESHOLD cycles more).\r
 342  *****************************************************************************/\r
 343 #define ISR_TAILCHAINING_THRESHOLD 66\r
 344 \r
 345 uint8_t* ptrLastISRExitEvent = NULL;\r
 346 uint32_t DWTCycleCountAtLastISRExit = 0;\r
 347 \r
 348 /******************************************************************************\r
 349  * (Advanced...)\r
 350  *\r
 351  * MEASURE_ISR_TAILCHAINING_THRESHOLD (For Cortex-M devices only)\r
 352  *\r
 353  * Allows for measuring the value of ISR_TAILCHAINING_THRESHOLD (see above).\r
 354  *\r
 355  * This is intended to measure the minimum number of clock cycles from the end\r
 356  * of vTraceStoreISREnd to the beginning of the following vTraceStoreISRBegin.\r
 357  * For this purpose, we assume a test setup using the SysTick interrupt, which \r
 358  * is available on most Cortex-M devices and typically used by the RTOS kernel. \r
 359  * To do the measurement, follow these steps:\r
 360  * \r
 361  * 1. Make sure MEASURE_ISR_TAILCHAINING_THRESHOLD is enabled (defined as 1)\r
 362  *\r
 363  * 2. Temporarily replace your SysTick handler with the following:\r
 364  *    \r
 365  *    void xPortSysTickHandler( void )\r
 366  *    {\r
 367  *       vTraceStoreISRBegin(1); \r
 368  *       vTraceStoreISREnd();\r
 369  *    }\r
 370  *\r
 371  * 3. To make sure that the ISRs execute back-to-back, increase the OS tick \r
 372  *    frequency to a very high level so that the OS tick interrupt execute \r
 373  *    continuously with no application tasks in between. A tick frequency of \r
 374  *    1 MHz (1.000.000) should be sufficient.\r
 375  *\r
 376  * 4. Put a breakpoint in the highest priority task and make sure it is not \r
 377  *    reached. This means that the SysTick handler is executing at maximum rate\r
 378  *    and thereby tail-chained, where the interrupt latency is 6 cycles.\r
 379  *\r
 380  * 5. Let the system run without breakpoints and inspect the value of \r
 381  *    threshold_low_watermark. This is the minimum total latency observed. \r
 382  *    The hardware latency is 6 clock cycles due to the tail-chaining, so the \r
 383  *    software latency (SL) is then SL = threshold_low_watermark - 6.\r
 384  * \r
 385  * The threshold value ISR_TAILCHAINING_THRESHOLD should be SL + 2 * HL, where \r
 386  * HL is the normal hardware interrupt latency, i.e., the number of CPU \r
 387  * cycles to enter or exit the exception handler for an exception in task \r
 388  * context. The HL value is 12-16 depending on core, as shown below.\r
 389  * \r
 390  * Values for ISR_TAILCHAINING_THRESHOLD, assuming SL = 42\r
 391  *   Cortex-M3 and M4 (HL = 12):        66 cycles\r
 392  *   Cortex-M0 (HL = 16):                       74 cycles\r
 393  *   Cortex-M0+ (HL = 15):          72 cycles\r
 394  *\r
 395  * If the ISR_TAILCHAINING_THRESHOLD value is set too low, some tail-chained\r
 396  * ISRs be shown separated, with a short fragment of the previous actor. If \r
 397  * the value is set too high, separate ISRs will appear to execute tail-chained\r
 398  * and for too long time.\r
 399  *****************************************************************************/\r
 400 #define MEASURE_ISR_TAILCHAINING_THRESHOLD 1\r
 401 \r
 402 #if (MEASURE_ISR_TAILCHAINING_THRESHOLD == 1)\r
 403 volatile uint32_t threshold_low_watermark = 2000000000;\r
 404 #endif\r
 405 \r
 406 #endif\r
 407 \r
 408 /*******************************************************************************\r
 409  * vTraceStoreISRBegin\r
 410  *\r
 411  * Registers the beginning of an Interrupt Service Routine.\r
 412  *\r
 413  * Example:\r
 414  *     #define ID_ISR_TIMER1 1       // lowest valid ID is 1\r
 415  *     #define PRIO_OF_ISR_TIMER1 3  // the hardware priority of the interrupt\r
 416  *     ...\r
 417  *     vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
 418  *     ...\r
 419  *     void ISR_handler()\r
 420  *     {\r
 421  *         vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
 422  *         ...\r
 423  *         vTraceStoreISREnd();\r
 424  *     }\r
 425  *\r
 426  ******************************************************************************/\r
 427 void vTraceStoreISRBegin(objectHandleType handle)\r
 428 {\r
 429     uint16_t dts4;\r
 430         #if (SELECTED_PORT == PORT_ARM_CortexM)\r
 431         uint32_t CPUCyclesSinceLastISRExit = DWT_CYCLE_COUNTER - DWTCycleCountAtLastISRExit;\r
 432         #endif  \r
 433     TSEvent* ts;\r
 434     TRACE_SR_ALLOC_CRITICAL_SECTION();\r
 435 \r
 436         ts = NULL;\r
 437 \r
 438 #if (SELECTED_PORT == PORT_ARM_CortexM)\r
 439         if (DWTCycleCountAtLastISRExit > 0)     \r
 440         {\r
 441                 #if (MEASURE_ISR_TAILCHAINING_THRESHOLD == 1)           \r
 442                 /* Allows for verifying the value of ISR_TAILCHAINING_THRESHOLD */\r
 443                 if (CPUCyclesSinceLastISRExit < threshold_low_watermark)\r
 444                 {\r
 445                         threshold_low_watermark = CPUCyclesSinceLastISRExit;\r
 446                 }\r
 447                 #endif\r
 448                 \r
 449                 if (CPUCyclesSinceLastISRExit <= ISR_TAILCHAINING_THRESHOLD)            \r
 450                 {                       \r
 451                         /* This is judged to be a case of ISR tail-chaining since the \r
 452                         number of cycles since the last vTraceStoreISREnd is shorter or equal to\r
 453                         the threshold (ISR_TAILCHAINING_THRESHOLD) */\r
 454                         \r
 455                         if (ptrLastISRExitEvent != NULL)\r
 456                         {                               \r
 457                                 /* Overwrite the last ISR exit event with a "neutral" event that only\r
 458                    accounts for the time passed */\r
 459                                 *ptrLastISRExitEvent = XTS16L;                                                  \r
 460                         }                       \r
 461                 }\r
 462                 \r
 463         }\r
 464 #endif\r
 465         \r
 466     if (recorder_busy)\r
 467     {\r
 468       vTraceError("Illegal call to vTraceStoreISRBegin, recorder busy!");\r
 469       return;\r
 470     }\r
 471         trcCRITICAL_SECTION_BEGIN();\r
 472     if (RecorderDataPtr->recorderActive && handle_of_last_logged_task)\r
 473     {\r
 474 \r
 475             TRACE_ASSERT(handle <= RecorderDataPtr->ObjectPropertyTable.NumberOfObjectsPerClass[TRACE_CLASS_ISR], "vTraceStoreISRBegin: Invalid value for handle", );\r
 476 \r
 477         dts4 = (uint16_t)prvTraceGetDTS(0xFFFF);\r
 478 \r
 479         if (RecorderDataPtr->recorderActive) /* Need to repeat this check! */\r
 480         {\r
 481             if (nISRactive < MAX_ISR_NESTING)\r
 482             {\r
 483                                 uint8_t hnd8 = prvTraceGet8BitHandle(handle);\r
 484                 isrstack[nISRactive] = handle;\r
 485                 nISRactive++;\r
 486                 ts = (TSEvent*)xTraceNextFreeEventBufferSlot();\r
 487                 if (ts != NULL)\r
 488                 {\r
 489                     ts->type = TS_ISR_BEGIN;\r
 490                     ts->dts = dts4;\r
 491                     ts->objHandle = hnd8;\r
 492                     prvTraceUpdateCounters();\r
 493                 }\r
 494             }\r
 495             else\r
 496             {\r
 497                 /* This should not occur unless something is very wrong */\r
 498                 vTraceError("Too many nested interrupts!");\r
 499             }\r
 500         }        \r
 501     }\r
 502         trcCRITICAL_SECTION_END();\r
 503 }\r
 504 \r
 505 /*******************************************************************************\r
 506  * vTraceStoreISREnd\r
 507  *\r
 508  * Registers the end of an Interrupt Service Routine.\r
 509  *\r
 510  * Example:\r
 511  *     #define ID_ISR_TIMER1 1       // lowest valid ID is 1\r
 512  *     #define PRIO_OF_ISR_TIMER1 3  // the hardware priority of the interrupt\r
 513  *     ...\r
 514  *     vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
 515  *     ...\r
 516  *     void ISR_handler()\r
 517  *     {\r
 518  *         vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
 519  *         ...\r
 520  *         vTraceStoreISREnd();\r
 521  *     }\r
 522  *\r
 523  ******************************************************************************/\r
 524 void vTraceStoreISREnd(void)\r
 525 {\r
 526         TSEvent* ts;\r
 527         uint16_t dts5;\r
 528         TRACE_SR_ALLOC_CRITICAL_SECTION();\r
 529 \r
 530         if (recorder_busy)\r
 531         {\r
 532                 vTraceError("Illegal call to vTraceStoreISREnd, recorder busy!");\r
 533                 return;\r
 534         }\r
 535 \r
 536         trcCRITICAL_SECTION_BEGIN();\r
 537         if (RecorderDataPtr->recorderActive && handle_of_last_logged_task)\r
 538         {               \r
 539                 dts5 = (uint16_t)prvTraceGetDTS(0xFFFF);\r
 540 \r
 541                 if (RecorderDataPtr->recorderActive) /* Need to repeat this check! */\r
 542                 {\r
 543                         uint8_t hnd8, type;\r
 544 \r
 545                         if (nISRactive > 1)\r
 546                         {\r
 547                                 /* return to another isr */\r
 548                                 type = TS_ISR_RESUME;\r
 549                                 hnd8 = prvTraceGet8BitHandle(isrstack[nISRactive]);\r
 550                         }\r
 551                         else\r
 552                         {\r
 553                                 /* return to task */\r
 554                                 type = TS_TASK_RESUME;\r
 555                                 hnd8 = prvTraceGet8BitHandle(handle_of_last_logged_task);\r
 556                         }\r
 557 \r
 558                         ts = (TSEvent*)xTraceNextFreeEventBufferSlot();\r
 559 \r
 560                         if (ts != NULL)\r
 561                         {\r
 562                                 ts->type = type;\r
 563                                 ts->objHandle = hnd8;\r
 564                                 ts->dts = dts5;\r
 565                                 nISRactive--;\r
 566                                 prvTraceUpdateCounters();\r
 567                         }\r
 568                                                 \r
 569                 }\r
 570                 \r
 571                 #if (SELECTED_PORT == PORT_ARM_CortexM)\r
 572                 /* Remember the last ISR exit event, as the event needs to be modified in case of a following ISR entry (if tail-chained ISRs) */\r
 573                 ptrLastISRExitEvent = (uint8_t*)ts;\r
 574                 DWTCycleCountAtLastISRExit = DWT_CYCLE_COUNTER;\r
 575                 #endif  \r
 576         }\r
 577         trcCRITICAL_SECTION_END();\r
 578 }\r
 579 \r
 580 #else\r
 581 \r
 582 /* ISR tracing is turned off */\r
 583 void vTraceIncreaseISRActive(void)\r
 584 {\r
 585     if (RecorderDataPtr->recorderActive && handle_of_last_logged_task)\r
 586         nISRactive++;\r
 587 }\r
 588 \r
 589 void vTraceDecreaseISRActive(void)\r
 590 {\r
 591     if (RecorderDataPtr->recorderActive && handle_of_last_logged_task)\r
 592         nISRactive--;\r
 593 }\r
 594 #endif\r
 595 \r
 596 \r
 597 /*******************************************************************************\r
 598  * User Event functions\r
 599  ******************************************************************************/\r
 600 \r
 601 #if (INCLUDE_USER_EVENTS == 1)\r
 602 \r
 603 #define MAX_ARG_SIZE (4+32)\r
 604 /*** Locally used in vTracePrintF ***/\r
 605 static uint8_t writeInt8(void * buffer, uint8_t i, uint8_t value)\r
 606 {\r
 607         TRACE_ASSERT(buffer != NULL, "writeInt8: buffer == NULL", 0);\r
 608 \r
 609     if (i >= MAX_ARG_SIZE)\r
 610     {\r
 611         return 255;\r
 612     }\r
 613 \r
 614     ((uint8_t*)buffer)[i] = value;\r
 615 \r
 616         if (i + 1 > MAX_ARG_SIZE)\r
 617         {\r
 618                 return 255;\r
 619         }\r
 620 \r
 621     return i + 1;\r
 622 }\r
 623 \r
 624 /*** Locally used in vTracePrintF ***/\r
 625 static uint8_t writeInt16(void * buffer, uint8_t i, uint16_t value)\r
 626 {\r
 627         TRACE_ASSERT(buffer != NULL, "writeInt16: buffer == NULL", 0);\r
 628 \r
 629     /* Align to multiple of 2 */\r
 630     while ((i % 2) != 0)\r
 631     {\r
 632                 if (i >= MAX_ARG_SIZE)\r
 633                 {\r
 634                         return 255;\r
 635                 }\r
 636 \r
 637         ((uint8_t*)buffer)[i] = 0;\r
 638         i++;\r
 639     }\r
 640 \r
 641     if (i + 2 > MAX_ARG_SIZE)\r
 642     {\r
 643         return 255;\r
 644     }\r
 645 \r
 646     ((uint16_t*)buffer)[i/2] = value;\r
 647 \r
 648     return i + 2;\r
 649 }\r
 650 \r
 651 /*** Locally used in vTracePrintF ***/\r
 652 static uint8_t writeInt32(void * buffer, uint8_t i, uint32_t value)\r
 653 {\r
 654         TRACE_ASSERT(buffer != NULL, "writeInt32: buffer == NULL", 0);\r
 655 \r
 656     /* A 32 bit value should begin at an even 4-byte address */\r
 657     while ((i % 4) != 0)\r
 658     {\r
 659                 if (i >= MAX_ARG_SIZE)\r
 660                 {\r
 661                         return 255;\r
 662                 }\r
 663 \r
 664         ((uint8_t*)buffer)[i] = 0;\r
 665         i++;\r
 666     }\r
 667 \r
 668     if (i + 4 > MAX_ARG_SIZE)\r
 669     {\r
 670         return 255;\r
 671     }\r
 672 \r
 673     ((uint32_t*)buffer)[i/4] = value;\r
 674 \r
 675     return i + 4;\r
 676 }\r
 677 \r
 678 #if (INCLUDE_FLOAT_SUPPORT)\r
 679 \r
 680 /*** Locally used in vTracePrintF ***/\r
 681 static uint8_t writeFloat(void * buffer, uint8_t i, float value)\r
 682 {\r
 683         TRACE_ASSERT(buffer != NULL, "writeFloat: buffer == NULL", 0);\r
 684 \r
 685     /* A 32 bit value should begin at an even 4-byte address */\r
 686     while ((i % 4) != 0)\r
 687     {\r
 688                 if (i >= MAX_ARG_SIZE)\r
 689                 {\r
 690                         return 255;\r
 691                 }\r
 692 \r
 693         ((uint8_t*)buffer)[i] = 0;\r
 694         i++;\r
 695     }\r
 696 \r
 697     if (i + 4 > MAX_ARG_SIZE)\r
 698     {\r
 699         return 255;\r
 700     }\r
 701 \r
 702     ((float*)buffer)[i/4] = value;\r
 703 \r
 704     return i + 4;\r
 705 }\r
 706 \r
 707 /*** Locally used in vTracePrintF ***/\r
 708 static uint8_t writeDouble(void * buffer, uint8_t i, double value)\r
 709 {\r
 710         TRACE_ASSERT(buffer != NULL, "writeDouble: buffer == NULL", 0);\r
 711 \r
 712     uint32_t * dest; \r
 713     uint32_t * src = (void*)&value;\r
 714     /* The double is written as two 32 bit values, and should begin at an even\r
 715     4-byte address (to avoid having to align with 8 byte) */\r
 716     while (i % 4 != 0)\r
 717     {\r
 718                 if (i >= MAX_ARG_SIZE)\r
 719                 {\r
 720                         return 255;\r
 721                 }\r
 722 \r
 723         ((uint8_t*)buffer)[i] = 0;\r
 724         i++;\r
 725     }\r
 726 \r
 727     if (i + 8 > MAX_ARG_SIZE)\r
 728     {\r
 729         return 255;\r
 730     }\r
 731         \r
 732         dest = &(((uint32_t *)buffer)[i]);\r
 733 \r
 734     dest[0] = src[0];\r
 735     dest[1] = src[1];\r
 736 \r
 737     return i + 8;\r
 738 }\r
 739 \r
 740 #endif\r
 741 \r
 742 /*******************************************************************************\r
 743  * prvTraceUserEventFormat\r
 744  *\r
 745  * Parses the format string and stores the arguments in the buffer.\r
 746  ******************************************************************************/\r
 747 static uint8_t prvTraceUserEventFormat(const char* formatStr, va_list vl, uint8_t* buffer, uint8_t byteOffset)\r
 748 {\r
 749         uint16_t formatStrIndex = 0;\r
 750         uint8_t argCounter = 0;\r
 751         uint8_t i = byteOffset;\r
 752 \r
 753         while (formatStr[formatStrIndex] != '\0')\r
 754     {\r
 755         if (formatStr[formatStrIndex] == '%')\r
 756         {\r
 757             argCounter++;\r
 758 \r
 759             if (argCounter > 15)\r
 760             {\r
 761                 vTraceError("vTracePrintF - Too many arguments, max 15 allowed!");\r
 762                 return 0;\r
 763             }\r
 764 \r
 765 /*******************************************************************************\r
 766 * These below code writes raw data (primitive datatypes) in the event buffer,\r
 767 * instead of the normal event structs (where byte 0 is event type).\r
 768 * These data entries must never be interpreted as real event data, as the type\r
 769 * field would be misleading since used for payload data.\r
 770 *\r
 771 * The correctness of this encoding depends on two mechanisms:\r
 772 *\r
 773 * 1. An initial USER_EVENT, which type code tells the number of 32-bit data\r
 774 * entires that follows. (code - USER_EVENT = number of data entries).\r
 775 * Note that a data entry corresponds to the slots that normally corresponds to\r
 776 * one (1) event, i.e., 32 bits. vTracePrintF may encode several pieces of data\r
 777 * in one data entry, e.g., two 16-bit values or four 8-bit values, one 16-bit\r
 778 * value followed by two 8-bit values, etc.\r
 779 *\r
 780 * 2. A two-phase commit procedure, where the USER_EVENT and data entries are\r
 781 * written to a local buffer at first, and when all checks are OK then copied to\r
 782 * the main event buffer using a fast memcpy. The event code is finalized as the\r
 783 * very last step. Before that step, the event code indicates an unfinished\r
 784 * event, which causes it to be ignored and stop the loading of the file (since\r
 785 * an unfinished event is the last event in the trace).\r
 786 *******************************************************************************/\r
 787             formatStrIndex++;\r
 788 \r
 789                         while ((formatStr[formatStrIndex] >= '0' && formatStr[formatStrIndex] <= '9') || formatStr[formatStrIndex] == '#' || formatStr[formatStrIndex] == '.')\r
 790                                 formatStrIndex++;\r
 791 \r
 792                         if (formatStr[formatStrIndex] != '\0')\r
 793                         {\r
 794                                 switch (formatStr[formatStrIndex])\r
 795                                 {\r
 796                                 case 'd':    i = writeInt32(buffer,\r
 797                                                                                                 i,\r
 798                                                                                                 (uint32_t)va_arg(vl, uint32_t));\r
 799                                                                 break;\r
 800                                 case 'x':\r
 801                                 case 'X':\r
 802                                 case 'u':    i = writeInt32(buffer,\r
 803                                                                                                 i,\r
 804                                                                                                 (uint32_t)va_arg(vl, uint32_t));\r
 805                                                                 break;\r
 806                                 case 's':    i = writeInt16(buffer,\r
 807                                                                                                 i,\r
 808                                                                                                 (uint16_t)xTraceOpenLabel((char*)va_arg(vl, char*)));\r
 809                                                                 break;\r
 810 \r
 811 #if (INCLUDE_FLOAT_SUPPORT)\r
 812                                                                 /* Yes, "double" as type also in the float\r
 813                                                                 case. This since "float" is promoted into "double"\r
 814                                                                 by the va_arg stuff. */\r
 815                                 case 'f':    i = writeFloat(buffer,\r
 816                                                                                                 i,\r
 817                                                                                                 (float)va_arg(vl, double));\r
 818                                                                 break;\r
 819 #else\r
 820         /* No support for floats, but attempt to store a float user event\r
 821         avoid a possible crash due to float reference. Instead store the\r
 822         data on uint_32 format (will not be displayed anyway). This is just\r
 823         to keep va_arg and i consistent. */\r
 824 \r
 825                                 case 'f':    i = writeInt32(buffer,\r
 826                                                                                                 i,\r
 827                                                                                                 (uint32_t)va_arg(vl, double));\r
 828                                                                 break;\r
 829 #endif\r
 830                                 case 'l':\r
 831                                         formatStrIndex++;\r
 832                                         switch (formatStr[formatStrIndex])\r
 833                                         {\r
 834 #if (INCLUDE_FLOAT_SUPPORT)\r
 835                                         case 'f':     i = writeDouble(buffer,\r
 836                                                                                                                 i,\r
 837                                                                                                                 (double)va_arg(vl, double));\r
 838                                                                 break;\r
 839 #else\r
 840         /* No support for floats, but attempt to store a float user event\r
 841         avoid a possible crash due to float reference. Instead store the\r
 842         data on uint_32 format (will not be displayed anyway). This is just\r
 843         to keep va_arg and i consistent. */\r
 844                                         case 'f':    i = writeInt32(buffer, /* In this case, the value will not be shown anyway */\r
 845                                                                                                         i,\r
 846                                                                                                         (uint32_t)va_arg(vl, double));\r
 847                                                                         i = writeInt32(buffer, /* Do it twice, to write in total 8 bytes */\r
 848                                                                                                         i,\r
 849                                                                                                         (uint32_t)va_arg(vl, double));\r
 850                                                                 break;\r
 851 #endif\r
 852 \r
 853                                         }\r
 854                                         break;\r
 855                                 case 'h':\r
 856                                         formatStrIndex++;\r
 857                                         switch (formatStr[formatStrIndex])\r
 858                                         {\r
 859                                         case 'd':    i = writeInt16(buffer,\r
 860                                                                                                         i,\r
 861                                                                                                         (uint16_t)va_arg(vl, uint32_t));\r
 862                                                                         break;\r
 863                                         case 'u':    i = writeInt16(buffer,\r
 864                                                                                                         i,\r
 865                                                                                                         (uint16_t)va_arg(vl, uint32_t));\r
 866                                                                         break;\r
 867                                         }\r
 868                                         break;\r
 869                                 case 'b':\r
 870                                         formatStrIndex++;\r
 871                                         switch (formatStr[formatStrIndex])\r
 872                                         {\r
 873                                         case 'd':    i = writeInt8(buffer,\r
 874                                                                                                         i,\r
 875                                                                                                         (uint8_t)va_arg(vl, uint32_t));\r
 876                                                                         break;\r
 877                                         case 'u':    i = writeInt8(buffer,\r
 878                                                                                                         i,\r
 879                                                                                                         (uint8_t)va_arg(vl, uint32_t));\r
 880                                                                         break;\r
 881                                         }\r
 882                                         break;\r
 883                                 }\r
 884                         }\r
 885                         else\r
 886                                 break;\r
 887         }\r
 888         formatStrIndex++;\r
 889         if (i == 255)\r
 890         {\r
 891             vTraceError("vTracePrintF - Too large arguments, max 32 byte allowed!");\r
 892             return 0;\r
 893         }\r
 894     }\r
 895         return (i+3)/4;\r
 896 }\r
 897 \r
 898 #if (USE_SEPARATE_USER_EVENT_BUFFER == 1)\r
 899 \r
 900 /*******************************************************************************\r
 901  * prvTraceClearChannelBuffer\r
 902  *\r
 903  * Clears a number of items in the channel buffer, starting from nextSlotToWrite.\r
 904  ******************************************************************************/\r
 905 static void prvTraceClearChannelBuffer(uint32_t count)\r
 906 {\r
 907         uint32_t slots;\r
 908 \r
 909         TRACE_ASSERT(USER_EVENT_BUFFER_SIZE >= count, "prvTraceClearChannelBuffer: USER_EVENT_BUFFER_SIZE is too small to handle this event.", );\r
 910 \r
 911         /* Check if we're close to the end of the buffer */\r
 912         if (RecorderDataPtr->userEventBuffer.nextSlotToWrite + count > USER_EVENT_BUFFER_SIZE)\r
 913         {\r
 914                 slots = USER_EVENT_BUFFER_SIZE - RecorderDataPtr->userEventBuffer.nextSlotToWrite; /* Number of slots before end of buffer */\r
 915                 (void)memset(&RecorderDataPtr->userEventBuffer.channelBuffer[RecorderDataPtr->userEventBuffer.nextSlotToWrite], 0, slots);\r
 916                 (void)memset(&RecorderDataPtr->userEventBuffer.channelBuffer[0], 0, (count - slots));\r
 917         }\r
 918         else\r
 919                 (void)memset(&RecorderDataPtr->userEventBuffer.channelBuffer[RecorderDataPtr->userEventBuffer.nextSlotToWrite], 0, count);\r
 920 }\r
 921 \r
 922 /*******************************************************************************\r
 923  * prvTraceCopyToDataBuffer\r
 924  *\r
 925  * Copies a number of items to the data buffer, starting from nextSlotToWrite.\r
 926  ******************************************************************************/\r
 927 static void prvTraceCopyToDataBuffer(uint32_t* data, uint32_t count)\r
 928 {\r
 929         TRACE_ASSERT(data != NULL, "prvTraceCopyToDataBuffer: data == NULL.", );\r
 930         TRACE_ASSERT(count <= USER_EVENT_BUFFER_SIZE, "prvTraceCopyToDataBuffer: USER_EVENT_BUFFER_SIZE is too small to handle this event.", );\r
 931 \r
 932         uint32_t slots;\r
 933         /* Check if we're close to the end of the buffer */\r
 934         if (RecorderDataPtr->userEventBuffer.nextSlotToWrite + count > USER_EVENT_BUFFER_SIZE)\r
 935         {\r
 936                 slots = USER_EVENT_BUFFER_SIZE - RecorderDataPtr->userEventBuffer.nextSlotToWrite; /* Number of slots before end of buffer */\r
 937                 (void)memcpy(&RecorderDataPtr->userEventBuffer.dataBuffer[RecorderDataPtr->userEventBuffer.nextSlotToWrite * 4], data, slots * 4);\r
 938                 (void)memcpy(&RecorderDataPtr->userEventBuffer.dataBuffer[0], data + slots, (count - slots) * 4);\r
 939         }\r
 940         else\r
 941         {\r
 942                 (void)memcpy(&RecorderDataPtr->userEventBuffer.dataBuffer[RecorderDataPtr->userEventBuffer.nextSlotToWrite * 4], data, count * 4);\r
 943         }\r
 944 }\r
 945 \r
 946 /*******************************************************************************\r
 947  * prvTraceUserEventHelper1\r
 948  *\r
 949  * Calls on prvTraceUserEventFormat() to do the actual formatting, then goes on to the next helper function.\r
 950  ******************************************************************************/\r
 951 static void prvTraceUserEventHelper1(UserEventChannel channel, traceLabel eventLabel, traceLabel formatLabel, va_list vl)\r
 952 {\r
 953         uint32_t data[(3 + MAX_ARG_SIZE) / 4];\r
 954         uint8_t byteOffset = 4; /* Need room for timestamp */\r
 955         uint8_t noOfSlots;\r
 956 \r
 957         if (channel == 0)\r
 958         {\r
 959                 /* We are dealing with an unknown channel format pair */\r
 960                 byteOffset += 4; /* Also need room for channel and format */\r
 961                 ((uint16_t*)data)[2] = eventLabel;\r
 962                 ((uint16_t*)data)[3] = formatLabel;\r
 963         }\r
 964 \r
 965         noOfSlots = prvTraceUserEventFormat((char*)&(RecorderDataPtr->SymbolTable.symbytes[formatLabel+4]), vl, (uint8_t*)data, byteOffset);\r
 966 \r
 967         prvTraceUserEventHelper2(channel, data, noOfSlots);\r
 968 }\r
 969 \r
 970 /*******************************************************************************\r
 971  * prvTraceUserEventHelper2\r
 972  *\r
 973  * This function simply copies the data buffer to the actual user event buffer.\r
 974  ******************************************************************************/\r
 975 static void prvTraceUserEventHelper2(UserEventChannel channel, uint32_t* data, uint32_t noOfSlots)\r
 976 {\r
 977         static uint32_t old_timestamp = 0;\r
 978         uint32_t old_nextSlotToWrite = 0;\r
 979 \r
 980         TRACE_ASSERT(USER_EVENT_BUFFER_SIZE >= noOfSlots, "vTracePrintF: USER_EVENT_BUFFER_SIZE is too small to handle this event.", );\r
 981 \r
 982         trcCRITICAL_SECTION_BEGIN();\r
 983         /* Store the timestamp */\r
 984         vTracePortGetTimeStamp(data);\r
 985 \r
 986         if (*data < old_timestamp)\r
 987                 RecorderDataPtr->userEventBuffer.wraparoundCounter++;\r
 988         old_timestamp = *data;\r
 989 \r
 990         /* Start by erasing any information in the channel buffer */\r
 991         prvTraceClearChannelBuffer(noOfSlots);\r
 992 \r
 993         prvTraceCopyToDataBuffer(data, noOfSlots); /* Will wrap around the data if necessary */\r
 994 \r
 995         old_nextSlotToWrite = RecorderDataPtr->userEventBuffer.nextSlotToWrite; /* Save the index that we want to write the channel data at when we're done */\r
 996         RecorderDataPtr->userEventBuffer.nextSlotToWrite = (RecorderDataPtr->userEventBuffer.nextSlotToWrite + noOfSlots) % USER_EVENT_BUFFER_SIZE; /* Make sure we never end up outside the buffer */\r
 997 \r
 998         /* Write to the channel buffer to indicate that this user event is ready to be used */\r
 999         if (channel != 0)\r
1000                 RecorderDataPtr->userEventBuffer.channelBuffer[old_nextSlotToWrite] = channel;\r
1001         else\r
1002                 RecorderDataPtr->userEventBuffer.channelBuffer[old_nextSlotToWrite] = (UserEventChannel)0xFF;   /* 0xFF indicates that this is not a normal channel id */\r
1003         trcCRITICAL_SECTION_END();\r
1004 }\r
1005 \r
1006 /*******************************************************************************\r
1007  * xTraceRegisterChannelFormat\r
1008  *\r
1009  * Attempts to create a pair of the channel and format string.\r
1010  *\r
1011  * Note: This is only available if USE_SEPARATE_USER_EVENT_BUFFER is enabled in \r
1012  * trcConfig.h\r
1013  ******************************************************************************/\r
1014 UserEventChannel xTraceRegisterChannelFormat(traceLabel channel, traceLabel formatStr)\r
1015 {\r
1016         uint8_t i;\r
1017         UserEventChannel retVal = 0;\r
1018 \r
1019         TRACE_ASSERT(formatStr != 0, "vTraceRegisterChannelFormat: formatStr == 0", (UserEventChannel)0);\r
1020 \r
1021         trcCRITICAL_SECTION_BEGIN();\r
1022         for (i = 1; i <= CHANNEL_FORMAT_PAIRS; i++) /* Size of the channels buffer is CHANNEL_FORMAT_PAIRS + 1. Index 0 is unused. */\r
1023         {\r
1024                 if(RecorderDataPtr->userEventBuffer.channels[i].name == 0 && RecorderDataPtr->userEventBuffer.channels[i].defaultFormat == 0)\r
1025                 {\r
1026                         /* Found empty slot */\r
1027                         RecorderDataPtr->userEventBuffer.channels[i].name = channel;\r
1028                         RecorderDataPtr->userEventBuffer.channels[i].defaultFormat = formatStr;\r
1029                         retVal = (UserEventChannel)i;\r
1030                         break;\r
1031                 }\r
1032 \r
1033                 if (RecorderDataPtr->userEventBuffer.channels[i].name == channel && RecorderDataPtr->userEventBuffer.channels[i].defaultFormat == formatStr)\r
1034                 {\r
1035                         /* Found a match */\r
1036                         retVal = (UserEventChannel)i;\r
1037                         break;\r
1038                 }\r
1039         }\r
1040         trcCRITICAL_SECTION_END();\r
1041         return retVal;\r
1042 }\r
1043 \r
1044 /******************************************************************************\r
1045  * vTraceChannelPrintF\r
1046  *\r
1047  * Slightly faster version of vTracePrintF() due to no lookups.\r
1048  *\r
1049  * Note: This is only available if USE_SEPARATE_USER_EVENT_BUFFER is enabled in\r
1050  * trcConfig.h\r
1051  *\r
1052  ******************************************************************************/\r
1053 void vTraceChannelPrintF(UserEventChannel channelPair, ...)\r
1054 {\r
1055         va_list vl;\r
1056 \r
1057         va_start(vl, channelPair);\r
1058         vTraceChannelPrintF_Helper(channelPair, vl);\r
1059         va_end(vl);\r
1060 }\r
1061 \r
1062 void vTraceChannelPrintF_Helper(UserEventChannel channelPair, va_list vl)\r
1063 {\r
1064         traceLabel channel;\r
1065         traceLabel formatStr;\r
1066 \r
1067         TRACE_ASSERT(channelPair != 0, "vTraceChannelPrintF: channelPair == 0", );\r
1068         TRACE_ASSERT(channelPair <= CHANNEL_FORMAT_PAIRS, "vTraceChannelPrintF: ", );\r
1069 \r
1070         channel = RecorderDataPtr->userEventBuffer.channels[channelPair].name;\r
1071         formatStr = RecorderDataPtr->userEventBuffer.channels[channelPair].defaultFormat;\r
1072 \r
1073         prvTraceUserEventHelper1(channelPair, channel, formatStr, vl);\r
1074 }\r
1075 \r
1076 /******************************************************************************\r
1077  * vTraceChannelUserEvent\r
1078  *\r
1079  * Slightly faster version of vTraceUserEvent() due to no lookups.\r
1080  ******************************************************************************/\r
1081 void vTraceChannelUserEvent(UserEventChannel channelPair)\r
1082 {\r
1083         uint32_t data[(3 + MAX_ARG_SIZE) / 4];\r
1084 \r
1085         TRACE_ASSERT(channelPair != 0, "vTraceChannelPrintF: channelPair == 0", );\r
1086         TRACE_ASSERT(channelPair <= CHANNEL_FORMAT_PAIRS, "vTraceChannelPrintF: ", );\r
1087 \r
1088         prvTraceUserEventHelper2(channelPair, data, 1); /* Only need one slot for timestamp */\r
1089 }\r
1090 #endif /* USE_SEPARATE_USER_EVENT_BUFFER == 1 */\r
1091 \r
1092  /******************************************************************************\r
1093  * vTracePrintF\r
1094  *\r
1095  * Advanced user events (Professional Edition only)\r
1096  *\r
1097  * Generates User Event with formatted text and data, similar to a "printf".\r
1098  * It is very fast compared to a normal "printf" since this function only\r
1099  * stores the arguments. The actual formatting is done\r
1100  * on the host PC when the trace is displayed in the viewer tool.\r
1101  *\r
1102  * User Event labels are created using xTraceOpenLabel.\r
1103  * Example:\r
1104  *\r
1105  *     traceLabel adc_uechannel = xTraceOpenLabel("ADC User Events");\r
1106  *     ...\r
1107  *     vTracePrint(adc_uechannel,\r
1108  *                 "ADC channel %d: %lf volts",\r
1109  *                 ch, (double)adc_reading/(double)scale);\r
1110  *\r
1111  * This can be combined into one line, if desired, but this is slower:\r
1112  *\r
1113  *     vTracePrint(xTraceOpenLabel("ADC User Events"),\r
1114  *                 "ADC channel %d: %lf volts",\r
1115  *                 ch, (double)adc_reading/(double)scale);\r
1116  *\r
1117  * Calling xTraceOpenLabel multiple times will not create duplicate entries, but\r
1118  * it is of course faster to just do it once, and then keep the handle for later\r
1119  * use. If you don´t have any data arguments, only a text label/string, it is\r
1120  * better to use vTraceUserEvent - it is faster.\r
1121  *\r
1122  * Format specifiers supported:\r
1123  *  %d - 32 bit signed integer\r
1124  *  %u - 32 bit unsigned integer\r
1125  *  %f - 32 bit float\r
1126  *  %s - string (is copied to the recorder symbol table)\r
1127  *  %hd - 16 bit signed integer\r
1128  *  %hu - 16 bit unsigned integer\r
1129  *  %bd - 8 bit signed integer\r
1130  *  %bu - 8 bit unsigned integer\r
1131  *  %lf - double-precision float\r
1132  *\r
1133  * Up to 15 data arguments are allowed, with a total size of maximum 32 byte.\r
1134  * In case this is exceeded, the user event is changed into an error message.\r
1135  *\r
1136  * The data is stored in trace buffer, and is packed to allow storing multiple\r
1137  * smaller data entries in the same 4-byte record, e.g., four 8-bit values.\r
1138  * A string requires two bytes, as the symbol table is limited to 64K. Storing a\r
1139  * double (%lf) uses two records, so this is quite costly. Use float (%f) unless\r
1140  * the higher precision is really necessary.\r
1141  ******************************************************************************/\r
1142 \r
1143 void vTracePrintF(traceLabel eventLabel, const char* formatStr, ...)\r
1144 {\r
1145         va_list vl;\r
1146 \r
1147         va_start(vl, formatStr);\r
1148         vTracePrintF_Helper(eventLabel, formatStr, vl);\r
1149         va_end(vl);\r
1150 }\r
1151 \r
1152 void vTracePrintF_Helper(traceLabel eventLabel, const char* formatStr, va_list vl)\r
1153 {\r
1154 #if (USE_SEPARATE_USER_EVENT_BUFFER == 0)\r
1155         uint32_t noOfSlots;\r
1156     UserEvent* ue1;\r
1157     uint32_t tempDataBuffer[(3 + MAX_ARG_SIZE) / 4];\r
1158     TRACE_SR_ALLOC_CRITICAL_SECTION();\r
1159 \r
1160     /**************************************************************************\r
1161     * The array tempDataBuffer is a local buffer used in a two-phase commit of\r
1162     * the event data, since a vTracePrintF may span over multiple slots in the\r
1163     * buffer.\r
1164     * This buffer can be made larger, of course, but remember the risk for\r
1165     * stack overflow. Note: This should be a LOCAL buffer, must not be made\r
1166     * global. That would cause data corruption when two calls to vTracePrintF\r
1167     * from different tasks overlaps (interrupts are only disabled in a small\r
1168     * part of this function, otherwise enabled)\r
1169     ***************************************************************************/\r
1170 \r
1171         TRACE_ASSERT(formatStr != NULL, "vTracePrintF: formatStr == NULL", );\r
1172 \r
1173         trcCRITICAL_SECTION_BEGIN();\r
1174         \r
1175     if (RecorderDataPtr->recorderActive && (! inExcludedTask || nISRactive) && handle_of_last_logged_task)\r
1176     {\r
1177         /* First, write the "primary" user event entry in the local buffer, but\r
1178         let the event type be "EVENT_BEING_WRITTEN" for now...*/\r
1179 \r
1180         ue1 = (UserEvent*)(&tempDataBuffer[0]);\r
1181                 \r
1182         ue1->type = EVENT_BEING_WRITTEN;      /* Update this as the last step */\r
1183 \r
1184         noOfSlots = prvTraceUserEventFormat(formatStr, vl, (uint8_t*)tempDataBuffer, 4);\r
1185 \r
1186         /* Store the format string, with a reference to the channel symbol */\r
1187         ue1->payload = prvTraceOpenSymbol(formatStr, eventLabel);                       \r
1188 \r
1189         ue1->dts = (uint8_t)prvTraceGetDTS(0xFF);\r
1190                 \r
1191                  /* prvTraceGetDTS might stop the recorder in some cases... */\r
1192         if (RecorderDataPtr->recorderActive)\r
1193         {\r
1194 \r
1195                         /* If the data does not fit in the remaining main buffer, wrap around to\r
1196                         0 if allowed, otherwise stop the recorder and quit). */\r
1197                         if (RecorderDataPtr->nextFreeIndex + noOfSlots > RecorderDataPtr->maxEvents)\r
1198                         {\r
1199                                 #if (TRACE_RECORDER_STORE_MODE == TRACE_STORE_MODE_RING_BUFFER)\r
1200                                 (void)memset(& RecorderDataPtr->eventData[RecorderDataPtr->nextFreeIndex * 4],\r
1201                                            0,\r
1202                                            (RecorderDataPtr->maxEvents - RecorderDataPtr->nextFreeIndex)*4);\r
1203                                 RecorderDataPtr->nextFreeIndex = 0;\r
1204                                 RecorderDataPtr->bufferIsFull = 1;\r
1205                                 #else\r
1206                                 \r
1207                                 /* Stop recorder, since the event data will not fit in the\r
1208                                 buffer and not circular buffer in this case... */                               \r
1209                                 vTraceStop();                           \r
1210                                 #endif\r
1211                         }\r
1212                         \r
1213                         /* Check if recorder has been stopped (i.e., vTraceStop above) */\r
1214                         if (RecorderDataPtr->recorderActive)\r
1215                         {                               \r
1216                                 /* Check that the buffer to be overwritten does not contain any user\r
1217                                 events that would be partially overwritten. If so, they must be "killed"\r
1218                                 by replacing the user event and following data with NULL events (i.e.,\r
1219                                 using a memset to zero).*/\r
1220                                 #if (TRACE_RECORDER_STORE_MODE == TRACE_STORE_MODE_RING_BUFFER)\r
1221                                 prvCheckDataToBeOverwrittenForMultiEntryEvents((uint8_t)noOfSlots);\r
1222                                 #endif\r
1223                                 /* Copy the local buffer to the main buffer */\r
1224                                 (void)memcpy(& RecorderDataPtr->eventData[RecorderDataPtr->nextFreeIndex * 4],\r
1225                                            tempDataBuffer,\r
1226                                            noOfSlots * 4);\r
1227 \r
1228                                 /* Update the event type, i.e., number of data entries following the\r
1229                                 main USER_EVENT entry (Note: important that this is after the memcpy,\r
1230                                 but within the critical section!)*/\r
1231                                 RecorderDataPtr->eventData[RecorderDataPtr->nextFreeIndex * 4] =\r
1232                                   (uint8_t) ( USER_EVENT + noOfSlots - 1 );\r
1233 \r
1234                                 /* Update the main buffer event index (already checked that it fits in\r
1235                                 the buffer, so no need to check for wrapping)*/\r
1236 \r
1237                                 RecorderDataPtr->nextFreeIndex += noOfSlots;\r
1238                                 RecorderDataPtr->numEvents += noOfSlots;\r
1239 \r
1240                                 if (RecorderDataPtr->nextFreeIndex >= EVENT_BUFFER_SIZE)\r
1241                                 {\r
1242                                         #if (TRACE_RECORDER_STORE_MODE == TRACE_STORE_MODE_RING_BUFFER)\r
1243                                         /* We have reached the end, but this is a ring buffer. Start from the beginning again. */\r
1244                                         RecorderDataPtr->bufferIsFull = 1;\r
1245                                         RecorderDataPtr->nextFreeIndex = 0;\r
1246                                         #else\r
1247                                         /* We have reached the end so we stop. */\r
1248                                         vTraceStop();\r
1249                                         #endif\r
1250                                 }\r
1251                                 \r
1252                                 #if (STOP_AFTER_N_EVENTS > -1)\r
1253                                 /* Check if we have reached the desired number of events */\r
1254                                 if (RecorderDataPtr->numEvents >= STOP_AFTER_N_EVENTS)\r
1255                                 {\r
1256                                         vTraceStop();\r
1257                                 }\r
1258                                 #endif        \r
1259                         }\r
1260                         \r
1261                         #if (TRACE_RECORDER_STORE_MODE == TRACE_STORE_MODE_RING_BUFFER)\r
1262                         /* Make sure the next entry is cleared correctly */\r
1263                         prvCheckDataToBeOverwrittenForMultiEntryEvents(1);\r
1264                         #endif\r
1265         \r
1266                 }\r
1267         }\r
1268         trcCRITICAL_SECTION_END();\r
1269 \r
1270 #elif (USE_SEPARATE_USER_EVENT_BUFFER == 1)\r
1271         /* Use the separate user event buffer */\r
1272         traceLabel formatLabel;\r
1273         UserEventChannel channel;\r
1274 \r
1275         if (RecorderDataPtr->recorderActive && (! inExcludedTask || nISRactive) && handle_of_last_logged_task)\r
1276     {\r
1277             formatLabel = xTraceOpenLabel(formatStr);\r
1278 \r
1279             channel = xTraceRegisterChannelFormat(eventLabel, formatLabel);\r
1280 \r
1281                 prvTraceUserEventHelper1(channel, eventLabel, formatLabel, vl);\r
1282         }\r
1283 #endif\r
1284 }\r
1285 \r
1286 /******************************************************************************\r
1287  * vTraceUserEvent\r
1288  *\r
1289  * Basic user event (Standard and Professional Edition only)\r
1290  *\r
1291  * Generates a User Event with a text label. The label is created/looked up\r
1292  * in the symbol table using xTraceOpenLabel.\r
1293  ******************************************************************************/\r
1294 void vTraceUserEvent(traceLabel eventLabel)\r
1295 {\r
1296 #if (USE_SEPARATE_USER_EVENT_BUFFER == 0)\r
1297     UserEvent* ue;\r
1298     uint8_t dts1;\r
1299     TRACE_SR_ALLOC_CRITICAL_SECTION();\r
1300 \r
1301         TRACE_ASSERT(eventLabel > 0, "vTraceUserEvent: Invalid value for eventLabel", );\r
1302 \r
1303         trcCRITICAL_SECTION_BEGIN();    \r
1304     if (RecorderDataPtr->recorderActive && (! inExcludedTask || nISRactive) && handle_of_last_logged_task)\r
1305     {    \r
1306         dts1 = (uint8_t)prvTraceGetDTS(0xFF);\r
1307 \r
1308         if (RecorderDataPtr->recorderActive) /* Need to repeat this check! */\r
1309         {\r
1310             ue = (UserEvent*) xTraceNextFreeEventBufferSlot();\r
1311             if (ue != NULL)\r
1312             {\r
1313                 ue->dts = dts1;\r
1314                 ue->type = USER_EVENT;\r
1315                 ue->payload = eventLabel;\r
1316                 prvTraceUpdateCounters();\r
1317             }\r
1318         }        \r
1319     }\r
1320         trcCRITICAL_SECTION_END();\r
1321         \r
1322 #elif (USE_SEPARATE_USER_EVENT_BUFFER == 1)\r
1323         UserEventChannel channel;\r
1324         uint32_t noOfSlots = 1;\r
1325         uint32_t tempDataBuffer[(3 + MAX_ARG_SIZE) / 4];        \r
1326         if (RecorderDataPtr->recorderActive && (! inExcludedTask || nISRactive) && handle_of_last_logged_task)\r
1327         {\r
1328                 channel = xTraceRegisterChannelFormat(0, eventLabel);\r
1329 \r
1330                 if (channel == 0)\r
1331                 {\r
1332                         /* We are dealing with an unknown channel format pair */\r
1333                         noOfSlots++; /* Also need room for channel and format */\r
1334                         ((uint16_t*)tempDataBuffer)[2] = 0;\r
1335                         ((uint16_t*)tempDataBuffer)[3] = eventLabel;\r
1336                 }\r
1337 \r
1338                 prvTraceUserEventHelper2(channel, tempDataBuffer, noOfSlots);\r
1339         }       \r
1340 #endif\r
1341 }\r
1342 \r
1343 /*******************************************************************************\r
1344  * xTraceOpenLabel\r
1345  *\r
1346  * Creates user event labels for user event channels or for individual events.\r
1347  * User events can be used to log application events and data for display in\r
1348  * the visualization tool. A user event is identified by a label, i.e., a string,\r
1349  * which is stored in the recorder's symbol table.\r
1350  * When logging a user event, a numeric handle (reference) to this string is\r
1351  * used to identify the event. This is obtained by calling\r
1352  *\r
1353  *     xTraceOpenLabel()\r
1354  *\r
1355  * which adds the string to the symbol table (if not already present)\r
1356  * and returns the corresponding handle.\r
1357  *\r
1358  * This can be used in two ways:\r
1359  *\r
1360  * 1. The handle is looked up every time, when storing the user event.\r
1361  *\r
1362  * Example:\r
1363  *     vTraceUserEvent(xTraceOpenLabel("MyUserEvent"));\r
1364  *\r
1365  * 2. The label is registered just once, with the handle stored in an\r
1366  *  application variable - much like using a file handle.\r
1367  *\r
1368  * Example:\r
1369  *     myEventHandle = xTraceOpenLabel("MyUserEvent");\r
1370  *     ...\r
1371  *     vTraceUserEvent(myEventHandle);\r
1372  *\r
1373  * The second option is faster since no lookup is required on each event, and\r
1374  * therefore recommended for user events that are frequently\r
1375  * executed and/or located in time-critical code. The lookup operation is\r
1376  * however fairly fast due to the design of the symbol table.\r
1377  ******************************************************************************/\r
1378 traceLabel xTraceOpenLabel(const char* label)\r
1379 {\r
1380         TRACE_ASSERT(label != NULL, "xTraceOpenLabel: label == NULL", (traceLabel)0);\r
1381 \r
1382     return prvTraceOpenSymbol(label, 0);\r
1383 }\r
1384 \r
1385 #endif\r
1386 \r
1387 #endif