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

   1 /*******************************************************************************\r
   2  * Tracealyzer v2.4.1 Recorder Library\r
   3  * Percepio AB, www.percepio.com\r
   4  *\r
   5  * trcUser.h\r
   6  * The public API of the trace recorder library.\r
   7  *\r
   8  * Terms of Use\r
   9  * This software is copyright Percepio AB. The recorder library is free for\r
  10  * use together with Percepio products. You may distribute the recorder library\r
  11  * in its original form, including modifications in trcHardwarePort.c/.h\r
  12  * given that these modification are clearly marked as your own modifications\r
  13  * and documented in the initial comment section of these source files.\r
  14  * This software is the intellectual property of Percepio AB and may not be\r
  15  * sold or in other ways commercially redistributed without explicit written\r
  16  * permission by Percepio AB.\r
  17  *\r
  18  * Disclaimer\r
  19  * The trace tool and recorder library is being delivered to you AS IS and\r
  20  * Percepio AB makes no warranty as to its use or performance. Percepio AB does\r
  21  * not and cannot warrant the performance or results you may obtain by using the\r
  22  * software or documentation. Percepio AB make no warranties, express or\r
  23  * implied, as to noninfringement of third party rights, merchantability, or\r
  24  * fitness for any particular purpose. In no event will Percepio AB, its\r
  25  * technology partners, or distributors be liable to you for any consequential,\r
  26  * incidental or special damages, including any lost profits or lost savings,\r
  27  * even if a representative of Percepio AB has been advised of the possibility\r
  28  * of such damages, or for any claim by any third party. Some jurisdictions do\r
  29  * not allow the exclusion or limitation of incidental, consequential or special\r
  30  * damages, or the exclusion of implied warranties or limitations on how long an\r
  31  * implied warranty may last, so the above limitations may not apply to you.\r
  32  *\r
  33  * Copyright Percepio AB, 2013.\r
  34  * www.percepio.com\r
  35  ******************************************************************************/\r
  36 \r
  37 #ifndef TRCUSER_H\r
  38 #define TRCUSER_H\r
  39 \r
  40 #ifdef __cplusplus\r
  41 extern "C" {\r
  42 #endif\r
  43 \r
  44 #include "trcKernelPort.h"\r
  45 \r
  46 #if (USE_TRACEALYZER_RECORDER == 1)\r
  47 \r
  48 #ifndef USE_SEPARATE_USER_EVENT_BUFFER\r
  49 #define USE_SEPARATE_USER_EVENT_BUFFER 0\r
  50 #endif\r
  51 \r
  52 /*******************************************************************************\r
  53  * TRACE_STOP_HOOK - Hook Pointer Data Type\r
  54  *\r
  55  * Declares a data type for a call back function that will be invoked whenever\r
  56  * the recorder is stopped.\r
  57  ******************************************************************************/\r
  58 typedef void (*TRACE_STOP_HOOK)(void);\r
  59 \r
  60 /*******************************************************************************\r
  61  * vTraceStopHookPtr\r
  62  *\r
  63  * Points to a call back function that is called from vTraceStop().\r
  64  ******************************************************************************/\r
  65 extern TRACE_STOP_HOOK vTraceStopHookPtr;\r
  66 \r
  67 /*******************************************************************************\r
  68  * vTraceInitTraceData\r
  69  *\r
  70  * Allocates, if necessary, and initializes the recorder data structure, based\r
  71  * on the constants in trcConfig.h.\r
  72  ******************************************************************************/\r
  73 void vTraceInitTraceData(void);\r
  74 \r
  75 /*******************************************************************************\r
  76  * vTraceSetRecorderData\r
  77  *\r
  78  * If custom allocation is used, this function must be called so the recorder\r
  79  * library knows where to save the trace data.\r
  80  ******************************************************************************/\r
  81 #if (TRACE_DATA_ALLOCATION == TRACE_DATA_ALLOCATION_CUSTOM)\r
  82 void vTraceSetRecorderData(void* pRecorderData);\r
  83 #endif\r
  84 \r
  85 /*******************************************************************************\r
  86  * uiTraceStart\r
  87  *\r
  88  * Starts the recorder. The recorder will not be started if an error has been\r
  89  * indicated using vTraceError, e.g. if any of the Nx constants in trcConfig.h\r
  90  * has a too small value (NTASK, NQUEUE, etc).\r
  91  *\r
  92  * Returns 1 if the recorder was started successfully.\r
  93  * Returns 0 if the recorder start was prevented due to a previous internal\r
  94  * error. In that case, check vTraceGetLastError to get the error message.\r
  95  * Any error message is also presented when opening a trace file.\r
  96  *\r
  97  ******************************************************************************/\r
  98 uint32_t uiTraceStart(void);\r
  99 \r
 100 /*******************************************************************************\r
 101  * vTraceStart\r
 102  *\r
 103  * Starts the recorder. The recorder will not be started if an error has been\r
 104  * indicated using vTraceError, e.g. if any of the Nx constants in trcConfig.h\r
 105  * has a too small value (NTASK, NQUEUE, etc).\r
 106  *\r
 107  * This function is obsolete, but has been saved for backwards compatibility.\r
 108  * We recommend using uiTraceStart instead.\r
 109  ******************************************************************************/\r
 110 void vTraceStart(void);\r
 111 \r
 112 /*******************************************************************************\r
 113  * vTraceStartStatusMonitor\r
 114  *\r
 115  * This starts a task to monitor the status of the recorder module.\r
 116  * This task periodically prints a line to the console window, which shows the\r
 117  * recorder status, the number of events recorded and the latest timestamp.\r
 118  * This task calls vTracePortEnd (trcHardwarePort.c) when it detects that the\r
 119  * recorder has been stopped. This allows for adding custom actions, e.g., to\r
 120  * store the trace to a file in case a file system is available on the device.\r
 121  ******************************************************************************/\r
 122 void vTraceStartStatusMonitor(void);\r
 123 \r
 124 /*******************************************************************************\r
 125  * vTraceStop\r
 126  *\r
 127  * Stops the recorder. The recording can be resumed by calling vTraceStart.\r
 128  * This does not reset the recorder. Use vTraceClear is that is desired.\r
 129  ******************************************************************************/\r
 130 void vTraceStop(void);\r
 131 \r
 132 /*******************************************************************************\r
 133  * vTraceClear\r
 134  *\r
 135  * Resets the recorder. Only necessary if a restart is desired - this is not\r
 136  * needed in the startup initialization.\r
 137  ******************************************************************************/\r
 138 void vTraceClear(void);\r
 139 \r
 140 #if (INCLUDE_ISR_TRACING == 1)\r
 141 \r
 142 /*******************************************************************************\r
 143  * vTraceSetISRProperties\r
 144  *\r
 145  * Registers an Interrupt Service Routine in the recorder library, This must be\r
 146  * called before using vTraceStoreISRBegin to store ISR events. This is\r
 147  * typically called in the startup of the system, before the scheduler is\r
 148  * started.\r
 149  *\r
 150  * Example:\r
 151  *     #define ID_ISR_TIMER1 1       // lowest valid ID is 1\r
 152  *     #define PRIO_OF_ISR_TIMER1 3  // the hardware priority of the interrupt\r
 153  *     ...\r
 154  *     vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
 155  *     ...\r
 156  *     void ISR_handler()\r
 157  *     {\r
 158  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 159  *         vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
 160  *         portEXIT_CRITICAL();\r
 161  *         ...\r
 162  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 163  *         vTraceStoreISREnd();\r
 164  *         portEXIT_CRITICAL();\r
 165  *     }\r
 166  ******************************************************************************/\r
 167 void vTraceSetISRProperties(objectHandleType handle, const char* name, char priority);\r
 168 \r
 169 /*******************************************************************************\r
 170  * vTraceStoreISRBegin\r
 171  *\r
 172  * Registers the beginning of an Interrupt Service Routine.\r
 173  * If allowing nested ISRs, this must be called with interrupts disabled.\r
 174  *\r
 175  * Example:\r
 176  *     #define ID_ISR_TIMER1 1       // lowest valid ID is 1\r
 177  *     #define PRIO_OF_ISR_TIMER1 3  // the hardware priority of the interrupt\r
 178  *     ...\r
 179  *     vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
 180  *     ...\r
 181  *     void ISR_handler()\r
 182  *     {\r
 183  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 184  *         vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
 185  *         portEXIT_CRITICAL();\r
 186  *         ...\r
 187  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 188  *         vTraceStoreISREnd();\r
 189  *         portEXIT_CRITICAL();\r
 190  *     }\r
 191  *\r
 192  ******************************************************************************/\r
 193 void vTraceStoreISRBegin(objectHandleType id);\r
 194 \r
 195 /*******************************************************************************\r
 196  * vTraceStoreISREnd\r
 197  *\r
 198  * Registers the end of an Interrupt Service Routine.\r
 199  *\r
 200  * If allowing nested ISRs, this must be called with interrupts disabled.\r
 201  *\r
 202  * Example:\r
 203  *     #define ID_ISR_TIMER1 1       // lowest valid ID is 1\r
 204  *     #define PRIO_OF_ISR_TIMER1 3  // the hardware priority of the interrupt\r
 205  *     ...\r
 206  *     vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
 207  *     ...\r
 208  *     void ISR_handler()\r
 209  *     {\r
 210  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 211  *         vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
 212  *         portEXIT_CRITICAL();\r
 213  *         ...\r
 214  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 215  *         vTraceStoreISREnd();\r
 216  *         portEXIT_CRITICAL();\r
 217  *     }\r
 218  *\r
 219  ******************************************************************************/\r
 220 void vTraceStoreISREnd(void);\r
 221 \r
 222 #else\r
 223    /* If not including the ISR recording */\r
 224 \r
 225 void vTraceIncreaseISRActive(void);\r
 226 \r
 227 void vTraceDecreaseISRActive(void);\r
 228 \r
 229 #define vTraceSetISRProperties(handle, name, priority)\r
 230 #define vTraceStoreISRBegin(id) vTraceIncreaseISRActive()\r
 231 #define vTraceStoreISREnd() vTraceDecreaseISRActive()\r
 232 \r
 233 #endif\r
 234 \r
 235 /*******************************************************************************\r
 236  * vvTraceTaskSkipDefaultInstanceFinishedEvents\r
 237  *\r
 238  * This is useful if there are implicit Instance Finish Events, such as\r
 239  * vTaskDelayUntil or xQueueReceive, in a task where an explicit Instance Finish\r
 240  * Event has been defined. This function tells the recorder that only the\r
 241  * explicitly defined functions (using vTraceTaskInstanceIsFinished) should be\r
 242  * treated as Instance Finish Events for this task. The implicit Instance Finish\r
 243  * Events are thus disregarded for this task.\r
 244  ******************************************************************************/\r
 245 void vTraceTaskSkipDefaultInstanceFinishedEvents(void);\r
 246 \r
 247 /*******************************************************************************\r
 248  * vTraceTaskInstanceIsFinished\r
 249  *\r
 250  * This defines an explicit Instance Finish Event for the current task. It tells\r
 251  * the recorder that the current instance of this task is finished at the next\r
 252  * kernel call of the task, e.g., a taskDelay or a queue receive. This function\r
 253  * should be called right before the api function call considered to be the end\r
 254  * of the task instamce, i.e., the Instance Finish Event.\r
 255  ******************************************************************************/\r
 256 void vTraceTaskInstanceIsFinished(void);\r
 257 \r
 258 /*******************************************************************************\r
 259  * vTraceGetTraceBuffer\r
 260  *\r
 261  * Returns a pointer to the recorder data structure. Use this together with\r
 262  * uiTraceGetTraceBufferSize if you wish to implement an own store/upload\r
 263  * solution, e.g., in case a debugger connection is not available for uploading\r
 264  * the data.\r
 265  ******************************************************************************/\r
 266 void* vTraceGetTraceBuffer(void);\r
 267 \r
 268 /*******************************************************************************\r
 269  * uiTraceGetTraceBufferSize\r
 270  *\r
 271  * Gets the size of the recorder data structure. For use together with\r
 272  * vTraceGetTraceBuffer if you wish to implement an own store/upload solution,\r
 273  * e.g., in case a debugger connection is not available for uploading the data.\r
 274  ******************************************************************************/\r
 275 uint32_t uiTraceGetTraceBufferSize(void);\r
 276 \r
 277 #if (INCLUDE_USER_EVENTS == 1)\r
 278 \r
 279 /*******************************************************************************\r
 280  * xTraceOpenLabel\r
 281  *\r
 282  * Creates user event labels for user event channels or for individual events.\r
 283  * User events can be used to log application events and data for display in\r
 284  * the visualization tool. A user event is identified by a label, i.e., a string,\r
 285  * which is stored in the recorder's symbol table.\r
 286  * When logging a user event, a numeric handle (reference) to this string is\r
 287  * used to identify the event. This is obtained by calling\r
 288  *\r
 289  *     xTraceOpenLabel()\r
 290  *\r
 291  * whihc adds the string to the symbol table (if not already present)\r
 292  * and returns the corresponding handle.\r
 293  *\r
 294  * This can be used in two ways:\r
 295  *\r
 296  * 1. The handle is looked up every time, when storing the user event.\r
 297  *\r
 298  * Example:\r
 299  *     vTraceUserEvent(xTraceOpenLabel("MyUserEvent"));\r
 300  *\r
 301  * 2. The label is registered just once, with the handle stored in an\r
 302  *  application variable - much like using a file handle.\r
 303  *\r
 304  * Example:\r
 305  *     myEventHandle = xTraceOpenLabel("MyUserEvent");\r
 306  *     ...\r
 307  *     vTraceUserEvent(myEventHandle);\r
 308  *\r
 309  * The second option is faster since no lookup is required on each event, and\r
 310  * therefore recommended for user events that are frequently\r
 311  * executed and/or located in time-critical code. The lookup operation is\r
 312  * however fairly fast due to the design of the symbol table.\r
 313  ******************************************************************************/\r
 314 traceLabel xTraceOpenLabel(const char* label);\r
 315 \r
 316  /******************************************************************************\r
 317  * vTraceUserEvent\r
 318  *\r
 319  * Basic user event (Standard and Professional Edition only)\r
 320  *\r
 321  * Generates a User Event with a text label. The label is created/looked up\r
 322  * in the symbol table using xTraceOpenLabel.\r
 323  ******************************************************************************/\r
 324 void vTraceUserEvent(traceLabel eventLabel);\r
 325 \r
 326  /******************************************************************************\r
 327  * vTracePrintF\r
 328  *\r
 329  * Advanced user events (Professional Edition only)\r
 330  *\r
 331  * Generates User Event with formatted text and data, similar to a "printf".\r
 332  * It is very fast compared to a normal "printf" since this function only\r
 333  * stores the arguments. The actual formatting is done\r
 334  * on the host PC when the trace is displayed in the viewer tool.\r
 335  *\r
 336  * User Event labels are created using xTraceOpenLabel.\r
 337  * Example:\r
 338  *\r
 339  *     traceLabel adc_uechannel = xTraceOpenLabel("ADC User Events");\r
 340  *     ...\r
 341  *     vTracePrint(adc_uechannel,\r
 342  *                 "ADC channel %d: %lf volts",\r
 343  *                 ch, (double)adc_reading/(double)scale);\r
 344  *\r
 345  * This can be combined into one line, if desired, but this is slower:\r
 346  *\r
 347  *     vTracePrint(xTraceOpenLabel("ADC User Events"),\r
 348  *                 "ADC channel %d: %lf volts",\r
 349  *                 ch, (double)adc_reading/(double)scale);\r
 350  *\r
 351  * Calling xTraceOpenLabel multiple times will not create duplicate entries, but\r
 352  * it is of course faster to just do it once, and then keep the handle for later\r
 353  * use. If you don´t have any data arguments, only a text label/string, it is\r
 354  * better to use vTraceUserEvent - it is faster.\r
 355  *\r
 356  * Format specifiers supported:\r
 357  *  %d - 32 bit signed integer\r
 358  *  %u - 32 bit unsigned integer\r
 359  *  %f - 32 bit float\r
 360  *  %s - string (is copied to the recorder symbol table)\r
 361  *  %hd - 16 bit signed integer\r
 362  *  %hu - 16 bit unsigned integer\r
 363  *  %bd - 8 bit signed integer\r
 364  *  %bu - 8 bit unsigned integer\r
 365  *  %lf - double-precision float (Note! See below...)\r
 366  *\r
 367  * Up to 15 data arguments are allowed, with a total size of maximum 32 byte.\r
 368  * In case this is exceeded, the user event is changed into an error message.\r
 369  *\r
 370  * The data is stored in trace buffer, and is packed to allow storing multiple\r
 371  * smaller data entries in the same 4-byte record, e.g., four 8-bit values.\r
 372  * A string requires two bytes, as the symbol table is limited to 64K. Storing\r
 373  * a double (%lf) uses two records, so this is quite costly. Use float (%f)\r
 374  * unless the higher precision is really necessary.\r
 375  *\r
 376  * Note that the double-precision float (%lf) assumes a 64 bit double\r
 377  * representation. This does not seem to be the case on e.g. PIC24F.\r
 378  * Before using a %lf argument on a 16-bit MCU, please verify that\r
 379  * "sizeof(double)" actually gives 8 as expected. If not, use %f instead.\r
 380  ******************************************************************************/\r
 381 void vTracePrintF(traceLabel eventLabel, const char* formatStr, ...);\r
 382 \r
 383 #if (USE_SEPARATE_USER_EVENT_BUFFER == 1)\r
 384 UserEventChannel xTraceRegisterChannelFormat(traceLabel channel, traceLabel formatStr);\r
 385 void vTraceChannelPrintF(UserEventChannel channel, ...);\r
 386 void vTraceChannelUserEvent(UserEventChannel channel);\r
 387 #endif\r
 388 \r
 389 #else\r
 390 \r
 391 #define vTracePrintF(eventLabel, formatStr, ...);\r
 392 #define xTraceOpenLabel(label) 0\r
 393 #define vTraceUserEvent(eventLabel)\r
 394 \r
 395 #endif\r
 396 \r
 397 #else\r
 398 \r
 399 /* Empty defines for user functions to avoid compiler errors if trace is not to be used */\r
 400 \r
 401 #define vTraceInitTraceData()\r
 402 #define uiTraceStart() (1) // Fake "success", if used when recorder is excluded from build\r
 403 #define vTraceStart()\r
 404 #define vTraceStop()\r
 405 #define vTraceClear()\r
 406 #define vTraceStartStatusMonitor()\r
 407 #define vTraceGetTraceBuffer() ((void*)0)\r
 408 #define uiTraceGetTraceBufferSize() 0\r
 409 #define xTraceOpenLabel(label) 0\r
 410 #define vTraceUserEvent(eventLabel)\r
 411 #define vTracePrintF(eventLabel,formatStr,...)\r
 412 #define vTraceExcludeTaskFromSchedulingTrace(name)\r
 413 \r
 414 #define vTraceTaskSkipDefaultInstanceFinishedEvents()\r
 415 #define vTraceSetISRProperties(handle, name, priority)\r
 416 #define vTraceStoreISRBegin(id)\r
 417 #define vTraceStoreISREnd()\r
 418 #endif\r
 419 \r
 420 #ifdef __cplusplus\r
 421 }\r
 422 #endif\r
 423 \r
 424 #endif\r