begriffs open source - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace/Include/trcUser.h

   1 /*******************************************************************************\r
   2  * Tracealyzer v2.5.0 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  * vTraceStop\r
 114  *\r
 115  * Stops the recorder. The recording can be resumed by calling vTraceStart.\r
 116  * This does not reset the recorder. Use vTraceClear is that is desired.\r
 117  ******************************************************************************/\r
 118 void vTraceStop(void);\r
 119 \r
 120 /*******************************************************************************\r
 121  * xTraceGetLastError\r
 122  *\r
 123  * Gives the last error message, if any. NULL if no error message is stored.\r
 124  * Any error message is also presented when opening a trace file.\r
 125  ******************************************************************************/\r
 126 char* xTraceGetLastError(void);\r
 127 \r
 128 /*******************************************************************************\r
 129  * vTraceClear\r
 130  *\r
 131  * Resets the recorder. Only necessary if a restart is desired - this is not\r
 132  * needed in the startup initialization.\r
 133  ******************************************************************************/\r
 134 void vTraceClear(void);\r
 135 \r
 136 /*******************************************************************************\r
 137 * vTraceClearError\r
 138 *\r
 139 * Removes any previous error message generated by recorder calling vTraceError.\r
 140 * By calling this function, it may be possible to start/restart the trace\r
 141 * despite errors in the recorder, but there is no guarantee that the trace\r
 142 * recorder will work correctly in that case, depending on the type of error.\r
 143 ******************************************************************************/\r
 144 void vTraceClearError(int resetErrorMessage);\r
 145 \r
 146 #if (INCLUDE_ISR_TRACING == 1)\r
 147 \r
 148 /*******************************************************************************\r
 149  * vTraceSetISRProperties\r
 150  *\r
 151  * Registers an Interrupt Service Routine in the recorder library, This must be\r
 152  * called before using vTraceStoreISRBegin to store ISR events. This is\r
 153  * typically called in the startup of the system, before the scheduler is\r
 154  * started.\r
 155  *\r
 156  * Example:\r
 157  *     #define ID_ISR_TIMER1 1       // lowest valid ID is 1\r
 158  *     #define PRIO_OF_ISR_TIMER1 3  // the hardware priority of the interrupt\r
 159  *     ...\r
 160  *     vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
 161  *     ...\r
 162  *     void ISR_handler()\r
 163  *     {\r
 164  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 165  *         vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
 166  *         portEXIT_CRITICAL();\r
 167  *         ...\r
 168  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 169  *         vTraceStoreISREnd();\r
 170  *         portEXIT_CRITICAL();\r
 171  *     }\r
 172  ******************************************************************************/\r
 173 void vTraceSetISRProperties(objectHandleType handle, const char* name, char priority);\r
 174 \r
 175 /*******************************************************************************\r
 176  * vTraceStoreISRBegin\r
 177  *\r
 178  * Registers the beginning of an Interrupt Service Routine.\r
 179  * If allowing nested ISRs, this must be called with interrupts disabled.\r
 180  *\r
 181  * Example:\r
 182  *     #define ID_ISR_TIMER1 1       // lowest valid ID is 1\r
 183  *     #define PRIO_OF_ISR_TIMER1 3  // the hardware priority of the interrupt\r
 184  *     ...\r
 185  *     vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
 186  *     ...\r
 187  *     void ISR_handler()\r
 188  *     {\r
 189  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 190  *         vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
 191  *         portEXIT_CRITICAL();\r
 192  *         ...\r
 193  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 194  *         vTraceStoreISREnd();\r
 195  *         portEXIT_CRITICAL();\r
 196  *     }\r
 197  *\r
 198  ******************************************************************************/\r
 199 void vTraceStoreISRBegin(objectHandleType id);\r
 200 \r
 201 /*******************************************************************************\r
 202  * vTraceStoreISREnd\r
 203  *\r
 204  * Registers the end of an Interrupt Service Routine.\r
 205  *\r
 206  * If allowing nested ISRs, this must be called with interrupts disabled.\r
 207  *\r
 208  * Example:\r
 209  *     #define ID_ISR_TIMER1 1       // lowest valid ID is 1\r
 210  *     #define PRIO_OF_ISR_TIMER1 3  // the hardware priority of the interrupt\r
 211  *     ...\r
 212  *     vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
 213  *     ...\r
 214  *     void ISR_handler()\r
 215  *     {\r
 216  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 217  *         vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
 218  *         portEXIT_CRITICAL();\r
 219  *         ...\r
 220  *         portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
 221  *         vTraceStoreISREnd();\r
 222  *         portEXIT_CRITICAL();\r
 223  *     }\r
 224  *\r
 225  ******************************************************************************/\r
 226 void vTraceStoreISREnd(void);\r
 227 \r
 228 #else\r
 229    /* If not including the ISR recording */\r
 230 \r
 231 void vTraceIncreaseISRActive(void);\r
 232 \r
 233 void vTraceDecreaseISRActive(void);\r
 234 \r
 235 #define vTraceSetISRProperties(handle, name, priority)\r
 236 #define vTraceStoreISRBegin(id) vTraceIncreaseISRActive()\r
 237 #define vTraceStoreISREnd() vTraceDecreaseISRActive()\r
 238 \r
 239 #endif\r
 240 \r
 241 /*******************************************************************************\r
 242  * vvTraceTaskSkipDefaultInstanceFinishedEvents\r
 243  *\r
 244  * This is useful if there are implicit Instance Finish Events, such as\r
 245  * vTaskDelayUntil or xQueueReceive, in a task where an explicit Instance Finish\r
 246  * Event has been defined. This function tells the recorder that only the\r
 247  * explicitly defined functions (using vTraceTaskInstanceIsFinished) should be\r
 248  * treated as Instance Finish Events for this task. The implicit Instance Finish\r
 249  * Events are thus disregarded for this task.\r
 250  ******************************************************************************/\r
 251 void vTraceTaskSkipDefaultInstanceFinishedEvents(void);\r
 252 \r
 253 /*******************************************************************************\r
 254  * vTraceTaskInstanceIsFinished\r
 255  *\r
 256  * This defines an explicit Instance Finish Event for the current task. It tells\r
 257  * the recorder that the current instance of this task is finished at the next\r
 258  * kernel call of the task, e.g., a taskDelay or a queue receive. This function\r
 259  * should be called right before the api function call considered to be the end\r
 260  * of the task instamce, i.e., the Instance Finish Event.\r
 261  ******************************************************************************/\r
 262 void vTraceTaskInstanceIsFinished(void);\r
 263 \r
 264 /*******************************************************************************\r
 265  * vTraceGetTraceBuffer\r
 266  *\r
 267  * Returns a pointer to the recorder data structure. Use this together with\r
 268  * uiTraceGetTraceBufferSize if you wish to implement an own store/upload\r
 269  * solution, e.g., in case a debugger connection is not available for uploading\r
 270  * the data.\r
 271  ******************************************************************************/\r
 272 void* vTraceGetTraceBuffer(void);\r
 273 \r
 274 /*******************************************************************************\r
 275  * uiTraceGetTraceBufferSize\r
 276  *\r
 277  * Gets the size of the recorder data structure. For use together with\r
 278  * vTraceGetTraceBuffer if you wish to implement an own store/upload solution,\r
 279  * e.g., in case a debugger connection is not available for uploading the data.\r
 280  ******************************************************************************/\r
 281 uint32_t uiTraceGetTraceBufferSize(void);\r
 282 \r
 283 #if (INCLUDE_USER_EVENTS == 1)\r
 284 \r
 285 /*******************************************************************************\r
 286  * xTraceOpenLabel\r
 287  *\r
 288  * Creates user event labels for user event channels or for individual events.\r
 289  * User events can be used to log application events and data for display in\r
 290  * the visualization tool. A user event is identified by a label, i.e., a string,\r
 291  * which is stored in the recorder's symbol table.\r
 292  * When logging a user event, a numeric handle (reference) to this string is\r
 293  * used to identify the event. This is obtained by calling\r
 294  *\r
 295  *     xTraceOpenLabel()\r
 296  *\r
 297  * whihc adds the string to the symbol table (if not already present)\r
 298  * and returns the corresponding handle.\r
 299  *\r
 300  * This can be used in two ways:\r
 301  *\r
 302  * 1. The handle is looked up every time, when storing the user event.\r
 303  *\r
 304  * Example:\r
 305  *     vTraceUserEvent(xTraceOpenLabel("MyUserEvent"));\r
 306  *\r
 307  * 2. The label is registered just once, with the handle stored in an\r
 308  *  application variable - much like using a file handle.\r
 309  *\r
 310  * Example:\r
 311  *     myEventHandle = xTraceOpenLabel("MyUserEvent");\r
 312  *     ...\r
 313  *     vTraceUserEvent(myEventHandle);\r
 314  *\r
 315  * The second option is faster since no lookup is required on each event, and\r
 316  * therefore recommended for user events that are frequently\r
 317  * executed and/or located in time-critical code. The lookup operation is\r
 318  * however fairly fast due to the design of the symbol table.\r
 319  ******************************************************************************/\r
 320 traceLabel xTraceOpenLabel(const char* label);\r
 321 \r
 322  /******************************************************************************\r
 323  * vTraceUserEvent\r
 324  *\r
 325  * Basic user event (Standard and Professional Edition only)\r
 326  *\r
 327  * Generates a User Event with a text label. The label is created/looked up\r
 328  * in the symbol table using xTraceOpenLabel.\r
 329  ******************************************************************************/\r
 330 void vTraceUserEvent(traceLabel eventLabel);\r
 331 \r
 332  /******************************************************************************\r
 333  * vTracePrintF\r
 334  *\r
 335  * Advanced user events (Professional Edition only)\r
 336  *\r
 337  * Generates User Event with formatted text and data, similar to a "printf".\r
 338  * It is very fast compared to a normal "printf" since this function only\r
 339  * stores the arguments. The actual formatting is done\r
 340  * on the host PC when the trace is displayed in the viewer tool.\r
 341  *\r
 342  * User Event labels are created using xTraceOpenLabel.\r
 343  * Example:\r
 344  *\r
 345  *     traceLabel adc_uechannel = xTraceOpenLabel("ADC User Events");\r
 346  *     ...\r
 347  *     vTracePrint(adc_uechannel,\r
 348  *                 "ADC channel %d: %lf volts",\r
 349  *                 ch, (double)adc_reading/(double)scale);\r
 350  *\r
 351  * This can be combined into one line, if desired, but this is slower:\r
 352  *\r
 353  *     vTracePrint(xTraceOpenLabel("ADC User Events"),\r
 354  *                 "ADC channel %d: %lf volts",\r
 355  *                 ch, (double)adc_reading/(double)scale);\r
 356  *\r
 357  * Calling xTraceOpenLabel multiple times will not create duplicate entries, but\r
 358  * it is of course faster to just do it once, and then keep the handle for later\r
 359  * use. If you don´t have any data arguments, only a text label/string, it is\r
 360  * better to use vTraceUserEvent - it is faster.\r
 361  *\r
 362  * Format specifiers supported:\r
 363  *  %d - 32 bit signed integer\r
 364  *  %u - 32 bit unsigned integer\r
 365  *  %f - 32 bit float\r
 366  *  %s - string (is copied to the recorder symbol table)\r
 367  *  %hd - 16 bit signed integer\r
 368  *  %hu - 16 bit unsigned integer\r
 369  *  %bd - 8 bit signed integer\r
 370  *  %bu - 8 bit unsigned integer\r
 371  *  %lf - double-precision float (Note! See below...)\r
 372  *\r
 373  * Up to 15 data arguments are allowed, with a total size of maximum 32 byte.\r
 374  * In case this is exceeded, the user event is changed into an error message.\r
 375  *\r
 376  * The data is stored in trace buffer, and is packed to allow storing multiple\r
 377  * smaller data entries in the same 4-byte record, e.g., four 8-bit values.\r
 378  * A string requires two bytes, as the symbol table is limited to 64K. Storing\r
 379  * a double (%lf) uses two records, so this is quite costly. Use float (%f)\r
 380  * unless the higher precision is really necessary.\r
 381  *\r
 382  * Note that the double-precision float (%lf) assumes a 64 bit double\r
 383  * representation. This does not seem to be the case on e.g. PIC24F.\r
 384  * Before using a %lf argument on a 16-bit MCU, please verify that\r
 385  * "sizeof(double)" actually gives 8 as expected. If not, use %f instead.\r
 386  ******************************************************************************/\r
 387 void vTracePrintF(traceLabel eventLabel, const char* formatStr, ...);\r
 388 \r
 389 #if (USE_SEPARATE_USER_EVENT_BUFFER == 1)\r
 390 UserEventChannel xTraceRegisterChannelFormat(traceLabel channel, traceLabel formatStr);\r
 391 void vTraceChannelPrintF(UserEventChannel channel, ...);\r
 392 void vTraceChannelUserEvent(UserEventChannel channel);\r
 393 #endif\r
 394 \r
 395 #else\r
 396 \r
 397 #define vTracePrintF(eventLabel, formatStr, ...);\r
 398 #define xTraceOpenLabel(label) 0\r
 399 #define vTraceUserEvent(eventLabel)\r
 400 \r
 401 #endif\r
 402 \r
 403 #else\r
 404 \r
 405 /* Empty defines for user functions to avoid compiler errors if trace is not to be used */\r
 406 \r
 407 #define vTraceInitTraceData()\r
 408 #define uiTraceStart() (1) // Fake "success", if used when recorder is excluded from build\r
 409 #define vTraceStart()\r
 410 #define vTraceStop()\r
 411 #define vTraceClear()\r
 412 #define vTraceStartStatusMonitor()\r
 413 #define vTraceGetTraceBuffer() ((void*)0)\r
 414 #define uiTraceGetTraceBufferSize() 0\r
 415 #define xTraceOpenLabel(label) 0\r
 416 #define vTraceUserEvent(eventLabel)\r
 417 #define vTracePrintF(eventLabel,formatStr,...)\r
 418 #define vTraceExcludeTaskFromSchedulingTrace(name)\r
 419 \r
 420 #define vTraceTaskSkipDefaultInstanceFinishedEvents()\r
 421 #define vTraceSetISRProperties(handle, name, priority)\r
 422 #define vTraceStoreISRBegin(id)\r
 423 #define vTraceStoreISREnd()\r
 424 #endif\r
 425 \r
 426 #ifdef __cplusplus\r
 427 }\r
 428 #endif\r
 429 \r
 430 #endif\r