/*******************************************************************************\r
- * Tracealyzer v2.6.0 Recorder Library\r
+ * Tracealyzer v2.7.0 Recorder Library\r
* Percepio AB, www.percepio.com\r
*\r
* trcUser.h\r
* damages, or the exclusion of implied warranties or limitations on how long an\r
* implied warranty may last, so the above limitations may not apply to you.\r
*\r
- * Copyright Percepio AB, 2013.\r
+ * Tabs are used for indent in this file (1 tab = 4 spaces)\r
+ *\r
+ * Copyright Percepio AB, 2014.\r
* www.percepio.com\r
******************************************************************************/\r
\r
void vTraceSetRecorderData(void* pRecorderData);\r
#endif\r
\r
+/*******************************************************************************\r
+ * vTraceSetStopHook\r
+ *\r
+ * Sets a function to be called when the recorder is stopped.\r
+ ******************************************************************************/\r
+void vTraceSetStopHook(TRACE_STOP_HOOK stopHookFunction);\r
+\r
/*******************************************************************************\r
* uiTraceStart\r
*\r
* started.\r
*\r
* Example:\r
- * #define ID_ISR_TIMER1 1 // lowest valid ID is 1\r
- * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt\r
- * ...\r
- * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
- * ...\r
- * void ISR_handler()\r
- * {\r
- * portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
- * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
- * portEXIT_CRITICAL();\r
- * ...\r
- * portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
- * vTraceStoreISREnd();\r
- * portEXIT_CRITICAL();\r
- * }\r
+ * #define ID_ISR_TIMER1 1 // lowest valid ID is 1\r
+ * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt\r
+ * ...\r
+ * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
+ * ...\r
+ * void ISR_handler()\r
+ * {\r
+ * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
+ * ...\r
+ * vTraceStoreISREnd(0);\r
+ * }\r
******************************************************************************/\r
void vTraceSetISRProperties(objectHandleType handle, const char* name, char priority);\r
\r
* If allowing nested ISRs, this must be called with interrupts disabled.\r
*\r
* Example:\r
- * #define ID_ISR_TIMER1 1 // lowest valid ID is 1\r
- * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt\r
- * ...\r
- * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
- * ...\r
- * void ISR_handler()\r
- * {\r
- * portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
- * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
- * portEXIT_CRITICAL();\r
- * ...\r
- * portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
- * vTraceStoreISREnd();\r
- * portEXIT_CRITICAL();\r
- * }\r
+ * #define ID_ISR_TIMER1 1 // lowest valid ID is 1\r
+ * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt\r
+ * ...\r
+ * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
+ * ...\r
+ * void ISR_handler()\r
+ * {\r
+ * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
+ * ...\r
+ * vTraceStoreISREnd(0);\r
+ * }\r
*\r
******************************************************************************/\r
void vTraceStoreISRBegin(objectHandleType id);\r
*\r
* Registers the end of an Interrupt Service Routine.\r
*\r
- * If allowing nested ISRs, this must be called with interrupts disabled.\r
+ * The parameter pendingISR indicates if the interrupt has requested a\r
+ * task-switch (= 1) or if the interrupt returns to the earlier context (= 0)\r
*\r
* Example:\r
- * #define ID_ISR_TIMER1 1 // lowest valid ID is 1\r
- * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt\r
- * ...\r
- * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
- * ...\r
- * void ISR_handler()\r
- * {\r
- * portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
- * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
- * portEXIT_CRITICAL();\r
- * ...\r
- * portENTER_CRITICAL(); // Required if nested ISRs are allowed\r
- * vTraceStoreISREnd();\r
- * portEXIT_CRITICAL();\r
- * }\r
+ * #define ID_ISR_TIMER1 1 // lowest valid ID is 1\r
+ * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt\r
+ * ...\r
+ * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);\r
+ * ...\r
+ * void ISR_handler()\r
+ * {\r
+ * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);\r
+ * ...\r
+ * vTraceStoreISREnd(0);\r
+ * }\r
*\r
******************************************************************************/\r
-void vTraceStoreISREnd(void);\r
+void vTraceStoreISREnd(int pendingISR);\r
\r
#else\r
- /* If not including the ISR recording */\r
+ /* If not including the ISR recording */\r
\r
void vTraceIncreaseISRActive(void);\r
\r
\r
#endif\r
\r
-/*******************************************************************************\r
- * vvTraceTaskSkipDefaultInstanceFinishedEvents\r
- *\r
- * This is useful if there are implicit Instance Finish Events, such as\r
- * vTaskDelayUntil or xQueueReceive, in a task where an explicit Instance Finish\r
- * Event has been defined. This function tells the recorder that only the\r
- * explicitly defined functions (using vTraceTaskInstanceIsFinished) should be\r
- * treated as Instance Finish Events for this task. The implicit Instance Finish\r
- * Events are thus disregarded for this task.\r
- ******************************************************************************/\r
-void vTraceTaskSkipDefaultInstanceFinishedEvents(void);\r
\r
-/*******************************************************************************\r
- * vTraceTaskInstanceIsFinished\r
+/******************************************************************************\r
+ * vTraceTaskInstanceFinish(void)\r
*\r
- * This defines an explicit Instance Finish Event for the current task. It tells\r
- * the recorder that the current instance of this task is finished at the next\r
- * kernel call of the task, e.g., a taskDelay or a queue receive. This function\r
- * should be called right before the api function call considered to be the end\r
- * of the task instamce, i.e., the Instance Finish Event.\r
- ******************************************************************************/\r
-void vTraceTaskInstanceIsFinished(void);\r
+ * Marks the current task instance as finished on the next kernel call.\r
+ *\r
+ * If that kernel call is blocking, the instance ends after the blocking event\r
+ * and the corresponding return event is then the start of the next instance.\r
+ * If the kernel call is not blocking, the viewer instead splits the current\r
+ * fragment right before the kernel call, which makes this call the first event\r
+ * of the next instance.\r
+ *\r
+ * See also USE_IMPLICIT_IFE_RULES in trcConfig.h\r
+ *\r
+ * Example:\r
+ *\r
+ * while(1)\r
+ * {\r
+ * xQueueReceive(CommandQueue, &command, timeoutDuration);\r
+ * processCommand(command);\r
+ * vTraceInstanceFinish();\r
+ * }\r
+ *\r
+ *****************************************************************************/\r
+void vTraceTaskInstanceFinish(void);\r
+\r
+/******************************************************************************\r
+ * vTraceTaskInstanceFinishDirect(void)\r
+ *\r
+ * Marks the current task instance as finished at this very instant.\r
+ * This makes the viewer to splits the current fragment at this point and begin\r
+ * a new actor instance.\r
+ *\r
+ * See also USE_IMPLICIT_IFE_RULES in trcConfig.h\r
+ *\r
+ * Example:\r
+ *\r
+ * This example will generate two instances for each loop iteration.\r
+ * The first instance ends at vTraceInstanceFinishDirect(), while the second\r
+ * instance ends at the next xQueueReceive call.\r
+ *\r
+ * while (1)\r
+ * {\r
+ * xQueueReceive(CommandQueue, &command, timeoutDuration);\r
+ * ProcessCommand(command);\r
+ * vTraceInstanceFinishDirect();\r
+ * DoSometingElse();\r
+ * vTraceInstanceFinish();\r
+ * }\r
+ *\r
+ *\r
+ *****************************************************************************/\r
+void vTraceTaskInstanceFinishDirect(void);\r
\r
/*******************************************************************************\r
* vTraceGetTraceBuffer\r
* When logging a user event, a numeric handle (reference) to this string is\r
* used to identify the event. This is obtained by calling\r
*\r
- * xTraceOpenLabel()\r
+ * xTraceOpenLabel()\r
*\r
* whihc adds the string to the symbol table (if not already present)\r
* and returns the corresponding handle.\r
* 1. The handle is looked up every time, when storing the user event.\r
*\r
* Example:\r
- * vTraceUserEvent(xTraceOpenLabel("MyUserEvent"));\r
+ * vTraceUserEvent(xTraceOpenLabel("MyUserEvent"));\r
*\r
* 2. The label is registered just once, with the handle stored in an\r
- * application variable - much like using a file handle.\r
+ * application variable - much like using a file handle.\r
*\r
* Example:\r
- * myEventHandle = xTraceOpenLabel("MyUserEvent");\r
- * ...\r
- * vTraceUserEvent(myEventHandle);\r
+ * myEventHandle = xTraceOpenLabel("MyUserEvent");\r
+ * ...\r
+ * vTraceUserEvent(myEventHandle);\r
*\r
* The second option is faster since no lookup is required on each event, and\r
* therefore recommended for user events that are frequently\r
* User Event labels are created using xTraceOpenLabel.\r
* Example:\r
*\r
- * traceLabel adc_uechannel = xTraceOpenLabel("ADC User Events");\r
- * ...\r
- * vTracePrint(adc_uechannel,\r
- * "ADC channel %d: %lf volts",\r
- * ch, (double)adc_reading/(double)scale);\r
+ * traceLabel adc_uechannel = xTraceOpenLabel("ADC User Events");\r
+ * ...\r
+ * vTracePrint(adc_uechannel,\r
+ * "ADC channel %d: %lf volts",\r
+ * ch, (double)adc_reading/(double)scale);\r
*\r
* This can be combined into one line, if desired, but this is slower:\r
*\r
- * vTracePrint(xTraceOpenLabel("ADC User Events"),\r
- * "ADC channel %d: %lf volts",\r
- * ch, (double)adc_reading/(double)scale);\r
+ * vTracePrint(xTraceOpenLabel("ADC User Events"),\r
+ * "ADC channel %d: %lf volts",\r
+ * ch, (double)adc_reading/(double)scale);\r
*\r
* Calling xTraceOpenLabel multiple times will not create duplicate entries, but\r
* it is of course faster to just do it once, and then keep the handle for later\r
* better to use vTraceUserEvent - it is faster.\r
*\r
* Format specifiers supported:\r
- * %d - 32 bit signed integer\r
- * %u - 32 bit unsigned integer\r
- * %f - 32 bit float\r
- * %s - string (is copied to the recorder symbol table)\r
- * %hd - 16 bit signed integer\r
- * %hu - 16 bit unsigned integer\r
- * %bd - 8 bit signed integer\r
- * %bu - 8 bit unsigned integer\r
- * %lf - double-precision float (Note! See below...)\r
+ * %d - 32 bit signed integer\r
+ * %u - 32 bit unsigned integer\r
+ * %f - 32 bit float\r
+ * %s - string (is copied to the recorder symbol table)\r
+ * %hd - 16 bit signed integer\r
+ * %hu - 16 bit unsigned integer\r
+ * %bd - 8 bit signed integer\r
+ * %bu - 8 bit unsigned integer\r
+ * %lf - double-precision float (Note! See below...)\r
*\r
* Up to 15 data arguments are allowed, with a total size of maximum 32 byte.\r
* In case this is exceeded, the user event is changed into an error message.\r
* unless the higher precision is really necessary.\r
*\r
* Note that the double-precision float (%lf) assumes a 64 bit double\r
- * representation. This does not seem to be the case on e.g. PIC24F.\r
+ * representation. This does not seem to be the case on e.g. PIC24 and PIC32.\r
* Before using a %lf argument on a 16-bit MCU, please verify that\r
* "sizeof(double)" actually gives 8 as expected. If not, use %f instead.\r
******************************************************************************/\r
#define vTracePrintF(eventLabel,formatStr,...)\r
#define vTraceExcludeTaskFromSchedulingTrace(name)\r
\r
-#define vTraceTaskSkipDefaultInstanceFinishedEvents()\r
#define vTraceSetISRProperties(handle, name, priority)\r
#define vTraceStoreISRBegin(id)\r
#define vTraceStoreISREnd()\r
#define vTraceSetSemaphoreName(a, b)\r
#define vTraceSetEventGroupName(a, b)\r
\r
+#define vTraceSetStopHook(a)\r
#endif\r
\r
#ifdef __cplusplus\r
projects / freertos / blobdiff