1 /*******************************************************************************
\r
2 * Tracealyzer v2.5.0 Recorder Library
\r
3 * Percepio AB, www.percepio.com
\r
7 * The public API of the trace recorder library.
\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
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
34 * Copyright Percepio AB, 2013.
\r
36 ******************************************************************************/
\r
38 #include "trcUser.h"
\r
40 #if (USE_TRACEALYZER_RECORDER == 1)
\r
46 TRACE_STOP_HOOK vTraceStopHookPtr = (TRACE_STOP_HOOK)0;
\r
48 extern uint8_t inExcludedTask;
\r
49 extern uint8_t nISRactive;
\r
50 extern uint8_t handle_of_last_logged_task;
\r
51 extern uint32_t dts_min;
\r
52 extern uint32_t hwtc_count_max_after_tick;
\r
53 extern uint32_t hwtc_count_sum_after_tick;
\r
54 extern uint32_t hwtc_count_sum_after_tick_counter;
\r
55 extern char* traceErrorMessage;
\r
57 /*** private functions *******************************************************/
\r
58 void vTracePrintF_Helper(traceLabel eventLabel, const char* formatStr, va_list vl);
\r
60 #if (USE_SEPARATE_USER_EVENT_BUFFER == 1)
\r
61 void vTraceChannelPrintF_Helper(UserEventChannel channelPair, va_list vl);
\r
62 static void prvTraceUserEventHelper1(UserEventChannel channel, traceLabel eventLabel, traceLabel formatLabel, va_list vl);
\r
63 static void prvTraceUserEventHelper2(UserEventChannel channel, uint32_t* data, uint32_t noOfSlots);
\r
65 /*****************************************************************************/
\r
69 /*******************************************************************************
\r
70 * vTraceInitTraceData
\r
72 * Allocates, if necessary, and initializes the recorder data structure, based
\r
73 * on the constants in trcConfig.h.
\r
74 ******************************************************************************/
\r
75 void vTraceInitTraceData(void)
\r
77 prvTraceInitTraceData();
\r
80 /*******************************************************************************
\r
81 * vTraceSetRecorderData
\r
83 * If custom allocation is used, this function must be called so the recorder
\r
84 * library knows where to save the trace data.
\r
85 ******************************************************************************/
\r
86 #if TRACE_DATA_ALLOCATION == TRACE_DATA_ALLOCATION_CUSTOM
\r
87 void vTraceSetRecorderData(void* pRecorderData)
\r
89 TRACE_ASSERT(pRecorderData != NULL, "vTraceSetTraceData, pRecorderData == NULL", );
\r
90 RecorderDataPtr = pRecorderData;
\r
94 /*******************************************************************************
\r
97 * Resets the recorder. Only necessary if a restart is desired - this is not
\r
98 * needed in the startup initialization.
\r
99 ******************************************************************************/
\r
100 void vTraceClear(void)
\r
102 trcCRITICAL_SECTION_BEGIN();
\r
104 RecorderDataPtr->absTimeLastEvent = 0;
\r
105 RecorderDataPtr->nextFreeIndex = 0;
\r
106 RecorderDataPtr->numEvents = 0;
\r
107 RecorderDataPtr->bufferIsFull = 0;
\r
109 trcCRITICAL_SECTION_END();
\r
113 /*******************************************************************************
\r
116 * Starts the recorder. The recorder will not be started if an error has been
\r
117 * indicated using vTraceError, e.g. if any of the Nx constants in trcConfig.h
\r
118 * has a too small value (NTASK, NQUEUE, etc).
\r
120 * Returns 1 if the recorder was started successfully.
\r
121 * Returns 0 if the recorder start was prevented due to a previous internal
\r
122 * error. In that case, check vTraceGetLastError to get the error message.
\r
123 * Any error message is also presented when opening a trace file.
\r
124 ******************************************************************************/
\r
126 uint32_t uiTraceStart(void)
\r
128 objectHandleType handle = 0;
\r
130 if (RecorderDataPtr == NULL)
\r
132 vTraceError("RecorderDataPtr is NULL. Call vTraceInitTraceData() before starting trace.");
\r
135 if (traceErrorMessage == NULL)
\r
137 trcCRITICAL_SECTION_BEGIN();
\r
138 RecorderDataPtr->recorderActive = 1;
\r
140 handle = TRACE_GET_TASK_NUMBER(TRACE_GET_CURRENT_TASK());
\r
143 /* This occurs if the scheduler is not yet started.
\r
144 This creates a dummy "(startup)" task entry internally in the
\r
146 handle = xTraceGetObjectHandle(TRACE_CLASS_TASK);
\r
147 vTraceSetObjectName(TRACE_CLASS_TASK, handle, "(startup)");
\r
149 vTraceSetPriorityProperty(TRACE_CLASS_TASK, handle, 0);
\r
152 vTraceStoreTaskswitch(handle); /* Register the currently running task */
\r
153 trcCRITICAL_SECTION_END();
\r
156 return RecorderDataPtr->recorderActive;
\r
159 /*******************************************************************************
\r
162 * Starts the recorder. The recorder will not be started if an error has been
\r
163 * indicated using vTraceError, e.g. if any of the Nx constants in trcConfig.h
\r
164 * has a too small value (NTASK, NQUEUE, etc).
\r
166 * This function is obsolete, but has been saved for backwards compatibility.
\r
167 * We recommend using uiTraceStart instead.
\r
168 ******************************************************************************/
\r
169 void vTraceStart(void)
\r
171 (void)uiTraceStart();
\r
174 /*******************************************************************************
\r
177 * Stops the recorder. The recording can be resumed by calling vTraceStart.
\r
178 * This does not reset the recorder. Use vTraceClear if that is desired.
\r
179 ******************************************************************************/
\r
180 void vTraceStop(void)
\r
182 RecorderDataPtr->recorderActive = 0;
\r
184 if (vTraceStopHookPtr != (TRACE_STOP_HOOK)0)
\r
186 (*vTraceStopHookPtr)(); /* Call an application level call back function. */
\r
190 /*******************************************************************************
\r
191 * xTraceGetLastError
\r
193 * Gives the last error message, if any. NULL if no error message is stored.
\r
194 * Any error message is also presented when opening a trace file.
\r
195 ******************************************************************************/
\r
196 char* xTraceGetLastError(void)
\r
198 return traceErrorMessage;
\r
201 /*******************************************************************************
\r
204 * Removes any previous error message generated by recorder calling vTraceError.
\r
205 * By calling this function, it may be possible to start/restart the trace
\r
206 * despite errors in the recorder, but there is no guarantee that the trace
\r
207 * recorder will work correctly in that case, depending on the type of error.
\r
208 ******************************************************************************/
\r
209 void vTraceClearError(int resetErrorMessage)
\r
211 ( void ) resetErrorMessage;
\r
212 traceErrorMessage = NULL;
\r
213 RecorderDataPtr->internalErrorOccured = 0;
\r
216 /*******************************************************************************
\r
217 * vTraceGetTraceBuffer
\r
219 * Returns a pointer to the recorder data structure. Use this together with
\r
220 * uiTraceGetTraceBufferSize if you wish to implement an own store/upload
\r
221 * solution, e.g., in case a debugger connection is not available for uploading
\r
223 ******************************************************************************/
\r
224 void* vTraceGetTraceBuffer(void)
\r
226 return RecorderDataPtr;
\r
229 /*******************************************************************************
\r
230 * uiTraceGetTraceBufferSize
\r
232 * Gets the size of the recorder data structure. For use together with
\r
233 * vTraceGetTraceBuffer if you wish to implement an own store/upload solution,
\r
234 * e.g., in case a debugger connection is not available for uploading the data.
\r
235 ******************************************************************************/
\r
236 uint32_t uiTraceGetTraceBufferSize(void)
\r
238 return sizeof(RecorderDataType);
\r
241 /******************************************************************************
\r
242 * vTraceTaskInstanceIsFinished
\r
244 * This defines an explicit Instance Finish Event for the current task. It tells
\r
245 * the recorder that the current instance of this task is finished at the
\r
246 * context-switch. This function should be called right before the API function
\r
247 * call considered to be the Instance Finish Event.
\r
248 *****************************************************************************/
\r
249 void vTraceTaskInstanceIsFinished()
\r
251 if (handle_of_last_logged_task)
\r
253 TRACE_PROPERTY_OBJECT_STATE(TRACE_CLASS_TASK, handle_of_last_logged_task) = 0;
\r
257 /*******************************************************************************
\r
258 * Interrupt recording functions
\r
259 ******************************************************************************/
\r
261 #if (INCLUDE_ISR_TRACING == 1)
\r
263 #define MAX_ISR_NESTING 16
\r
264 static uint8_t isrstack[MAX_ISR_NESTING];
\r
266 /*******************************************************************************
\r
267 * vTraceSetISRProperties
\r
269 * Registers an Interrupt Service Routine in the recorder library, This must be
\r
270 * called before using vTraceStoreISRBegin to store ISR events. This is
\r
271 * typically called in the startup of the system, before the scheduler is
\r
275 * #define ID_ISR_TIMER1 1 // lowest valid ID is 1
\r
276 * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt
\r
278 * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);
\r
280 * void ISR_handler()
\r
282 * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);
\r
284 * vTraceStoreISREnd();
\r
287 * NOTE: To safely record ISRs, you need to make sure that all traced
\r
288 * interrupts actually are disabled by trcCRITICAL_SECTION_BEGIN(). However,
\r
289 * in some ports this does not disable high priority interrupts!
\r
290 * If an ISR calls vTraceStoreISRBegin while the recorder is busy, it will
\r
291 * stop the recording and give an error message.
\r
292 ******************************************************************************/
\r
293 void vTraceSetISRProperties(objectHandleType handle, const char* name, char priority)
\r
295 TRACE_ASSERT(handle <= RecorderDataPtr->ObjectPropertyTable.NumberOfObjectsPerClass[TRACE_CLASS_ISR], "vTraceSetISRProperties: Invalid value for handle", );
\r
296 TRACE_ASSERT(name != NULL, "vTraceSetISRProperties: name == NULL", );
\r
297 TRACE_ASSERT(priority >= 0, "vTraceSetISRProperties: Invalid value for priority", );
\r
299 vTraceSetObjectName(TRACE_CLASS_ISR, handle, name);
\r
300 vTraceSetPriorityProperty(TRACE_CLASS_ISR, handle, priority);
\r
303 /*******************************************************************************
\r
304 * vTraceStoreISRBegin
\r
306 * Registers the beginning of an Interrupt Service Routine.
\r
309 * #define ID_ISR_TIMER1 1 // lowest valid ID is 1
\r
310 * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt
\r
312 * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);
\r
314 * void ISR_handler()
\r
316 * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);
\r
318 * vTraceStoreISREnd();
\r
321 * NOTE: You need to make sure that any traced interrupts actually are
\r
322 * disabled by trcCRITICAL_SECTION_BEGIN().
\r
323 * If an invalid call to vTraceStoreISRBegin is detected (i.e., that preempted
\r
324 * a critical section of the recorder) this will generate a recorder error
\r
325 * using vTraceError.
\r
326 ******************************************************************************/
\r
327 void vTraceStoreISRBegin(objectHandleType handle)
\r
330 TSEvent* ts = NULL;
\r
332 TRACE_ASSERT(handle <= RecorderDataPtr->ObjectPropertyTable.NumberOfObjectsPerClass[TRACE_CLASS_ISR], "vTraceStoreISRBegin: Invalid value for handle", );
\r
336 vTraceError("Illegal call to vTraceStoreISRBegin, recorder busy!");
\r
339 if (RecorderDataPtr->recorderActive && handle_of_last_logged_task)
\r
341 trcCRITICAL_SECTION_BEGIN();
\r
342 dts4 = (uint16_t)prvTraceGetDTS(0xFFFF);
\r
344 if (RecorderDataPtr->recorderActive) /* Need to repeat this check! */
\r
347 if (nISRactive < MAX_ISR_NESTING)
\r
349 isrstack[nISRactive] = handle;
\r
351 ts = (TSEvent*)xTraceNextFreeEventBufferSlot();
\r
354 ts->type = TS_ISR_BEGIN;
\r
356 ts->objHandle = handle;
\r
357 prvTraceUpdateCounters();
\r
362 /* This should not occur unless something is very wrong */
\r
363 vTraceError("Too many nested interrupts!");
\r
366 trcCRITICAL_SECTION_END();
\r
371 #if (SELECTED_PORT == PORT_ARM_CortexM)
\r
373 static int tailchain_irq_pending(void);
\r
375 /*******************************************************************************
\r
376 * tailchain_irq_pending
\r
378 * For Cortex-M chips only. Returns 1 if an interrupt is pending, by checking
\r
379 * the 8 NVIC IRQ pend registers at 0xE000E200 to 0xE000E21C. Returns 0 if no
\r
380 * interrupt is pending. This is used to predict tailchaining of ISRs.
\r
381 ******************************************************************************/
\r
382 static int tailchain_irq_pending(void)
\r
384 uint32_t* pend_reg = ((uint32_t*)0xE000E200);
\r
387 for (i=0; i<8; i++)
\r
389 if (pend_reg[i] != 0)
\r
399 /*******************************************************************************
\r
400 * vTraceStoreISREnd
\r
402 * Registers the end of an Interrupt Service Routine.
\r
405 * #define ID_ISR_TIMER1 1 // lowest valid ID is 1
\r
406 * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt
\r
408 * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);
\r
410 * void ISR_handler()
\r
412 * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);
\r
414 * vTraceStoreISREnd();
\r
417 * NOTE: You need to make sure that any traced interrupts actually are
\r
418 * disabled by trcCRITICAL_SECTION_BEGIN().
\r
419 * If an invalid call to vTraceStoreISREnd is detected (i.e., that preempted
\r
420 * a critical section of the recorder) this will generate a recorder error
\r
421 * using vTraceError.
\r
422 ******************************************************************************/
\r
423 void vTraceStoreISREnd(void)
\r
430 vTraceError("Illegal call to vTraceStoreISREnd, recorder busy!");
\r
434 if (RecorderDataPtr->recorderActive && handle_of_last_logged_task)
\r
436 #if (SELECTED_PORT == PORT_ARM_CortexM)
\r
437 if (tailchain_irq_pending() > 0)
\r
439 nISRactive--; /* If an IRQ strikes exactly here, the resulting
\r
440 ISR tailchaining is not detected. The trace instead shows a very
\r
441 short fragment of the earlier preempted task/ISR, and then the new
\r
447 trcCRITICAL_SECTION_BEGIN();
\r
448 dts5 = (uint16_t)prvTraceGetDTS(0xFFFF);
\r
450 if (RecorderDataPtr->recorderActive) /* Need to repeat this check! */
\r
452 ts = (TSEvent*)xTraceNextFreeEventBufferSlot();
\r
455 if (nISRactive > 1)
\r
457 /* return to another isr */
\r
458 ts->type = TS_ISR_RESUME;
\r
459 ts->objHandle = isrstack[nISRactive];
\r
463 /* return to task */
\r
464 ts->type = TS_TASK_RESUME;
\r
465 ts->objHandle = handle_of_last_logged_task;
\r
469 prvTraceUpdateCounters();
\r
472 trcCRITICAL_SECTION_END();
\r
478 /* ISR tracing is turned off */
\r
479 void vTraceIncreaseISRActive(void)
\r
481 if (RecorderDataPtr->recorderActive && handle_of_last_logged_task)
\r
485 void vTraceDecreaseISRActive(void)
\r
487 if (RecorderDataPtr->recorderActive && handle_of_last_logged_task)
\r
493 /*******************************************************************************
\r
494 * User Event functions
\r
495 ******************************************************************************/
\r
497 #if (INCLUDE_USER_EVENTS == 1)
\r
499 #define MAX_ARG_SIZE (4+32)
\r
500 /*** Locally used in vTracePrintF ***/
\r
501 static uint8_t writeInt8(void * buffer, uint8_t i, uint8_t value)
\r
503 TRACE_ASSERT(buffer != NULL, "writeInt8: buffer == NULL", 0);
\r
505 if (i >= MAX_ARG_SIZE)
\r
510 ((uint8_t*)buffer)[i] = value;
\r
512 if (i + 1 > MAX_ARG_SIZE)
\r
520 /*** Locally used in vTracePrintF ***/
\r
521 static uint8_t writeInt16(void * buffer, uint8_t i, uint16_t value)
\r
523 TRACE_ASSERT(buffer != NULL, "writeInt16: buffer == NULL", 0);
\r
525 /* Align to multiple of 2 */
\r
526 while ((i % 2) != 0)
\r
528 if (i >= MAX_ARG_SIZE)
\r
533 ((uint8_t*)buffer)[i] = 0;
\r
537 if (i + 2 > MAX_ARG_SIZE)
\r
542 ((uint16_t*)buffer)[i/2] = value;
\r
547 /*** Locally used in vTracePrintF ***/
\r
548 static uint8_t writeInt32(void * buffer, uint8_t i, uint32_t value)
\r
550 TRACE_ASSERT(buffer != NULL, "writeInt32: buffer == NULL", 0);
\r
552 /* A 32 bit value should begin at an even 4-byte address */
\r
553 while ((i % 4) != 0)
\r
555 if (i >= MAX_ARG_SIZE)
\r
560 ((uint8_t*)buffer)[i] = 0;
\r
564 if (i + 4 > MAX_ARG_SIZE)
\r
569 ((uint32_t*)buffer)[i/4] = value;
\r
574 #if (INCLUDE_FLOAT_SUPPORT)
\r
576 /*** Locally used in vTracePrintF ***/
\r
577 static uint8_t writeFloat(void * buffer, uint8_t i, float value)
\r
579 TRACE_ASSERT(buffer != NULL, "writeFloat: buffer == NULL", 0);
\r
581 /* A 32 bit value should begin at an even 4-byte address */
\r
582 while ((i % 4) != 0)
\r
584 if (i >= MAX_ARG_SIZE)
\r
589 ((uint8_t*)buffer)[i] = 0;
\r
593 if (i + 4 > MAX_ARG_SIZE)
\r
598 ((float*)buffer)[i/4] = value;
\r
603 /*** Locally used in vTracePrintF ***/
\r
604 static uint8_t writeDouble(void * buffer, uint8_t i, double value)
\r
606 TRACE_ASSERT(buffer != NULL, "writeDouble: buffer == NULL", 0);
\r
608 uint32_t * dest = buffer;
\r
609 uint32_t * src = (void*)&value;
\r
610 /* The double is written as two 32 bit values, and should begin at an even
\r
611 4-byte address (to avoid having to align with 8 byte) */
\r
614 if (i >= MAX_ARG_SIZE)
\r
619 ((uint8_t*)buffer)[i] = 0;
\r
623 if (i + 8 > MAX_ARG_SIZE)
\r
628 dest[i/4+0] = src[0];
\r
629 dest[i/4+1] = src[1];
\r
636 /*******************************************************************************
\r
637 * prvTraceUserEventFormat
\r
639 * Parses the format string and stores the arguments in the buffer.
\r
640 ******************************************************************************/
\r
641 static uint8_t prvTraceUserEventFormat(const char* formatStr, va_list vl, uint8_t* buffer, uint8_t byteOffset)
\r
643 uint16_t formatStrIndex = 0;
\r
644 uint8_t argCounter = 0;
\r
645 uint8_t i = byteOffset;
\r
647 while (formatStr[formatStrIndex] != '\0')
\r
649 if (formatStr[formatStrIndex] == '%')
\r
653 if (argCounter > 15)
\r
655 vTraceError("vTracePrintF - Too many arguments, max 15 allowed!");
\r
659 /*******************************************************************************
\r
660 * These below code writes raw data (primitive datatypes) in the event buffer,
\r
661 * instead of the normal event structs (where byte 0 is event type).
\r
662 * These data entries must never be interpreted as real event data, as the type
\r
663 * field would be misleading since used for payload data.
\r
665 * The correctness of this encoding depends on two mechanisms:
\r
667 * 1. An initial USER_EVENT, which type code tells the number of 32-bit data
\r
668 * entires that follows. (code - USER_EVENT = number of data entries).
\r
669 * Note that a data entry corresponds to the slots that normally corresponds to
\r
670 * one (1) event, i.e., 32 bits. vTracePrintF may encode several pieces of data
\r
671 * in one data entry, e.g., two 16-bit values or four 8-bit values, one 16-bit
\r
672 * value followed by two 8-bit values, etc.
\r
674 * 2. A two-phase commit procedure, where the USER_EVENT and data entries are
\r
675 * written to a local buffer at first, and when all checks are OK then copied to
\r
676 * the main event buffer using a fast memcpy. The event code is finalized as the
\r
677 * very last step. Before that step, the event code indicates an unfinished
\r
678 * event, which causes it to be ignored and stop the loading of the file (since
\r
679 * an unfinished event is the last event in the trace).
\r
680 *******************************************************************************/
\r
683 while ((formatStr[formatStrIndex] >= '0' && formatStr[formatStrIndex] <= '9') || formatStr[formatStrIndex] == '#' || formatStr[formatStrIndex] == '.')
\r
686 if (formatStr[formatStrIndex] != '\0')
\r
688 switch (formatStr[formatStrIndex])
\r
690 case 'd': i = writeInt32(buffer,
\r
692 (uint32_t)va_arg(vl, uint32_t));
\r
696 case 'u': i = writeInt32(buffer,
\r
698 (uint32_t)va_arg(vl, uint32_t));
\r
700 case 's': i = writeInt16(buffer,
\r
702 (uint16_t)xTraceOpenLabel((char*)va_arg(vl, char*)));
\r
705 #if (INCLUDE_FLOAT_SUPPORT)
\r
706 /* Yes, "double" as type also in the float
\r
707 case. This since "float" is promoted into "double"
\r
708 by the va_arg stuff. */
\r
709 case 'f': i = writeFloat(buffer,
\r
711 (float)va_arg(vl, double));
\r
714 /* No support for floats, but attempt to store a float user event
\r
715 avoid a possible crash due to float reference. Instead store the
\r
716 data on uint_32 format (will not be displayed anyway). This is just
\r
717 to keep va_arg and i consistent. */
\r
719 case 'f': i = writeInt32(buffer,
\r
721 (uint32_t)va_arg(vl, double));
\r
726 switch (formatStr[formatStrIndex])
\r
728 #if (INCLUDE_FLOAT_SUPPORT)
\r
729 case 'f': i = writeDouble(buffer,
\r
731 (double)va_arg(vl, double));
\r
734 /* No support for floats, but attempt to store a float user event
\r
735 avoid a possible crash due to float reference. Instead store the
\r
736 data on uint_32 format (will not be displayed anyway). This is just
\r
737 to keep va_arg and i consistent. */
\r
738 case 'f': i = writeInt32(buffer, /* In this case, the value will not be shown anyway */
\r
740 (uint32_t)va_arg(vl, double));
\r
741 i = writeInt32(buffer, /* Do it twice, to write in total 8 bytes */
\r
743 (uint32_t)va_arg(vl, double));
\r
751 switch (formatStr[formatStrIndex])
\r
753 case 'd': i = writeInt16(buffer,
\r
755 (uint16_t)va_arg(vl, uint32_t));
\r
757 case 'u': i = writeInt16(buffer,
\r
759 (uint16_t)va_arg(vl, uint32_t));
\r
765 switch (formatStr[formatStrIndex])
\r
767 case 'd': i = writeInt8(buffer,
\r
769 (uint8_t)va_arg(vl, uint32_t));
\r
771 case 'u': i = writeInt8(buffer,
\r
773 (uint8_t)va_arg(vl, uint32_t));
\r
785 vTraceError("vTracePrintF - Too large arguments, max 32 byte allowed!");
\r
792 #if (USE_SEPARATE_USER_EVENT_BUFFER == 1)
\r
794 /*******************************************************************************
\r
795 * prvTraceClearChannelBuffer
\r
797 * Clears a number of items in the channel buffer, starting from nextSlotToWrite.
\r
798 ******************************************************************************/
\r
799 static void prvTraceClearChannelBuffer(uint32_t count)
\r
803 TRACE_ASSERT(USER_EVENT_BUFFER_SIZE >= count, "prvTraceClearChannelBuffer: USER_EVENT_BUFFER_SIZE is too small to handle this event.", );
\r
805 /* Check if we're close to the end of the buffer */
\r
806 if (RecorderDataPtr->userEventBuffer.nextSlotToWrite + count > USER_EVENT_BUFFER_SIZE)
\r
808 slots = USER_EVENT_BUFFER_SIZE - RecorderDataPtr->userEventBuffer.nextSlotToWrite; /* Number of slots before end of buffer */
\r
809 (void)memset(&RecorderDataPtr->userEventBuffer.channelBuffer[RecorderDataPtr->userEventBuffer.nextSlotToWrite], 0, slots);
\r
810 (void)memset(&RecorderDataPtr->userEventBuffer.channelBuffer[0], 0, (count - slots));
\r
813 (void)memset(&RecorderDataPtr->userEventBuffer.channelBuffer[RecorderDataPtr->userEventBuffer.nextSlotToWrite], 0, count);
\r
816 /*******************************************************************************
\r
817 * prvTraceCopyToDataBuffer
\r
819 * Copies a number of items to the data buffer, starting from nextSlotToWrite.
\r
820 ******************************************************************************/
\r
821 static void prvTraceCopyToDataBuffer(uint32_t* data, uint32_t count)
\r
823 TRACE_ASSERT(data != NULL, "prvTraceCopyToDataBuffer: data == NULL.", );
\r
824 TRACE_ASSERT(count <= USER_EVENT_BUFFER_SIZE, "prvTraceCopyToDataBuffer: USER_EVENT_BUFFER_SIZE is too small to handle this event.", );
\r
827 /* Check if we're close to the end of the buffer */
\r
828 if (RecorderDataPtr->userEventBuffer.nextSlotToWrite + count > USER_EVENT_BUFFER_SIZE)
\r
830 slots = USER_EVENT_BUFFER_SIZE - RecorderDataPtr->userEventBuffer.nextSlotToWrite; /* Number of slots before end of buffer */
\r
831 (void)memcpy(&RecorderDataPtr->userEventBuffer.dataBuffer[RecorderDataPtr->userEventBuffer.nextSlotToWrite * 4], data, slots * 4);
\r
832 (void)memcpy(&RecorderDataPtr->userEventBuffer.dataBuffer[0], data + slots, (count - slots) * 4);
\r
836 (void)memcpy(&RecorderDataPtr->userEventBuffer.dataBuffer[RecorderDataPtr->userEventBuffer.nextSlotToWrite * 4], data, count * 4);
\r
840 /*******************************************************************************
\r
841 * prvTraceUserEventHelper1
\r
843 * Calls on prvTraceUserEventFormat() to do the actual formatting, then goes on to the next helper function.
\r
844 ******************************************************************************/
\r
845 static void prvTraceUserEventHelper1(UserEventChannel channel, traceLabel eventLabel, traceLabel formatLabel, va_list vl)
\r
847 uint32_t data[(3 + MAX_ARG_SIZE) / 4];
\r
848 uint8_t byteOffset = 4; /* Need room for timestamp */
\r
853 /* We are dealing with an unknown channel format pair */
\r
854 byteOffset += 4; /* Also need room for channel and format */
\r
855 ((uint16_t*)data)[2] = eventLabel;
\r
856 ((uint16_t*)data)[3] = formatLabel;
\r
859 noOfSlots = prvTraceUserEventFormat((char*)&(RecorderDataPtr->SymbolTable.symbytes[formatLabel+4]), vl, (uint8_t*)data, byteOffset);
\r
861 prvTraceUserEventHelper2(channel, data, noOfSlots);
\r
864 /*******************************************************************************
\r
865 * prvTraceUserEventHelper2
\r
867 * This function simply copies the data buffer to the actual user event buffer.
\r
868 ******************************************************************************/
\r
869 static void prvTraceUserEventHelper2(UserEventChannel channel, uint32_t* data, uint32_t noOfSlots)
\r
871 static uint32_t old_timestamp = 0;
\r
872 uint32_t old_nextSlotToWrite = 0;
\r
874 TRACE_ASSERT(USER_EVENT_BUFFER_SIZE >= noOfSlots, "vTracePrintF: USER_EVENT_BUFFER_SIZE is too small to handle this event.", );
\r
876 trcCRITICAL_SECTION_BEGIN();
\r
877 /* Store the timestamp */
\r
878 vTracePortGetTimeStamp(data);
\r
880 if (*data < old_timestamp)
\r
881 RecorderDataPtr->userEventBuffer.wraparoundCounter++;
\r
882 old_timestamp = *data;
\r
884 /* Start by erasing any information in the channel buffer */
\r
885 prvTraceClearChannelBuffer(noOfSlots);
\r
887 prvTraceCopyToDataBuffer(data, noOfSlots); /* Will wrap around the data if necessary */
\r
889 old_nextSlotToWrite = RecorderDataPtr->userEventBuffer.nextSlotToWrite; /* Save the index that we want to write the channel data at when we're done */
\r
890 RecorderDataPtr->userEventBuffer.nextSlotToWrite = (RecorderDataPtr->userEventBuffer.nextSlotToWrite + noOfSlots) % USER_EVENT_BUFFER_SIZE; /* Make sure we never end up outside the buffer */
\r
892 /* Write to the channel buffer to indicate that this user event is ready to be used */
\r
894 RecorderDataPtr->userEventBuffer.channelBuffer[old_nextSlotToWrite] = channel;
\r
896 RecorderDataPtr->userEventBuffer.channelBuffer[old_nextSlotToWrite] = (UserEventChannel)0xFF; /* 0xFF indicates that this is not a normal channel id */
\r
897 trcCRITICAL_SECTION_END();
\r
900 /*******************************************************************************
\r
901 * xTraceRegisterChannelFormat
\r
903 * Attempts to create a pair of the channel and format string.
\r
905 * Note: This is only available if USE_SEPARATE_USER_EVENT_BUFFER is enabled in
\r
907 ******************************************************************************/
\r
908 UserEventChannel xTraceRegisterChannelFormat(traceLabel channel, traceLabel formatStr)
\r
911 UserEventChannel retVal = 0;
\r
913 TRACE_ASSERT(formatStr != 0, "vTraceRegisterChannelFormat: formatStr == 0", (UserEventChannel)0);
\r
915 trcCRITICAL_SECTION_BEGIN();
\r
916 for (i = 1; i <= CHANNEL_FORMAT_PAIRS; i++) /* Size of the channels buffer is CHANNEL_FORMAT_PAIRS + 1. Index 0 is unused. */
\r
918 if(RecorderDataPtr->userEventBuffer.channels[i].name == 0 && RecorderDataPtr->userEventBuffer.channels[i].defaultFormat == 0)
\r
920 /* Found empty slot */
\r
921 RecorderDataPtr->userEventBuffer.channels[i].name = channel;
\r
922 RecorderDataPtr->userEventBuffer.channels[i].defaultFormat = formatStr;
\r
923 retVal = (UserEventChannel)i;
\r
927 if (RecorderDataPtr->userEventBuffer.channels[i].name == channel && RecorderDataPtr->userEventBuffer.channels[i].defaultFormat == formatStr)
\r
929 /* Found a match */
\r
930 retVal = (UserEventChannel)i;
\r
934 trcCRITICAL_SECTION_END();
\r
938 /******************************************************************************
\r
939 * vTraceChannelPrintF
\r
941 * Slightly faster version of vTracePrintF() due to no lookups.
\r
943 * Note: This is only available if USE_SEPARATE_USER_EVENT_BUFFER is enabled in
\r
946 ******************************************************************************/
\r
947 void vTraceChannelPrintF(UserEventChannel channelPair, ...)
\r
951 va_start(vl, channelPair);
\r
952 vTraceChannelPrintF_Helper(channelPair, vl);
\r
956 void vTraceChannelPrintF_Helper(UserEventChannel channelPair, va_list vl)
\r
958 traceLabel channel;
\r
959 traceLabel formatStr;
\r
961 TRACE_ASSERT(channelPair != 0, "vTraceChannelPrintF: channelPair == 0", );
\r
962 TRACE_ASSERT(channelPair <= CHANNEL_FORMAT_PAIRS, "vTraceChannelPrintF: ", );
\r
964 channel = RecorderDataPtr->userEventBuffer.channels[channelPair].name;
\r
965 formatStr = RecorderDataPtr->userEventBuffer.channels[channelPair].defaultFormat;
\r
967 prvTraceUserEventHelper1(channelPair, channel, formatStr, vl);
\r
970 /******************************************************************************
\r
971 * vTraceChannelUserEvent
\r
973 * Slightly faster version of vTraceUserEvent() due to no lookups.
\r
974 ******************************************************************************/
\r
975 void vTraceChannelUserEvent(UserEventChannel channelPair)
\r
977 uint32_t data[(3 + MAX_ARG_SIZE) / 4];
\r
979 TRACE_ASSERT(channelPair != 0, "vTraceChannelPrintF: channelPair == 0", );
\r
980 TRACE_ASSERT(channelPair <= CHANNEL_FORMAT_PAIRS, "vTraceChannelPrintF: ", );
\r
982 prvTraceUserEventHelper2(channelPair, data, 1); /* Only need one slot for timestamp */
\r
984 #endif /* USE_SEPARATE_USER_EVENT_BUFFER == 1 */
\r
986 /******************************************************************************
\r
989 * Advanced user events (Professional Edition only)
\r
991 * Generates User Event with formatted text and data, similar to a "printf".
\r
992 * It is very fast compared to a normal "printf" since this function only
\r
993 * stores the arguments. The actual formatting is done
\r
994 * on the host PC when the trace is displayed in the viewer tool.
\r
996 * User Event labels are created using xTraceOpenLabel.
\r
999 * traceLabel adc_uechannel = xTraceOpenLabel("ADC User Events");
\r
1001 * vTracePrint(adc_uechannel,
\r
1002 * "ADC channel %d: %lf volts",
\r
1003 * ch, (double)adc_reading/(double)scale);
\r
1005 * This can be combined into one line, if desired, but this is slower:
\r
1007 * vTracePrint(xTraceOpenLabel("ADC User Events"),
\r
1008 * "ADC channel %d: %lf volts",
\r
1009 * ch, (double)adc_reading/(double)scale);
\r
1011 * Calling xTraceOpenLabel multiple times will not create duplicate entries, but
\r
1012 * it is of course faster to just do it once, and then keep the handle for later
\r
1013 * use. If you don´t have any data arguments, only a text label/string, it is
\r
1014 * better to use vTraceUserEvent - it is faster.
\r
1016 * Format specifiers supported:
\r
1017 * %d - 32 bit signed integer
\r
1018 * %u - 32 bit unsigned integer
\r
1019 * %f - 32 bit float
\r
1020 * %s - string (is copied to the recorder symbol table)
\r
1021 * %hd - 16 bit signed integer
\r
1022 * %hu - 16 bit unsigned integer
\r
1023 * %bd - 8 bit signed integer
\r
1024 * %bu - 8 bit unsigned integer
\r
1025 * %lf - double-precision float
\r
1027 * Up to 15 data arguments are allowed, with a total size of maximum 32 byte.
\r
1028 * In case this is exceeded, the user event is changed into an error message.
\r
1030 * The data is stored in trace buffer, and is packed to allow storing multiple
\r
1031 * smaller data entries in the same 4-byte record, e.g., four 8-bit values.
\r
1032 * A string requires two bytes, as the symbol table is limited to 64K. Storing a
\r
1033 * double (%lf) uses two records, so this is quite costly. Use float (%f) unless
\r
1034 * the higher precision is really necessary.
\r
1035 ******************************************************************************/
\r
1037 void vTracePrintF(traceLabel eventLabel, const char* formatStr, ...)
\r
1041 va_start(vl, formatStr);
\r
1042 vTracePrintF_Helper(eventLabel, formatStr, vl);
\r
1046 void vTracePrintF_Helper(traceLabel eventLabel, const char* formatStr, va_list vl)
\r
1048 #if (USE_SEPARATE_USER_EVENT_BUFFER == 0)
\r
1049 uint32_t noOfSlots;
\r
1051 uint32_t tempDataBuffer[(3 + MAX_ARG_SIZE) / 4];
\r
1053 /**************************************************************************
\r
1054 * The array tempDataBuffer is a local buffer used in a two-phase commit of
\r
1055 * the event data, since a vTracePrintF may span over multiple slots in the
\r
1057 * This buffer can be made larger, of course, but remember the risk for
\r
1058 * stack overflow. Note: This should be a LOCAL buffer, must not be made
\r
1059 * global. That would cause data corruption when two calls to vTracePrintF
\r
1060 * from different tasks overlaps (interrupts are only disabled in a small
\r
1061 * part of this function, otherwise enabled)
\r
1062 ***************************************************************************/
\r
1064 TRACE_ASSERT(formatStr != NULL, "vTracePrintF: formatStr == NULL", );
\r
1066 if (RecorderDataPtr->recorderActive && (! inExcludedTask || nISRactive) && handle_of_last_logged_task)
\r
1068 /* First, write the "primary" user event entry in the local buffer, but
\r
1069 let the event type be "EVENT_BEING_WRITTEN" for now...*/
\r
1071 ue1 = (UserEvent*)(&tempDataBuffer[0]);
\r
1072 ue1->type = EVENT_BEING_WRITTEN; /* Update this as the last step */
\r
1074 noOfSlots = prvTraceUserEventFormat(formatStr, vl, (uint8_t*)tempDataBuffer, 4);
\r
1076 /* Store the format string, with a reference to the channel symbol */
\r
1077 ue1->payload = prvTraceOpenSymbol(formatStr, eventLabel);
\r
1079 trcCRITICAL_SECTION_BEGIN();
\r
1081 ue1->dts = (uint8_t)prvTraceGetDTS(0xFF);
\r
1082 if (! RecorderDataPtr->recorderActive)
\r
1085 /* Abort, since an XTS event (created by prvTraceGetDTS) filled the
\r
1086 buffer, and the recorder stopped since not circular buffer. */
\r
1087 trcCRITICAL_SECTION_END();
\r
1092 /* If the data does not fit in the remaining main buffer, wrap around to
\r
1093 0 if allowed, otherwise stop the recorder and quit). */
\r
1094 if (RecorderDataPtr->nextFreeIndex + noOfSlots > RecorderDataPtr->maxEvents)
\r
1096 #if (TRACE_RECORDER_STORE_MODE == TRACE_STORE_MODE_RING_BUFFER)
\r
1097 (void)memset(& RecorderDataPtr->eventData[RecorderDataPtr->nextFreeIndex * 4],
\r
1099 (RecorderDataPtr->maxEvents - RecorderDataPtr->nextFreeIndex)*4);
\r
1100 RecorderDataPtr->nextFreeIndex = 0;
\r
1101 RecorderDataPtr->bufferIsFull = 1;
\r
1103 /* Abort and stop recorder, since the event data will not fit in the
\r
1104 buffer and not circular buffer in this case... */
\r
1105 trcCRITICAL_SECTION_END();
\r
1113 #if (TRACE_RECORDER_STORE_MODE == TRACE_STORE_MODE_RING_BUFFER)
\r
1114 /* Check that the buffer to be overwritten does not contain any user
\r
1115 events that would be partially overwritten. If so, they must be "killed"
\r
1116 by replacing the user event and following data with NULL events (i.e.,
\r
1117 using a memset to zero).*/
\r
1118 prvCheckDataToBeOverwrittenForMultiEntryEvents((uint8_t)noOfSlots);
\r
1120 /* Copy the local buffer to the main buffer */
\r
1121 (void)memcpy(& RecorderDataPtr->eventData[RecorderDataPtr->nextFreeIndex * 4],
\r
1125 /* Update the event type, i.e., number of data entries following the
\r
1126 main USER_EVENT entry (Note: important that this is after the memcpy,
\r
1127 but within the critical section!)*/
\r
1128 RecorderDataPtr->eventData[RecorderDataPtr->nextFreeIndex * 4] =
\r
1129 (uint8_t) ( USER_EVENT + noOfSlots - 1 );
\r
1131 /* Update the main buffer event index (already checked that it fits in
\r
1132 the buffer, so no need to check for wrapping)*/
\r
1134 RecorderDataPtr->nextFreeIndex += noOfSlots;
\r
1135 RecorderDataPtr->numEvents += noOfSlots;
\r
1139 if (RecorderDataPtr->nextFreeIndex >= EVENT_BUFFER_SIZE)
\r
1141 #if (TRACE_RECORDER_STORE_MODE == TRACE_STORE_MODE_RING_BUFFER)
\r
1142 /* We have reached the end, but this is a ring buffer. Start from the beginning again. */
\r
1143 RecorderDataPtr->bufferIsFull = 1;
\r
1144 RecorderDataPtr->nextFreeIndex = 0;
\r
1146 /* We have reached the end so we stop. */
\r
1151 #if (TRACE_RECORDER_STORE_MODE == TRACE_STORE_MODE_RING_BUFFER)
\r
1152 /* Make sure the next entry is cleared correctly */
\r
1153 prvCheckDataToBeOverwrittenForMultiEntryEvents(1);
\r
1156 #ifdef STOP_AFTER_N_EVENTS
\r
1157 #if (STOP_AFTER_N_EVENTS > -1)
\r
1158 /* Check if we have reached the desired number of events */
\r
1159 if (RecorderDataPtr->numEvents >= STOP_AFTER_N_EVENTS)
\r
1166 trcCRITICAL_SECTION_END();
\r
1169 #elif (USE_SEPARATE_USER_EVENT_BUFFER == 1)
\r
1170 /* Use the separate user event buffer */
\r
1171 traceLabel formatLabel;
\r
1172 UserEventChannel channel;
\r
1174 if (RecorderDataPtr->recorderActive && (! inExcludedTask || nISRactive) && handle_of_last_logged_task)
\r
1176 formatLabel = xTraceOpenLabel(formatStr);
\r
1178 channel = xTraceRegisterChannelFormat(eventLabel, formatLabel);
\r
1180 prvTraceUserEventHelper1(channel, eventLabel, formatLabel, vl);
\r
1185 /******************************************************************************
\r
1188 * Basic user event (Standard and Professional Edition only)
\r
1190 * Generates a User Event with a text label. The label is created/looked up
\r
1191 * in the symbol table using xTraceOpenLabel.
\r
1192 ******************************************************************************/
\r
1193 void vTraceUserEvent(traceLabel eventLabel)
\r
1195 #if (USE_SEPARATE_USER_EVENT_BUFFER == 0)
\r
1199 TRACE_ASSERT(eventLabel > 0, "vTraceUserEvent: Invalid value for eventLabel", );
\r
1201 if (RecorderDataPtr->recorderActive && (! inExcludedTask || nISRactive) && handle_of_last_logged_task)
\r
1203 trcCRITICAL_SECTION_BEGIN();
\r
1205 dts1 = (uint8_t)prvTraceGetDTS(0xFF);
\r
1207 if (RecorderDataPtr->recorderActive) /* Need to repeat this check! */
\r
1209 ue = (UserEvent*) xTraceNextFreeEventBufferSlot();
\r
1213 ue->type = USER_EVENT;
\r
1214 ue->payload = eventLabel;
\r
1215 prvTraceUpdateCounters();
\r
1218 trcCRITICAL_SECTION_END();
\r
1220 #elif (USE_SEPARATE_USER_EVENT_BUFFER == 1)
\r
1221 UserEventChannel channel;
\r
1222 uint32_t noOfSlots = 1;
\r
1223 uint32_t tempDataBuffer[(3 + MAX_ARG_SIZE) / 4];
\r
1225 if (RecorderDataPtr->recorderActive && (! inExcludedTask || nISRactive) && handle_of_last_logged_task)
\r
1227 channel = xTraceRegisterChannelFormat(0, eventLabel);
\r
1231 /* We are dealing with an unknown channel format pair */
\r
1232 noOfSlots++; /* Also need room for channel and format */
\r
1233 ((uint16_t*)tempDataBuffer)[2] = 0;
\r
1234 ((uint16_t*)tempDataBuffer)[3] = eventLabel;
\r
1237 prvTraceUserEventHelper2(channel, tempDataBuffer, noOfSlots);
\r
1242 /*******************************************************************************
\r
1245 * Creates user event labels for user event channels or for individual events.
\r
1246 * User events can be used to log application events and data for display in
\r
1247 * the visualization tool. A user event is identified by a label, i.e., a string,
\r
1248 * which is stored in the recorder's symbol table.
\r
1249 * When logging a user event, a numeric handle (reference) to this string is
\r
1250 * used to identify the event. This is obtained by calling
\r
1252 * xTraceOpenLabel()
\r
1254 * which adds the string to the symbol table (if not already present)
\r
1255 * and returns the corresponding handle.
\r
1257 * This can be used in two ways:
\r
1259 * 1. The handle is looked up every time, when storing the user event.
\r
1262 * vTraceUserEvent(xTraceOpenLabel("MyUserEvent"));
\r
1264 * 2. The label is registered just once, with the handle stored in an
\r
1265 * application variable - much like using a file handle.
\r
1268 * myEventHandle = xTraceOpenLabel("MyUserEvent");
\r
1270 * vTraceUserEvent(myEventHandle);
\r
1272 * The second option is faster since no lookup is required on each event, and
\r
1273 * therefore recommended for user events that are frequently
\r
1274 * executed and/or located in time-critical code. The lookup operation is
\r
1275 * however fairly fast due to the design of the symbol table.
\r
1276 ******************************************************************************/
\r
1277 traceLabel xTraceOpenLabel(const char* label)
\r
1279 TRACE_ASSERT(label != NULL, "xTraceOpenLabel: label == NULL", (traceLabel)0);
\r
1281 return prvTraceOpenSymbol(label, 0);
\r