1 /*******************************************************************************
\r
2 * FreeRTOS+Trace v2.3.0 Recorder Library
\r
3 * Percepio AB, www.percepio.com
\r
6 * The public API of the trace recorder library.
\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 trcPort.c and trcPort.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
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
33 * FreeRTOS+Trace is available as Free Edition and in two premium editions.
\r
34 * You may use the premium features during 30 days for evaluation.
\r
35 * Download FreeRTOS+Trace at http://www.percepio.com/products/downloads/
\r
37 * Copyright Percepio AB, 2012.
\r
39 ******************************************************************************/
\r
44 #include "FreeRTOS.h"
\r
46 #include "trcKernel.h"
\r
48 #if (configUSE_TRACE_FACILITY == 1)
\r
54 /*******************************************************************************
\r
57 * Starts the recorder. The recorder will not be started if an error has been
\r
58 * indicated using vTraceError, e.g. if any of the Nx constants in trcConfig.h
\r
59 * has a too small value (NTASK, NQUEUE, etc).
\r
61 * Returns 1 if the recorder was started successfully.
\r
62 * Returns 0 if the recorder start was prevented due to a previous internal
\r
63 * error. In that case, check vTraceGetLastError to get the error message.
\r
64 * Any error message is also presented when opening a trace file in
\r
65 * FreeRTOS+Trace v2.2.2 or later.
\r
66 ******************************************************************************/
\r
67 uint32_t uiTraceStart(void);
\r
69 /*******************************************************************************
\r
72 * Starts the recorder. The recorder will not be started if an error has been
\r
73 * indicated using vTraceError, e.g. if any of the Nx constants in trcConfig.h
\r
74 * has a too small value (NTASK, NQUEUE, etc).
\r
76 * This function is obsolete, but has been saved for backwards compatibility.
\r
77 * We recommend using uiTraceStart instead.
\r
78 ******************************************************************************/
\r
79 void vTraceStart(void);
\r
81 /*******************************************************************************
\r
82 * vTraceStartStatusMonitor
\r
84 * This starts a task to monitor the status of the recorder module.
\r
85 * This task periodically prints a line to the console window, which shows the
\r
86 * recorder status, the number of events recorded and the latest timestamp.
\r
87 * This task calls vTracePortEnd (trcPort.c) when it detects that the recorder
\r
88 * has been stopped. This allows for adding custom actions, e.g., to store the
\r
89 * trace to a file in case a file system is available on the device.
\r
90 ******************************************************************************/
\r
91 void vTraceStartStatusMonitor(void);
\r
93 /*******************************************************************************
\r
96 * Stops the recorder. The recording can be resumed by calling vTraceStart.
\r
97 * This does not reset the recorder. Use vTraceClear is that is desired.
\r
98 ******************************************************************************/
\r
99 void vTraceStop(void);
\r
101 /*******************************************************************************
\r
104 * Resets the recorder. Only necessary if a restart is desired - this is not
\r
105 * needed in the startup initialization.
\r
106 ******************************************************************************/
\r
107 void vTraceClear(void);
\r
109 /*******************************************************************************
\r
110 * vTraceSetQueueName
\r
112 * Assigns a name to a FreeRTOS Queue, Semaphore or Mutex. This function should
\r
113 * be called right after creation of the queue/mutex/semaphore. If not using
\r
114 * this function, the queues/mutexes/semaphores will be presented by their
\r
115 * numeric handle only.
\r
118 * actuatorQ = xQueueCreate(3, sizeof(QueueMessage));
\r
119 * vTraceSetQueueName(actuatorQ, "ActuatorQueue");
\r
120 ******************************************************************************/
\r
121 void vTraceSetQueueName(void* queue, const char* name);
\r
123 #if (INCLUDE_ISR_TRACING == 1)
\r
125 /*******************************************************************************
\r
126 * vTraceSetISRProperties
\r
128 * Registers an Interrupt Service Routine in the recorder library, This must be
\r
129 * called before using vTraceStoreISRBegin to store ISR events. This is
\r
130 * typically called in the startup of the system, before the scheduler is
\r
134 * #define ID_ISR_TIMER1 1 // lowest valid ID is 1
\r
135 * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt
\r
137 * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);
\r
139 * void ISR_handler()
\r
141 * portENTER_CRITICAL(); // Required if nested ISRs are allowed
\r
142 * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);
\r
143 * portEXIT_CRITICAL();
\r
145 * portENTER_CRITICAL(); // Required if nested ISRs are allowed
\r
146 * vTraceStoreISREnd();
\r
147 * portEXIT_CRITICAL();
\r
149 ******************************************************************************/
\r
150 void vTraceSetISRProperties(objectHandleType handle, const char* name, char priority);
\r
152 /*******************************************************************************
\r
153 * vTraceStoreISRBegin
\r
155 * Registers the beginning of an Interrupt Service Routine.
\r
157 * Note! This may only be used for interrupts affected by portENTER_CRITICAL.
\r
158 * In some FreeRTOS ports, such as ARM Cortex M3, this does not disable all
\r
159 * interrupts. Interrupts above configMAX_SYSCALL_INTERRUPT_PRIORITY are still
\r
160 * enabled, but may not call the FreeRTOS API. Such may not call the recorder
\r
161 * API, including this function.
\r
163 * See http://www.freertos.org/a00110.html
\r
165 * If allowing nested ISRs, this must be called with interrupts disabled.
\r
168 * #define ID_ISR_TIMER1 1 // lowest valid ID is 1
\r
169 * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt
\r
171 * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);
\r
173 * void ISR_handler()
\r
175 * portENTER_CRITICAL(); // Required if nested ISRs are allowed
\r
176 * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);
\r
177 * portEXIT_CRITICAL();
\r
179 * portENTER_CRITICAL(); // Required if nested ISRs are allowed
\r
180 * vTraceStoreISREnd();
\r
181 * portEXIT_CRITICAL();
\r
183 ******************************************************************************/
\r
184 void vTraceStoreISRBegin(objectHandleType id);
\r
186 /*******************************************************************************
\r
187 * vTraceStoreISREnd
\r
189 * Registers the end of an Interrupt Service Routine.
\r
191 * Note! This may only be used for interrupts affected by portENTER_CRITICAL.
\r
192 * In some FreeRTOS ports, such as ARM Cortex M3, this does not disable all
\r
193 * interrupts. Interrupts above configMAX_SYSCALL_INTERRUPT_PRIORITY are still
\r
194 * enabled, but may not call the FreeRTOS API. Such may not call the recorder
\r
195 * API, including this function.
\r
197 * See http://www.freertos.org/a00110.html
\r
199 * If allowing nested ISRs, this must be called with interrupts disabled.
\r
202 * #define ID_ISR_TIMER1 1 // lowest valid ID is 1
\r
203 * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt
\r
205 * vTraceSetISRProperties(ID_ISR_TIMER1, "ISRTimer1", PRIO_OF_ISR_TIMER1);
\r
207 * void ISR_handler()
\r
209 * portENTER_CRITICAL(); // Required if nested ISRs are allowed
\r
210 * vTraceStoreISRBegin(ID_OF_ISR_TIMER1);
\r
211 * portEXIT_CRITICAL();
\r
213 * portENTER_CRITICAL(); // Required if nested ISRs are allowed
\r
214 * vTraceStoreISREnd();
\r
215 * portEXIT_CRITICAL();
\r
217 ******************************************************************************/
\r
218 void vTraceStoreISREnd(void);
\r
221 /* If not including the ISR recording */
\r
223 void vTraceIncreaseISRActive(void);
\r
225 void vTraceDecreaseISRActive(void);
\r
227 #define vTraceSetISRProperties(handle, name, priority)
\r
228 #define vTraceStoreISRBegin(id) vTraceIncreaseISRActive()
\r
229 #define vTraceStoreISREnd() vTraceDecreaseISRActive()
\r
233 /*******************************************************************************
\r
234 * vvTraceTaskSkipDefaultInstanceFinishedEvents
\r
236 * This is useful if there are implicit Instance Finish Events, such as
\r
237 * vTaskDelayUntil or xQueueReceive, in a task where an explicit Instance Finish
\r
238 * Event has been defined. This function tells the recorder that only the
\r
239 * explicitly defined functions (using vTraceTaskInstanceIsFinished) should be
\r
240 * treated as Instance Finish Events for this task. The implicit Instance Finish
\r
241 * Events are thus disregarded for this task.
\r
242 ******************************************************************************/
\r
243 void vTraceTaskSkipDefaultInstanceFinishedEvents(void);
\r
245 /*******************************************************************************
\r
246 * vTraceTaskInstanceIsFinished
\r
248 * This defines an explicit Instance Finish Event for the current task. It tells
\r
249 * the recorder that the current instance of this task is finished at the next
\r
250 * kernel call of the task, e.g., a taskDelay or a queue receive. This function
\r
251 * should be called right before the api function call considered to be the end
\r
252 * of the task instamce, i.e., the Instance Finish Event.
\r
253 ******************************************************************************/
\r
254 void vTraceTaskInstanceIsFinished(void);
\r
256 /*******************************************************************************
\r
257 * vTraceGetTraceBuffer
\r
259 * Returns a pointer to the recorder data structure. Use this together with
\r
260 * uiTraceGetTraceBufferSize if you wish to implement an own store/upload
\r
261 * solution, e.g., in case a debugger connection is not available for uploading
\r
263 ******************************************************************************/
\r
264 void* vTraceGetTraceBuffer(void);
\r
266 /*******************************************************************************
\r
267 * uiTraceGetTraceBufferSize
\r
269 * Gets the size of the recorder data structure. For use together with
\r
270 * vTraceGetTraceBuffer if you wish to implement an own store/upload solution,
\r
271 * e.g., in case a debugger connection is not available for uploading the data.
\r
272 ******************************************************************************/
\r
273 uint32_t uiTraceGetTraceBufferSize(void);
\r
275 #if (INCLUDE_USER_EVENTS == 1)
\r
277 /*******************************************************************************
\r
280 * Creates user event labels for user event channels or for individual events.
\r
281 * User events can be used to log application events and data for display in
\r
282 * the visualization tool. A user event is identified by a label, i.e., a string,
\r
283 * which is stored in the recorder's symbol table.
\r
284 * When logging a user event, a numeric handle (reference) to this string is
\r
285 * used to identify the event. This is obtained by calling
\r
287 * xTraceOpenLabel()
\r
289 * whihc adds the string to the symbol table (if not already present)
\r
290 * and returns the corresponding handle.
\r
292 * This can be used in two ways:
\r
294 * 1. The handle is looked up every time, when storing the user event.
\r
297 * vTraceUserEvent(xTraceOpenLabel("MyUserEvent"));
\r
299 * 2. The label is registered just once, with the handle stored in an
\r
300 * application variable - much like using a file handle.
\r
303 * myEventHandle = xTraceOpenLabel("MyUserEvent");
\r
305 * vTraceUserEvent(myEventHandle);
\r
307 * The second option is faster since no lookup is required on each event, and
\r
308 * therefore recommended for user events that are frequently
\r
309 * executed and/or located in time-critical code. The lookup operation is
\r
310 * however fairly fast due to the design of the symbol table.
\r
311 ******************************************************************************/
\r
312 traceLabel xTraceOpenLabel(const char* label);
\r
314 /******************************************************************************
\r
317 * Basic user event (Standard and Professional Edition only)
\r
319 * Generates a User Event with a text label. The label is created/looked up
\r
320 * in the symbol table using xTraceOpenLabel.
\r
321 ******************************************************************************/
\r
322 void vTraceUserEvent(traceLabel eventLabel);
\r
324 /******************************************************************************
\r
327 * Advanced user events (Professional Edition only)
\r
329 * Generates User Event with formatted text and data, similar to a "printf".
\r
330 * It is very fast compared to a normal "printf" since this function only
\r
331 * stores the arguments. The actual formatting is done
\r
332 * on the host PC when the trace is displayed in the viewer tool.
\r
334 * User Event labels are created using xTraceOpenLabel.
\r
337 * traceLabel adc_uechannel = xTraceOpenLabel("ADC User Events");
\r
339 * vTracePrint(adc_uechannel,
\r
340 * "ADC channel %d: %lf volts",
\r
341 * ch, (double)adc_reading/(double)scale);
\r
343 * This can be combined into one line, if desired, but this is slower:
\r
345 * vTracePrint(xTraceOpenLabel("ADC User Events"),
\r
346 * "ADC channel %d: %lf volts",
\r
347 * ch, (double)adc_reading/(double)scale);
\r
349 * Calling xTraceOpenLabel multiple times will not create duplicate entries, but
\r
350 * it is of course faster to just do it once, and then keep the handle for later
\r
351 * use. If you don´t have any data arguments, only a text label/string, it is
\r
352 * better to use vTraceUserEvent - it is faster.
\r
354 * Format specifiers supported:
\r
355 * %d - 32 bit signed integer
\r
356 * %u - 32 bit unsigned integer
\r
357 * %f - 32 bit float
\r
358 * %s - string (is copied to the recorder symbol table)
\r
359 * %hd - 16 bit signed integer
\r
360 * %hu - 16 bit unsigned integer
\r
361 * %bd - 8 bit signed integer
\r
362 * %bu - 8 bit unsigned integer
\r
363 * %lf - double-precision float (Note! See below...)
\r
365 * Up to 15 data arguments are allowed, with a total size of maximum 32 byte.
\r
366 * In case this is exceeded, the user event is changed into an error message.
\r
368 * The data is stored in trace buffer, and is packed to allow storing multiple
\r
369 * smaller data entries in the same 4-byte record, e.g., four 8-bit values.
\r
370 * A string requires two bytes, as the symbol table is limited to 64K. Storing
\r
371 * a double (%lf) uses two records, so this is quite costly. Use float (%f)
\r
372 * unless the higher precision is really necessary.
\r
374 * Note that the double-precision float (%lf) assumes a 64 bit double
\r
375 * representation. This does not seem to be the case on e.g. PIC24F.
\r
376 * Before using a %lf argument on a 16-bit MCU, please verify that
\r
377 * "sizeof(double)" actually gives 8 as expected. If not, use %f instead.
\r
378 ******************************************************************************/
\r
379 void vTracePrintF(traceLabel eventLabel, const char* formatStr, ...);
\r
383 #define vTracePrintF(eventLabel, formatStr, ...);
\r
384 #define xTraceOpenLabel(label) 0
\r
385 #define vTraceUserEvent(eventLabel)
\r
389 /******************************************************************************
\r
390 * vTraceExclude______FromTrace
\r
392 * Excludes a task or object from the trace.
\r
393 * This can be useful if some irrelevant task is very frequent and is "eating
\r
394 * up the buffer". This should be called after the task has been created, but
\r
395 * before starting the FreeRTOS scheduler.
\r
396 *****************************************************************************/
\r
397 void vTraceExcludeQueueFromTrace(void* handle);
\r
398 void vTraceExcludeSemaphoreFromTrace(void* handle);
\r
399 void vTraceExcludeMutexFromTrace(void* handle);
\r
400 void vTraceExcludeTaskFromTrace(void* handle);
\r
401 void vTraceExcludeKernelServiceFromTrace(traceKernelService kernelService);
\r
403 /******************************************************************************
\r
404 * vTraceInclude______InTrace
\r
406 * Includes a task, object or kernel service in the trace. This is only
\r
407 * necessary if the task or object has been previously exluded.
\r
408 *****************************************************************************/
\r
409 void vTraceIncludeQueueInTrace(void* handle);
\r
410 void vTraceIncludeSemaphoreInTrace(void* handle);
\r
411 void vTraceIncludeMutexInTrace(void* handle);
\r
412 void vTraceIncludeTaskInTrace(void* handle);
\r
413 void vTraceIncludeKernelServiceInTrace(traceKernelService kernelService);
\r
421 #include "trcPort.h"
\r
423 #define vTraceInit()
\r
424 #define uiTraceStart() (1)
\r
425 #define vTraceStart()
\r
426 #define vTraceStop()
\r
427 #define vTraceClear()
\r
428 #define vTraceStartStatusMonitor()
\r
429 #define vTracePortSetOutFile(f)
\r
430 #define vTraceGetTraceBuffer() ((void*)0)
\r
431 #define uiTraceGetTraceBufferSize() 0
\r
432 #define xTraceOpenLabel(label) 0
\r
433 #define vTraceUserEvent(eventLabel)
\r
434 #define vTracePrintF(eventLabel,formatStr,...)
\r
435 #define vTraceExcludeTaskFromSchedulingTrace(name)
\r
436 #define vTraceSetQueueName(queue, name)
\r
438 #define vTraceTaskSkipDefaultInstanceFinishedEvents()
\r
439 #define vTraceSetISRProperties(handle, name, priority)
\r
440 #define vTraceStoreISRBegin(id)
\r
441 #define vTraceStoreISREnd()
\r
projects / freertos / blob