diff options
Diffstat (limited to 'FreeRTOS-Labs/Source/FreeRTOS-Plus-Trace/Include/trcRecorder.h')
| -rw-r--r-- | FreeRTOS-Labs/Source/FreeRTOS-Plus-Trace/Include/trcRecorder.h | 1789 |
1 files changed, 1789 insertions, 0 deletions
diff --git a/FreeRTOS-Labs/Source/FreeRTOS-Plus-Trace/Include/trcRecorder.h b/FreeRTOS-Labs/Source/FreeRTOS-Plus-Trace/Include/trcRecorder.h new file mode 100644 index 000000000..edcd5f0ae --- /dev/null +++ b/FreeRTOS-Labs/Source/FreeRTOS-Plus-Trace/Include/trcRecorder.h @@ -0,0 +1,1789 @@ +/*******************************************************************************
+ * Trace Recorder Library for Tracealyzer v4.1.5
+ * Percepio AB, www.percepio.com
+ *
+ * trcRecorder.h
+ *
+ * The public API of the trace recorder.
+ *
+ * Terms of Use
+ * This file is part of the trace recorder library (RECORDER), which is the
+ * intellectual property of Percepio AB (PERCEPIO) and provided under a
+ * license as follows.
+ * The RECORDER may be used free of charge for the purpose of recording data
+ * intended for analysis in PERCEPIO products. It may not be used or modified
+ * for other purposes without explicit permission from PERCEPIO.
+ * You may distribute the RECORDER in its original source code form, assuming
+ * this text (terms of use, disclaimer, copyright notice) is unchanged. You are
+ * allowed to distribute the RECORDER with minor modifications intended for
+ * configuration or porting of the RECORDER, e.g., to allow using it on a
+ * specific processor, processor family or with a specific communication
+ * interface. Any such modifications should be documented directly below
+ * this comment block.
+ *
+ * Disclaimer
+ * The RECORDER is being delivered to you AS IS and PERCEPIO makes no warranty
+ * as to its use or performance. PERCEPIO does not and cannot warrant the
+ * performance or results you may obtain by using the RECORDER or documentation.
+ * PERCEPIO make no warranties, express or implied, as to noninfringement of
+ * third party rights, merchantability, or fitness for any particular purpose.
+ * In no event will PERCEPIO, its technology partners, or distributors be liable
+ * to you for any consequential, incidental or special damages, including any
+ * lost profits or lost savings, even if a representative of PERCEPIO has been
+ * advised of the possibility of such damages, or for any claim by any third
+ * party. Some jurisdictions do not allow the exclusion or limitation of
+ * incidental, consequential or special damages, or the exclusion of implied
+ * warranties or limitations on how long an implied warranty may last, so the
+ * above limitations may not apply to you.
+ *
+ * Tabs are used for indent in this file (1 tab = 4 spaces)
+ *
+ * Copyright Percepio AB, 2018.
+ * www.percepio.com
+ ******************************************************************************/
+
+#ifndef TRC_RECORDER_H
+#define TRC_RECORDER_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+#include <stddef.h>
+
+#include "trcConfig.h"
+#include "trcPortDefines.h"
+
+
+#if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_SNAPSHOT)
+typedef uint16_t traceString;
+typedef uint8_t traceUBChannel;
+typedef uint8_t traceObjectClass;
+
+#if (TRC_CFG_USE_16BIT_OBJECT_HANDLES == 1)
+typedef uint16_t traceHandle;
+#else
+typedef uint8_t traceHandle;
+#endif
+
+#include "trcHardwarePort.h"
+#include "trcKernelPort.h"
+
+// Not available in snapshot mode
+#define vTraceConsoleChannelPrintF(fmt, ...)
+
+#endif
+
+#if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)
+
+typedef const char* traceString;
+typedef const void* traceHandle;
+
+#include "trcHardwarePort.h"
+#include "trcStreamingPort.h"
+#include "trcKernelPort.h"
+
+#endif
+
+#if (TRC_USE_TRACEALYZER_RECORDER == 1)
+
+/* The user event channel for recorder warnings, must be defined in trcKernelPort.c */
+extern traceString trcWarningChannel;
+
+#define TRACE_GET_LOW16(value) ((uint16_t)((value) & 0x0000FFFF))
+#define TRACE_GET_HIGH16(value) ((uint16_t)(((value) >> 16) & 0x0000FFFF))
+#define TRACE_SET_LOW16(current, value) (((current) & 0xFFFF0000) | (value))
+#define TRACE_SET_HIGH16(current, value) (((current) & 0x0000FFFF) | (((uint32_t)(value)) << 16))
+
+/******************************************************************************/
+/*** Common API - both Snapshot and Streaming mode ****************************/
+/******************************************************************************/
+
+/******************************************************************************
+* vTraceEnable(int startOption);
+*
+* Initializes and optionally starts the trace, depending on the start option.
+* To use the trace recorder, the startup must call vTraceEnable before any RTOS
+* calls are made (including "create" calls). Three start options are provided:
+*
+* TRC_START: Starts the tracing directly. In snapshot mode this allows for
+* starting the trace at any point in your code, assuming vTraceEnable(TRC_INIT)
+* has been called in the startup.
+* Can also be used for streaming without Tracealyzer control, e.g. to a local
+* flash file system (assuming such a "stream port", see trcStreamingPort.h).
+*
+* TRC_START_AWAIT_HOST: For streaming mode only. Initializes the trace recorder
+* if necessary and waits for a Start command from Tracealyzer ("Start Recording"
+* button). This call is intentionally blocking! By calling vTraceEnable with
+* this option from the startup code, you start tracing at this point and capture
+* the early events.
+*
+* TRC_INIT: Initializes the trace recorder, but does not start the tracing.
+* In snapshot mode, this must be followed by a vTraceEnable(TRC_START) sometime
+* later.
+*
+* Usage examples:
+*
+* Snapshot trace, from startup:
+* <board init>
+* vTraceEnable(TRC_START);
+* <RTOS init>
+*
+* Snapshot trace, from a later point:
+* <board init>
+* vTraceEnable(TRC_INIT);
+* <RTOS init>
+* ...
+* vTraceEnable(TRC_START); // e.g., in task context, at some relevant event
+*
+* Streaming trace, from startup:
+* <board init>
+* vTraceEnable(TRC_START_AWAIT_HOST); // Blocks!
+* <RTOS init>
+*
+* Streaming trace, from a later point:
+* <board startup>
+* vTraceEnable(TRC_INIT);
+* <RTOS startup>
+*
+******************************************************************************/
+void vTraceEnable(int startOption);
+
+/******************************************************************************
+ * vTracePrintF
+ *
+ * Generates "User Events", with formatted text and data, similar to a "printf".
+ * User Events can be used for very efficient logging from your application code.
+ * It is very fast since the actual string formatting is done on the host side,
+ * when the trace is displayed. The execution time is just some microseconds on
+ * a 32-bit MCU.
+ *
+ * User Events are shown as yellow labels in the main trace view of $PNAME.
+ *
+ * An advantage of User Events is that data can be plotted in the "User Event
+ * Signal Plot" view, visualizing any data you log as User Events, discrete
+ * states or control system signals (e.g. system inputs or outputs).
+ *
+ * You may group User Events into User Event Channels. The yellow User Event
+ * labels show the logged string, preceded by the channel name within brackets.
+ *
+ * Example:
+ *
+ * "[MyChannel] Hello World!"
+ *
+ * The User Event Channels are shown in the View Filter, which makes it easy to
+ * select what User Events you wish to display. User Event Channels are created
+ * using xTraceRegisterString().
+ *
+ * Example:
+ *
+ * traceString adc_uechannel = xTraceRegisterString("ADC User Events");
+ * ...
+ * vTracePrintF(adc_uechannel,
+ * "ADC channel %d: %d volts",
+ * ch, adc_reading);
+ *
+ * The following format specifiers are supported in both modes:
+ * %d - signed integer.
+ * %u - unsigned integer.
+ * %X - hexadecimal, uppercase.
+ * %x - hexadecimal, lowercase.
+ * %s - string (see comment below)
+ *
+ * For integer formats (%d, %u, %x, %X) you may also use width and padding.
+ * If using -42 as data argument, two examples are:
+ * "%05d" -> "-0042"
+ * "%5d" -> " -42".
+ *
+ * String arguments are supported in both snapshot and streaming, but in streaming
+ * mode you need to use xTraceRegisterString and use the returned traceString as
+ * the argument. In snapshot you simply provide a char* as argument.
+ *
+ * Snapshot: vTracePrintF(myChn, "my string: %s", str);
+ * Streaming: vTracePrintF(myChn, "my string: %s", xTraceRegisterString(str));
+ *
+ * In snapshot mode you can specify 8-bit or 16-bit arguments to reduce RAM usage:
+ * %hd -> 16 bit (h) signed integer (d).
+ * %bu -> 8 bit (b) unsigned integer (u).
+ *
+ * However, in streaming mode all data arguments are assumed to be 32 bit wide.
+ * Width specifiers (e.g. %hd) are accepted but ignored (%hd treated like %d).
+ *
+ * The maximum event size also differs between the modes. In streaming this is
+ * limited by a maximum payload size of 52 bytes, including format string and
+ * data arguments. So if using one data argument, the format string is limited
+ * to 48 byte, etc. If this is exceeded, the format string is truncated and you
+ * get a warning in Tracealyzer.
+ *
+ * In snapshot mode you are limited to maximum 15 arguments, that must not exceed
+ * 32 bytes in total (not counting the format string). If exceeded, the recorder
+ * logs an internal error (displayed when opening the trace) and stops recording.
+ ******************************************************************************/
+#if (TRC_CFG_SCHEDULING_ONLY == 0) && (TRC_CFG_INCLUDE_USER_EVENTS == 1)
+void vTracePrintF(traceString chn, const char* fmt, ...);
+#else
+#define vTracePrintF(chn, ...) (void)chn
+#endif
+
+ /******************************************************************************
+* vTracePrint
+*
+* A faster version of vTracePrintF, that only allows for logging a string.
+*
+* Example:
+*
+* traceString chn = xTraceRegisterString("MyChannel");
+* ...
+* vTracePrint(chn, "Hello World!");
+******************************************************************************/
+#if (TRC_CFG_SCHEDULING_ONLY == 0) && (TRC_CFG_INCLUDE_USER_EVENTS == 1)
+void vTracePrint(traceString chn, const char* str);
+#else
+#define vTracePrint(chn, ...) (void)chn
+#endif
+
+
+/*******************************************************************************
+* vTraceConsoleChannelPrintF
+*
+* Wrapper for vTracePrint, using the default channel. Can be used as a drop-in
+* replacement for printf and similar functions, e.g. in a debug logging macro.
+*
+* Example:
+*
+* // Old: #define LogString debug_console_printf
+*
+* // New, log to Tracealyzer instead:
+* #define LogString vTraceConsoleChannelPrintF
+* ...
+* LogString("My value is: %d", myValue);
+******************************************************************************/
+#if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)
+void vTraceConsoleChannelPrintF(const char* fmt, ...);
+#endif
+
+/*******************************************************************************
+* xTraceRegisterString
+*
+* Register strings in the recorder, e.g. for names of user event channels.
+*
+* Example:
+* myEventHandle = xTraceRegisterString("MyUserEvent");
+* ...
+* vTracePrintF(myEventHandle, "My value is: %d", myValue);
+******************************************************************************/
+#if (TRC_CFG_SCHEDULING_ONLY == 0) && (TRC_CFG_INCLUDE_USER_EVENTS == 1)
+traceString xTraceRegisterString(const char* name);
+#else
+#define xTraceRegisterString(x) (x)
+#endif
+
+/*******************************************************************************
+ * vTraceSet...Name(void* object, const char* name)
+ *
+ * Parameter object: pointer to the kernel object that shall be named
+ * Parameter name: the name to set
+ *
+ * Kernel-specific functions for setting names of kernel objects, for display in
+ * Tracealyzer.
+ ******************************************************************************/
+/* See trcKernelPort.h for details (kernel-specific) */
+
+/*******************************************************************************
+ * xTraceSetISRProperties
+ *
+ * Stores a name and priority level for an Interrupt Service Routine, to allow
+ * for better visualization. Returns a traceHandle used by vTraceStoreISRBegin.
+ *
+ * Example:
+ * #define PRIO_ISR_TIMER1 3 // the hardware priority of the interrupt
+ * ...
+ * traceHandle Timer1Handle = xTraceSetISRProperties("ISRTimer1", PRIO_ISR_TIMER1);
+ * ...
+ * void ISR_handler()
+ * {
+ * vTraceStoreISRBegin(Timer1Handle);
+ * ...
+ * vTraceStoreISREnd(0);
+ * }
+ ******************************************************************************/
+traceHandle xTraceSetISRProperties(const char* name, uint8_t priority);
+
+/*******************************************************************************
+ * vTraceStoreISRBegin
+ *
+ * Registers the beginning of an Interrupt Service Routine, using a traceHandle
+ * provided by xTraceSetISRProperties.
+ *
+ * Example:
+ * #define PRIO_ISR_TIMER1 3 // the hardware priority of the interrupt
+ * ...
+ * traceHandle Timer1Handle = xTraceSetISRProperties("ISRTimer1", PRIO_ISR_TIMER1);
+ * ...
+ * void ISR_handler()
+ * {
+ * vTraceStoreISRBegin(Timer1Handle);
+ * ...
+ * vTraceStoreISREnd(0);
+ * }
+ ******************************************************************************/
+void vTraceStoreISRBegin(traceHandle handle);
+
+/*******************************************************************************
+ * vTraceStoreISREnd
+ *
+ * Registers the end of an Interrupt Service Routine.
+ *
+ * The parameter pendingISR indicates if the interrupt has requested a
+ * task-switch (= 1), e.g., by signaling a semaphore. Otherwise (= 0) the
+ * interrupt is assumed to return to the previous context.
+ *
+ * Example:
+ * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt
+ * traceHandle traceHandleIsrTimer1 = 0; // The ID set by the recorder
+ * ...
+ * traceHandleIsrTimer1 = xTraceSetISRProperties("ISRTimer1", PRIO_OF_ISR_TIMER1);
+ * ...
+ * void ISR_handler()
+ * {
+ * vTraceStoreISRBegin(traceHandleIsrTimer1);
+ * ...
+ * vTraceStoreISREnd(0);
+ * }
+ ******************************************************************************/
+void vTraceStoreISREnd(int isTaskSwitchRequired);
+
+/*******************************************************************************
+ * vTraceInstanceFinishNow
+ *
+ * Creates an event that ends the current task instance at this very instant.
+ * This makes the viewer to splits the current fragment at this point and begin
+ * a new actor instance, even if no task-switch has occurred.
+ *****************************************************************************/
+void vTraceInstanceFinishedNow(void);
+
+/*******************************************************************************
+ * vTraceInstanceFinishedNext
+ *
+ * Marks the current "task instance" as finished on the next kernel call.
+ *
+ * If that kernel call is blocking, the instance ends after the blocking event
+ * and the corresponding return event is then the start of the next instance.
+ * If the kernel call is not blocking, the viewer instead splits the current
+ * fragment right before the kernel call, which makes this call the first event
+ * of the next instance.
+ *****************************************************************************/
+void vTraceInstanceFinishedNext(void);
+
+/*******************************************************************************
+ * xTraceGetLastError
+ *
+ * Returns the last error or warning as a string, or NULL if none.
+ *****************************************************************************/
+const char* xTraceGetLastError(void);
+
+/*******************************************************************************
+ * vTraceClearError
+ *
+ * Clears any errors.
+ *****************************************************************************/
+void vTraceClearError(void);
+
+/*******************************************************************************
+* vTraceStop
+*
+* Stops the recording. Intended for snapshot mode or if streaming without
+* Tracealyzer control (e.g., to a device file system).
+******************************************************************************/
+void vTraceStop(void);
+
+/******************************************************************************
+* vTraceSetFrequency
+*
+* Registers the clock rate of the time source for the event timestamping.
+* This is normally not required, but if the default value (TRC_HWTC_FREQ_HZ)
+* should be incorrect for your setup, you can override it using this function.
+*
+* Must be called prior to vTraceEnable, and the time source is assumed to
+* have a fixed clock frequency after the startup.
+*
+* Note that, in snapshot mode, the value is divided by the TRC_HWTC_DIVISOR.
+* This is a software "prescaler" that is also applied on the timestamps.
+*****************************************************************************/
+void vTraceSetFrequency(uint32_t frequency);
+
+/*******************************************************************************
+* vTraceSetRecorderDataBuffer
+*
+* The trcConfig.h setting TRC_CFG_RECORDER_BUFFER_ALLOCATION allows for selecting
+* custom allocation (TRC_RECORDER_BUFFER_ALLOCATION_CUSTOM), which allows you to
+* control where the recorder trace buffer is allocated.
+*
+* When custom allocation is selected, use TRC_ALLOC_CUSTOM_BUFFER to make the
+* allocation (in global context) and then call vTraceSetRecorderDataBuffer to
+* register the allocated buffer. This supports both snapshot and streaming,
+* and has no effect if using other allocation modes than CUSTOM.
+*
+* NOTE: vTraceSetRecorderDataBuffer must be called before vTraceEnable.
+******************************************************************************/
+#if (TRC_CFG_RECORDER_BUFFER_ALLOCATION == TRC_RECORDER_BUFFER_ALLOCATION_CUSTOM)
+void vTraceSetRecorderDataBuffer(void* pRecorderData);
+#else
+#define vTraceSetRecorderDataBuffer(pRecorderData)
+#endif
+
+
+/*******************************************************************************
+* TRC_ALLOC_CUSTOM_BUFFER
+*
+* If using custom allocation of the trace buffer (i.e., your trcConfig.h has the
+* setting TRC_RECORDER_BUFFER_ALLOCATION_CUSTOM), this macro allows you to declare
+* the trace buffer in a portable way that works both in snapshot and streaming.
+*
+* This macro has no effect if using another allocation mode, so you can easily
+* switch between different recording modes and configurations, using the same
+* initialization code.
+*
+* This translates to a single static allocation, on which you can apply linker
+* directives to place it in a particular memory region.
+*
+* - Snapshot mode: "RecorderDataType <name>"
+*
+* - Streaming mode: "char <name> [<size>]",
+* where <size> is defined in trcStreamingConfig.h.
+*
+* Example:
+*
+* // GCC example: place myTraceBuffer in section .tz, defined in the .ld file.
+* TRC_ALLOC_CUSTOM_BUFFER(myTraceBuffer) __attribute__((section(".tz")));
+*
+* int main(void)
+* {
+* ...
+* vTraceSetRecorderDataBuffer(&myTraceBuffer); // Note the "&"
+* ...
+* vTraceEnable(TRC_INIT); // Initialize the data structure
+******************************************************************************/
+#if (TRC_CFG_RECORDER_BUFFER_ALLOCATION == TRC_RECORDER_BUFFER_ALLOCATION_CUSTOM)
+ #if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_SNAPSHOT)
+ #define TRC_ALLOC_CUSTOM_BUFFER(bufname) RecorderDataType bufname;
+ #elif (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)
+ #ifdef TRC_CFG_RTT_BUFFER_SIZE_UP /* J-Link RTT */
+ #define TRC_ALLOC_CUSTOM_BUFFER(bufname) char bufname [TRC_CFG_RTT_BUFFER_SIZE_UP]; /* Not static in this case, since declared in user code */
+ #else
+ #define TRC_ALLOC_CUSTOM_BUFFER(bufname) char bufname [(TRC_CFG_PAGED_EVENT_BUFFER_PAGE_COUNT) * (TRC_CFG_PAGED_EVENT_BUFFER_PAGE_SIZE)];
+ #endif
+ #endif
+#else
+ #define TRC_ALLOC_CUSTOM_BUFFER(bufname)
+#endif
+
+/******************************************************************************
+* xTraceIsRecordingEnabled
+*
+* Returns true (1) if the recorder is enabled (i.e. is recording), otherwise 0.
+******************************************************************************/
+int xTraceIsRecordingEnabled(void);
+
+/*******************************************************************************
+* vTraceSetFilterGroup
+*
+* Sets the "filter group" to assign when creating RTOS objects, such as tasks,
+* queues, semaphores and mutexes. This together with vTraceSetFilterMask
+* allows you to control what events that are recorded, based on the
+* objects they refer to.
+*
+* There are 16 filter groups named FilterGroup0 .. FilterGroup15.
+*
+* Note: We don't recommend filtering out the Idle task, so make sure to call
+* vTraceSetFilterGroup just before initializing the RTOS, in order to assign
+* such "default" objects to the right Filter Group (typically group 0).
+*
+* Example:
+*
+* // Assign tasks T1 to FilterGroup0 (default)
+* <Create Task T1>
+*
+* // Assign Q1 and Q2 to FilterGroup1
+* vTraceSetFilterGroup(FilterGroup1);
+* <Create Queue Q1>
+* <Create Queue Q2>
+*
+* // Assigns Q3 to FilterGroup2
+* vTraceSetFilterGroup(FilterGroup2);
+* <Create Queue Q3>
+*
+* // Only include FilterGroup0 and FilterGroup2, exclude FilterGroup1 (Q1 and Q2) from the trace
+* vTraceSetFilterMask( FilterGroup0 | FilterGroup2 );
+*
+* // Assign the default RTOS objects (e.g. Idle task) to FilterGroup0
+* vTraceSetFilterGroup(FilterGroup0);
+* <Start the RTOS scheduler>
+*
+* Note that you may define your own names for the filter groups using
+* preprocessor definitions, to make the code easier to understand.
+*
+* Example:
+*
+* #define BASE FilterGroup0
+* #define USB_EVENTS FilterGroup1
+* #define CAN_EVENTS FilterGroup2
+*
+* Note that filtering per event type (regardless of object) is also available
+* in trcConfig.h.
+******************************************************************************/
+void vTraceSetFilterGroup(uint16_t filterGroup);
+
+/******************************************************************************
+* vTraceSetFilterMask
+*
+* Sets the "filter mask" that is used to filter the events by object. This can
+* be used to reduce the trace data rate, i.e., if your streaming interface is
+* a bottleneck or if you want longer snapshot traces without increasing the
+* buffer size.
+*
+* Note: There are two kinds of filters in the recorder. The other filter type
+* excludes all events of certain kinds (e.g., OS ticks). See trcConfig.h.
+*
+* The filtering is based on bitwise AND with the Filter Group ID, assigned
+* to RTOS objects such as tasks, queues, semaphores and mutexes.
+* This together with vTraceSetFilterGroup allows you to control what
+* events that are recorded, based on the objects they refer to.
+*
+* See example for vTraceSetFilterGroup.
+******************************************************************************/
+void vTraceSetFilterMask(uint16_t filterMask);
+
+#if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_SNAPSHOT)
+
+/******************************************************************************/
+/*** Extended API for Snapshot mode *******************************************/
+/******************************************************************************/
+
+/******************************************************************************
+* TRACE_STOP_HOOK - Hook Pointer Data Type
+*
+* Declares a data type for a call back function that will be invoked whenever
+* the recorder is stopped.
+*
+* Snapshot mode only!
+******************************************************************************/
+typedef void(*TRACE_STOP_HOOK)(void);
+
+/*******************************************************************************
+* vTraceStopHookPtr
+*
+* Points to a call back function that is called from vTraceStop().
+*
+* Snapshot mode only!
+******************************************************************************/
+extern TRACE_STOP_HOOK vTraceStopHookPtr;
+
+/*******************************************************************************
+* vTraceSetStopHook
+*
+* Sets a function to be called when the recorder is stopped.
+*
+* Snapshot mode only!
+******************************************************************************/
+void vTraceSetStopHook(TRACE_STOP_HOOK stopHookFunction);
+
+/*******************************************************************************
+* uiTraceStart
+*
+* [DEPRECATED] Use vTraceEnable instead.
+*
+* Starts the recorder. The recorder will not be started if an error has been
+* indicated using prvTraceError, e.g. if any of the Nx constants in
+* trcSnapshotConfig.h has a too small value (TRC_CFG_NTASK, TRC_CFG_NQUEUE, etc).
+*
+* Returns 1 if the recorder was started successfully.
+* Returns 0 if the recorder start was prevented due to a previous internal
+* error. In that case, check xTraceGetLastError to get the error message.
+* Any error message is also presented when opening a trace file.
+*
+* Snapshot mode only!
+******************************************************************************/
+uint32_t uiTraceStart(void);
+
+/*******************************************************************************
+* vTraceStart
+*
+* [DEPRECATED] Use vTraceEnable instead.
+*
+* Starts the recorder. The recorder will not be started if an error has been
+* indicated using prvTraceError, e.g. if any of the Nx constants in
+* trcSnapshotConfig.h has a too small value (TRC_CFG_NTASK, TRC_CFG_NQUEUE, etc).
+*
+* Snapshot mode only!
+******************************************************************************/
+void vTraceStart(void);
+
+/*******************************************************************************
+* vTraceClear
+*
+* Resets the recorder. Only necessary if a restart is desired - this is not
+* needed in the startup initialization.
+*
+* Snapshot mode only!
+******************************************************************************/
+void vTraceClear(void);
+
+
+/*****************************************************************************/
+/*** INTERNAL SNAPSHOT FUNCTIONS *********************************************/
+/*****************************************************************************/
+
+#define TRC_UNUSED
+
+#ifndef TRC_CFG_INCLUDE_OBJECT_DELETE
+#define TRC_CFG_INCLUDE_OBJECT_DELETE 0
+#endif
+
+#ifndef TRC_CFG_INCLUDE_READY_EVENTS
+#define TRC_CFG_INCLUDE_READY_EVENTS 1
+#endif
+
+#ifndef TRC_CFG_INCLUDE_OSTICK_EVENTS
+#define TRC_CFG_INCLUDE_OSTICK_EVENTS 0
+#endif
+
+/* This macro will create a task in the object table */
+#undef trcKERNEL_HOOKS_TASK_CREATE
+#define trcKERNEL_HOOKS_TASK_CREATE(SERVICE, CLASS, pxTCB) \
+ TRACE_SET_OBJECT_NUMBER(TASK, pxTCB); \
+ TRACE_SET_OBJECT_FILTER(TASK, pxTCB, CurrentFilterGroup); \
+ prvTraceSetObjectName(TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB), TRACE_GET_TASK_NAME(pxTCB)); \
+ prvTraceSetPriorityProperty(TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB), TRACE_GET_TASK_PRIORITY(pxTCB)); \
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, pxTCB) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB));
+
+/* This macro will remove the task and store it in the event buffer */
+#undef trcKERNEL_HOOKS_TASK_DELETE
+#define trcKERNEL_HOOKS_TASK_DELETE(SERVICE, SERVICE_NAME, SERVICE_PROP, pxTCB) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, pxTCB) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB)); \
+ prvTraceStoreObjectNameOnCloseEvent(SERVICE_NAME, TRACE_GET_TASK_NUMBER(pxTCB), TRACE_CLASS_TASK); \
+ prvTraceStoreObjectPropertiesOnCloseEvent(SERVICE_PROP, TRACE_GET_TASK_NUMBER(pxTCB), TRACE_CLASS_TASK); \
+ prvTraceSetPriorityProperty(TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB), TRACE_GET_TASK_PRIORITY(pxTCB)); \
+ prvTraceSetObjectState(TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB), TASK_STATE_INSTANCE_NOT_ACTIVE); \
+ prvTraceFreeObjectHandle(TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB));
+
+
+/* This macro will setup a task in the object table */
+#undef trcKERNEL_HOOKS_OBJECT_CREATE
+#define trcKERNEL_HOOKS_OBJECT_CREATE(SERVICE, CLASS, pxObject)\
+ TRACE_SET_OBJECT_NUMBER(CLASS, pxObject);\
+ TRACE_SET_OBJECT_FILTER(CLASS, pxObject, CurrentFilterGroup); \
+ prvMarkObjectAsUsed(TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject));\
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ if (TRACE_GET_OBJECT_FILTER(CLASS, pxObject) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject)); \
+ prvTraceSetObjectState(TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject), 0);
+
+/* This macro will remove the object and store it in the event buffer */
+#undef trcKERNEL_HOOKS_OBJECT_DELETE
+#define trcKERNEL_HOOKS_OBJECT_DELETE(SERVICE, SERVICE_NAME, SERVICE_PROP, CLASS, pxObject) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ if (TRACE_GET_OBJECT_FILTER(CLASS, pxObject) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject)); \
+ prvTraceStoreObjectNameOnCloseEvent(SERVICE_NAME, TRACE_GET_OBJECT_NUMBER(CLASS, pxObject), TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject)); \
+ prvTraceStoreObjectPropertiesOnCloseEvent(SERVICE_PROP, TRACE_GET_OBJECT_NUMBER(CLASS, pxObject), TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject)); \
+ prvTraceFreeObjectHandle(TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject));
+
+/* This macro will create a call to a kernel service with a certain result, with an object as parameter */
+#undef trcKERNEL_HOOKS_KERNEL_SERVICE
+#define trcKERNEL_HOOKS_KERNEL_SERVICE(SERVICE, CLASS, pxObject) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ if (TRACE_GET_OBJECT_FILTER(CLASS, pxObject) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject));
+
+/* This macro will create a call to a kernel service with a certain result, with a null object as parameter */
+#undef trcKERNEL_HOOKS_KERNEL_SERVICE_NULL_OBJECT
+#define trcKERNEL_HOOKS_KERNEL_SERVICE_NULL_OBJECT(SERVICE, TRACECLASS) \
+ if (TRACE_GET_TASK_FILTER(TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACECLASS, 0);
+
+/* This macro will create a call to a kernel service with a certain result, with an object as parameter */
+#undef trcKERNEL_HOOKS_KERNEL_SERVICE_WITH_PARAM
+#define trcKERNEL_HOOKS_KERNEL_SERVICE_WITH_PARAM(SERVICE, CLASS, pxObject, param) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ if (TRACE_GET_OBJECT_FILTER(CLASS, pxObject) & CurrentFilterMask) \
+ prvTraceStoreKernelCallWithParam(SERVICE, TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject), (uint32_t)param);
+
+/* This macro will create a call to a kernel service with a certain result, with a null object and other value as parameter */
+#undef trcKERNEL_HOOKS_KERNEL_SERVICE_NULL_OBJECT_WITH_PARAM
+#define trcKERNEL_HOOKS_KERNEL_SERVICE_NULL_OBJECT_WITH_PARAM(SERVICE, TRACECLASS, param) \
+ if (TRACE_GET_TASK_FILTER(TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ prvTraceStoreKernelCallWithParam(SERVICE, TRACECLASS, 0, param);
+
+/* This macro will create a call to a kernel service with a certain result, with an object as parameter */
+#undef trcKERNEL_HOOKS_KERNEL_SERVICE_WITH_NUMERIC_PARAM_ONLY
+#define trcKERNEL_HOOKS_KERNEL_SERVICE_WITH_NUMERIC_PARAM_ONLY(SERVICE, param) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ prvTraceStoreKernelCallWithNumericParamOnly(SERVICE, (uint32_t)param);
+
+/* This macro will create a call to a kernel service with a certain result, with an object as parameter */
+#undef trcKERNEL_HOOKS_KERNEL_SERVICE_FROM_ISR
+#define trcKERNEL_HOOKS_KERNEL_SERVICE_FROM_ISR(SERVICE, CLASS, pxObject) \
+ if (TRACE_GET_OBJECT_FILTER(CLASS, pxObject) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject));
+
+/* This macro will create a call to a kernel service with a certain result, with an object as parameter */
+#undef trcKERNEL_HOOKS_KERNEL_SERVICE_WITH_PARAM_FROM_ISR
+#define trcKERNEL_HOOKS_KERNEL_SERVICE_WITH_PARAM_FROM_ISR(SERVICE, CLASS, pxObject, param) \
+ if (TRACE_GET_OBJECT_FILTER(CLASS, pxObject) & CurrentFilterMask) \
+ prvTraceStoreKernelCallWithParam(SERVICE, TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject), (uint32_t)param);
+
+/* This macro will create a call to a kernel service with a certain result, with an object as parameter */
+#undef trcKERNEL_HOOKS_KERNEL_SERVICE_WITH_NUMERIC_PARAM_ONLY_FROM_ISR
+#define trcKERNEL_HOOKS_KERNEL_SERVICE_WITH_NUMERIC_PARAM_ONLY_FROM_ISR(SERVICE, param) \
+ prvTraceStoreKernelCallWithNumericParamOnly(SERVICE, (uint32_t)param);
+
+/* This macro will set the state for an object */
+#undef trcKERNEL_HOOKS_SET_OBJECT_STATE
+#define trcKERNEL_HOOKS_SET_OBJECT_STATE(CLASS, pxObject, STATE) \
+ prvTraceSetObjectState(TRACE_GET_OBJECT_TRACE_CLASS(CLASS, pxObject), TRACE_GET_OBJECT_NUMBER(CLASS, pxObject), (uint8_t)STATE);
+
+/* This macro will flag a certain task as a finished instance */
+#undef trcKERNEL_HOOKS_SET_TASK_INSTANCE_FINISHED
+#define trcKERNEL_HOOKS_SET_TASK_INSTANCE_FINISHED() \
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ prvTraceSetTaskInstanceFinished(TRACE_GET_TASK_NUMBER(TRACE_GET_CURRENT_TASK()));
+
+#if (TRC_CFG_INCLUDE_READY_EVENTS == 1)
+/* This macro will create an event to indicate that a task became Ready */
+#undef trcKERNEL_HOOKS_MOVED_TASK_TO_READY_STATE
+#define trcKERNEL_HOOKS_MOVED_TASK_TO_READY_STATE(pxTCB) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, pxTCB) & CurrentFilterMask) \
+ prvTraceStoreTaskReady(TRACE_GET_TASK_NUMBER(pxTCB));
+#else /*(TRC_CFG_INCLUDE_READY_EVENTS == 1)*/
+#undef trcKERNEL_HOOKS_MOVED_TASK_TO_READY_STATE
+#define trcKERNEL_HOOKS_MOVED_TASK_TO_READY_STATE(pxTCB)
+#endif /*(TRC_CFG_INCLUDE_READY_EVENTS == 1)*/
+
+/* This macro will update the internal tick counter and call prvTracePortGetTimeStamp(0) to update the internal counters */
+#undef trcKERNEL_HOOKS_INCREMENT_TICK
+#define trcKERNEL_HOOKS_INCREMENT_TICK() \
+ { \
+ extern uint32_t uiTraceTickCount; \
+ uiTraceTickCount++; \
+ prvTracePortGetTimeStamp(0); \
+ }
+
+#if (TRC_CFG_INCLUDE_OSTICK_EVENTS == 1)
+/* This macro will create an event indicating that the OS tick count has increased */
+#undef trcKERNEL_HOOKS_NEW_TIME
+#define trcKERNEL_HOOKS_NEW_TIME(SERVICE, xValue) \
+ prvTraceStoreKernelCallWithNumericParamOnly(SERVICE, xValue);
+#else /*(TRC_CFG_INCLUDE_OSTICK_EVENTS == 1)*/
+#undef trcKERNEL_HOOKS_NEW_TIME
+#define trcKERNEL_HOOKS_NEW_TIME(SERVICE, xValue)
+#endif /*(TRC_CFG_INCLUDE_OSTICK_EVENTS == 1)*/
+
+/* This macro will create a task switch event to the currently executing task */
+#undef trcKERNEL_HOOKS_TASK_SWITCH
+#define trcKERNEL_HOOKS_TASK_SWITCH( pxTCB ) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, pxTCB) & CurrentFilterMask) \
+ prvTraceStoreTaskswitch(TRACE_GET_TASK_NUMBER(pxTCB));
+
+/* This macro will create an event to indicate that the task has been suspended */
+#undef trcKERNEL_HOOKS_TASK_SUSPEND
+#define trcKERNEL_HOOKS_TASK_SUSPEND(SERVICE, pxTCB) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, pxTCB) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB)); \
+ prvTraceSetTaskInstanceFinished((uint8_t)TRACE_GET_TASK_NUMBER(pxTCB));
+
+/* This macro will create an event to indicate that a task has called a wait/delay function */
+#undef trcKERNEL_HOOKS_TASK_DELAY
+#define trcKERNEL_HOOKS_TASK_DELAY(SERVICE, pxTCB, xValue) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, pxTCB) & CurrentFilterMask) \
+ { \
+ prvTraceStoreKernelCallWithNumericParamOnly(SERVICE, xValue); \
+ prvTraceSetTaskInstanceFinished((uint8_t)TRACE_GET_TASK_NUMBER(pxTCB)); \
+ }
+
+/* This macro will create an event to indicate that a task has gotten its priority changed */
+#undef trcKERNEL_HOOKS_TASK_PRIORITY_CHANGE
+#define trcKERNEL_HOOKS_TASK_PRIORITY_CHANGE(SERVICE, pxTCB, uxNewPriority) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, pxTCB) & CurrentFilterMask) \
+ { \
+ prvTraceStoreKernelCallWithParam(SERVICE, TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB), prvTraceGetPriorityProperty(TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB)));\
+ prvTraceSetPriorityProperty(TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB), (uint8_t)uxNewPriority); \
+ }
+
+/* This macro will create an event to indicate that the task has been resumed */
+#undef trcKERNEL_HOOKS_TASK_RESUME
+#define trcKERNEL_HOOKS_TASK_RESUME(SERVICE, pxTCB) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, TRACE_GET_CURRENT_TASK()) & CurrentFilterMask) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, pxTCB) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB));
+
+#undef trcKERNEL_HOOKS_TASK_RESUME_FROM_ISR
+#define trcKERNEL_HOOKS_TASK_RESUME_FROM_ISR(SERVICE, pxTCB) \
+ if (TRACE_GET_OBJECT_FILTER(TASK, pxTCB) & CurrentFilterMask) \
+ prvTraceStoreKernelCall(SERVICE, TRACE_CLASS_TASK, TRACE_GET_TASK_NUMBER(pxTCB));
+
+#if !defined TRC_CFG_INCLUDE_READY_EVENTS || TRC_CFG_INCLUDE_READY_EVENTS == 1
+ void prvTraceSetReadyEventsEnabled(int status);
+ void prvTraceStoreTaskReady(traceHandle handle);
+#else
+ #define prvTraceSetReadyEventsEnabled(status)
+#endif
+
+void prvTraceStoreLowPower(uint32_t flag);
+
+void prvTraceStoreTaskswitch(traceHandle task_handle);
+
+
+#if (TRC_CFG_SCHEDULING_ONLY == 0)
+
+void prvTraceStoreKernelCall(uint32_t eventcode, traceObjectClass objectClass, uint32_t byteParam);
+
+void prvTraceStoreKernelCallWithNumericParamOnly(uint32_t evtcode, uint32_t param);
+
+void prvTraceStoreKernelCallWithParam(uint32_t evtcode, traceObjectClass objectClass,
+ uint32_t objectNumber, uint32_t param);
+#else
+
+#define prvTraceStoreKernelCall(eventcode, objectClass, byteParam) {}
+#define prvTraceStoreKernelCallWithNumericParamOnly(evtcode, param) {}
+#define prvTraceStoreKernelCallWithParam(evtcode, objectClass, objectNumber, param) {}
+
+#endif
+
+void prvTraceSetTaskInstanceFinished(traceHandle handle);
+
+void prvTraceSetPriorityProperty(uint8_t objectclass, traceHandle id, uint8_t value);
+
+uint8_t prvTraceGetPriorityProperty(uint8_t objectclass, traceHandle id);
+
+void prvTraceSetObjectState(uint8_t objectclass, traceHandle id, uint8_t value);
+
+void prvMarkObjectAsUsed(traceObjectClass objectclass, traceHandle handle);
+
+void prvTraceStoreObjectNameOnCloseEvent(uint8_t evtcode, traceHandle handle,
+ traceObjectClass objectclass);
+
+void prvTraceStoreObjectPropertiesOnCloseEvent(uint8_t evtcode, traceHandle handle,
+ traceObjectClass objectclass);
+
+/* Internal constants for task state */
+#define TASK_STATE_INSTANCE_NOT_ACTIVE 0
+#define TASK_STATE_INSTANCE_ACTIVE 1
+
+
+#if (TRC_CFG_INCLUDE_ISR_TRACING == 0)
+
+#undef vTraceSetISRProperties
+#define vTraceSetISRProperties(handle, name, priority)
+
+#undef vTraceStoreISRBegin
+#define vTraceStoreISRBegin(x) (void)x
+
+#undef vTraceStoreISREnd
+#define vTraceStoreISREnd(x) (void)x
+
+#undef xTraceSetISRProperties
+#define xTraceSetISRProperties(name, priority) 0
+
+#endif /*(TRC_CFG_INCLUDE_ISR_TRACING == 0)*/
+
+/*******************************************************************************
+ * xTraceGetTraceBuffer
+ *
+ * Returns a pointer to the recorder data structure. Use this together with
+ * uiTraceGetTraceBufferSize if you wish to implement an own store/upload
+ * solution, e.g., in case a debugger connection is not available for uploading
+ * the data.
+ ******************************************************************************/
+void* xTraceGetTraceBuffer(void);
+
+/*******************************************************************************
+ * uiTraceGetTraceBufferSize
+ *
+ * Gets the size of the recorder data structure. For use together with
+ * vTraceGetTraceBuffer if you wish to implement an own store/upload solution,
+ * e.g., in case a debugger connection is not available for uploading the data.
+ ******************************************************************************/
+uint32_t uiTraceGetTraceBufferSize(void);
+
+#if (TRC_CFG_SCHEDULING_ONLY == 1)
+#undef TRC_CFG_INCLUDE_USER_EVENTS
+#define TRC_CFG_INCLUDE_USER_EVENTS 0
+#endif /*(TRC_CFG_SCHEDULING_ONLY == 1)*/
+
+#if ((TRC_CFG_INCLUDE_USER_EVENTS == 1) && (TRC_CFG_SCHEDULING_ONLY == 0))
+
+#if (TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER == 1)
+traceUBChannel xTraceRegisterUBChannel(traceString channel, traceString formatStr);
+void vTraceUBData(traceUBChannel channel, ...);
+void vTraceUBEvent(traceUBChannel channel);
+#endif /*(TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER == 1)*/
+
+#else /*((TRC_CFG_INCLUDE_USER_EVENTS == 1) && (TRC_CFG_SCHEDULING_ONLY == 0))*/
+
+#undef vTracePrint
+#define vTracePrint(chn, ...) (void)chn
+#undef vTracePrintF
+#define vTracePrintF(chn, ...) (void)chn
+#undef xTraceRegisterString
+#define xTraceRegisterString(x) 0; (void)x;
+#undef xTraceRegisterChannelFormat
+#define xTraceRegisterChannelFormat(eventLabel, formatStr) 0
+#undef vTraceUBData
+#define vTraceUBData(label, ...) {}
+#undef vTraceChannelPrint
+#define vTraceChannelPrint(label) {}
+
+#endif /*(TRC_CFG_INCLUDE_USER_EVENTS == 1)*/
+
+#define NEventCodes 0x100
+
+/* Our local critical sections for the recorder */
+#define trcCRITICAL_SECTION_BEGIN() {TRACE_ENTER_CRITICAL_SECTION(); recorder_busy++;}
+#define trcCRITICAL_SECTION_END() {recorder_busy--; TRACE_EXIT_CRITICAL_SECTION();}
+
+#if (TRC_CFG_HARDWARE_PORT == TRC_HARDWARE_PORT_ARM_Cortex_M)
+ #define trcSR_ALLOC_CRITICAL_SECTION_ON_CORTEX_M_ONLY TRACE_ALLOC_CRITICAL_SECTION
+ #define trcCRITICAL_SECTION_BEGIN_ON_CORTEX_M_ONLY trcCRITICAL_SECTION_BEGIN
+ #define trcCRITICAL_SECTION_END_ON_CORTEX_M_ONLY trcCRITICAL_SECTION_END
+#else
+ #define trcSR_ALLOC_CRITICAL_SECTION_ON_CORTEX_M_ONLY() {}
+ #define trcCRITICAL_SECTION_BEGIN_ON_CORTEX_M_ONLY() recorder_busy++;
+ #define trcCRITICAL_SECTION_END_ON_CORTEX_M_ONLY() recorder_busy--;
+#endif
+
+/******************************************************************************
+ * ObjectHandleStack
+ * This data-structure is used to provide a mechanism for 1-byte trace object
+ * handles. This way, only 1 byte is necessary instead of 4 bytes (a pointer)
+ * when storing a reference to an object. This allows for up to 255 objects of
+ * each object class active at any given moment. There can be more "historic"
+ * objects, that have been deleted - that number is only limited by the size of
+ * the symbol table.
+ *
+ * Note that handle zero (0) is not used, it is a code for an invalid handle.
+ *
+ * This data structure keeps track of the FREE handles, not the handles in use.
+ * This data structure contains one stack per object class. When a handle is
+ * allocated to an object, the next free handle is popped from the stack. When
+ * a handle is released (on object delete), it is pushed back on the stack.
+ * Note that there is no initialization code that pushed the free handles
+ * initially, that is not necessary due to the following optimization:
+ *
+ * The stack of handles (objectHandles) is initially all zeros. Since zero
+ * is not a valid handle, that is a signal of additional handles needed.
+ * If a zero is received when popping a new handle, it is replaced by the
+ * index of the popped handle instead.
+ *****************************************************************************/
+typedef struct
+{
+ /* For each object class, the index of the next handle to allocate */
+ uint16_t indexOfNextAvailableHandle[ TRACE_NCLASSES ];
+
+ /* The lowest index of this class (constant) */
+ uint16_t lowestIndexOfClass[ TRACE_NCLASSES ];
+
+ /* The highest index of this class (constant) */
+ uint16_t highestIndexOfClass[ TRACE_NCLASSES ];
+
+ /* The highest use count for this class (for statistics) */
+ uint16_t handleCountWaterMarksOfClass[ TRACE_NCLASSES ];
+
+ /* The free object handles - a set of stacks within this array */
+ traceHandle objectHandles[ TRACE_KERNEL_OBJECT_COUNT ];
+
+} objectHandleStackType;
+
+extern objectHandleStackType objectHandleStacks;
+
+/******************************************************************************
+ * Object Property Table
+ * The Object Table contains name and other properties of the objects (tasks,
+ * queues, mutexes, etc). The below data structures defines the properties of
+ * each object class and are used to cast the byte buffer into a cleaner format.
+ *
+ * The values in the object table are continuously overwritten and always
+ * represent the current state. If a property is changed during runtime, the OLD
+ * value should be stored in the trace buffer, not the new value (since the new
+ * value is found in the Object Property Table).
+ *
+ * For close events this mechanism is the old names are stored in the symbol
+ * table), for "priority set" (the old priority is stored in the event data)
+ * and for "isActive", where the value decides if the task switch event type
+ * should be "new" or "resume".
+ ******************************************************************************/
+
+typedef struct
+{
+ /* = NCLASSES */
+ uint32_t NumberOfObjectClasses;
+
+ uint32_t ObjectPropertyTableSizeInBytes;
+
+ /* This is used to calculate the index in the dynamic object table
+ (handle - 1 - nofStaticObjects = index)*/
+#if (TRC_CFG_USE_16BIT_OBJECT_HANDLES == 1)
+ traceHandle NumberOfObjectsPerClass[2*((TRACE_NCLASSES+1)/2)];
+#else
+ traceHandle NumberOfObjectsPerClass[4*((TRACE_NCLASSES+3)/4)];
+#endif
+
+ /* Allocation size rounded up to the closest multiple of 4 */
+ uint8_t NameLengthPerClass[ 4*((TRACE_NCLASSES+3)/4) ];
+
+ uint8_t TotalPropertyBytesPerClass[ 4*((TRACE_NCLASSES+3)/4) ];
+
+ /* Allocation size rounded up to the closest multiple of 2 */
+ uint16_t StartIndexOfClass[ 2*((TRACE_NCLASSES+1)/2) ];
+
+ /* The actual handles issued, should be Initiated to all zeros */
+ uint8_t objbytes[ 4*((TRACE_OBJECT_TABLE_SIZE+3)/4) ];
+} ObjectPropertyTableType;
+
+/* Symbol table data structure */
+typedef struct
+{
+ /* = SYMBOL_HISTORY_TABLE_SIZE_IN_BYTES */
+ uint32_t symTableSize;
+
+ /* Entry 0 is reserved. Any reference to entry 0 implies NULL*/
+ uint32_t nextFreeSymbolIndex;
+
+ /* Size rounded up to closest multiple of 4, to avoid alignment issues*/
+ uint8_t symbytes[4*(((TRC_CFG_SYMBOL_TABLE_SIZE)+3)/4)];
+
+ /* Used for lookups - Up to 64 linked lists within the symbol table
+ connecting all entries with the same 6 bit checksum.
+ This field holds the current list heads. Should be initiated to zeros */
+ uint16_t latestEntryOfChecksum[64];
+} symbolTableType;
+
+
+/*******************************************************************************
+ * The data structures of the different events, all 4 bytes long
+ ******************************************************************************/
+
+typedef struct
+{
+ uint8_t type;
+ uint8_t objHandle;
+ uint16_t dts; /* differential timestamp - time since last event */
+} TSEvent, TREvent;
+
+typedef struct
+{
+ uint8_t type;
+ uint8_t dummy;
+ uint16_t dts; /* differential timestamp - time since last event */
+} LPEvent;
+
+typedef struct
+{
+ uint8_t type;
+ uint8_t objHandle;
+ uint16_t dts; /* differential timestamp - time since last event */
+} KernelCall;
+
+typedef struct
+{
+ uint8_t type;
+ uint8_t objHandle;
+ uint8_t param;
+ uint8_t dts; /* differential timestamp - time since last event */
+} KernelCallWithParamAndHandle;
+
+typedef struct
+{
+ uint8_t type;
+ uint8_t dts; /* differential timestamp - time since last event */
+ uint16_t param;
+} KernelCallWithParam16;
+
+typedef struct
+{
+ uint8_t type;
+ uint8_t objHandle; /* the handle of the closed object */
+ uint16_t symbolIndex; /* the name of the closed object */
+} ObjCloseNameEvent;
+
+typedef struct
+{
+ uint8_t type;
+ uint8_t arg1;
+ uint8_t arg2;
+ uint8_t arg3;
+} ObjClosePropEvent;
+
+typedef struct
+{
+ uint8_t type;
+ uint8_t unused1;
+ uint8_t unused2;
+ uint8_t dts;
+} TaskInstanceStatusEvent;
+
+typedef struct
+{
+ uint8_t type;
+ uint8_t dts;
+ uint16_t payload; /* the name of the user event */
+} UserEvent;
+
+typedef struct
+{
+ uint8_t type;
+
+ /* 8 bits extra for storing DTS, if it does not fit in ordinary event
+ (this one is always MSB if used) */
+ uint8_t xts_8;
+
+ /* 16 bits extra for storing DTS, if it does not fit in ordinary event. */
+ uint16_t xts_16;
+} XTSEvent;
+
+typedef struct
+{
+ uint8_t type;
+
+ uint8_t xps_8;
+ uint16_t xps_16;
+} XPSEvent;
+
+typedef struct{
+ uint8_t type;
+ uint8_t dts;
+ uint16_t size;
+} MemEventSize;
+
+typedef struct{
+ uint8_t type;
+ uint8_t addr_high;
+ uint16_t addr_low;
+} MemEventAddr;
+
+/*******************************************************************************
+ * The separate user event buffer structure. Can be enabled in trcConfig.h.
+ ******************************************************************************/
+
+#if (TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER == 1)
+typedef struct
+{
+ traceString name;
+ traceString defaultFormat;
+} ChannelFormatPair;
+
+typedef struct
+{
+ uint16_t bufferID;
+ uint16_t version;
+ uint32_t wraparoundCounter;
+ uint32_t numberOfSlots;
+ uint32_t nextSlotToWrite;
+ uint8_t numberOfChannels;
+ uint8_t padding1;
+ uint8_t padding2;
+ uint8_t padding3;
+ ChannelFormatPair channels[(TRC_CFG_UB_CHANNELS)+1];
+ uint8_t channelBuffer[((TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE) + 3) & 0xFFFFFFFC]; /* 1 byte per slot, with padding for 4 byte alignment */
+ uint8_t dataBuffer[(TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE) * 4]; /* 4 bytes per slot */
+
+} UserEventBuffer;
+#endif
+
+/*******************************************************************************
+ * The main data structure, read by Tracealyzer from the RAM dump
+ ******************************************************************************/
+
+typedef struct
+{
+ volatile uint8_t startmarker0; /* Volatile is important, see init code. */
+ volatile uint8_t startmarker1;
+ volatile uint8_t startmarker2;
+ volatile uint8_t startmarker3;
+ volatile uint8_t startmarker4;
+ volatile uint8_t startmarker5;
+ volatile uint8_t startmarker6;
+ volatile uint8_t startmarker7;
+ volatile uint8_t startmarker8;
+ volatile uint8_t startmarker9;
+ volatile uint8_t startmarker10;
+ volatile uint8_t startmarker11;
+
+ /* Used to determine Kernel and Endianess */
+ uint16_t version;
+
+ /* Currently 5 */
+ uint8_t minor_version;
+
+ /* This should be 0 if lower IRQ priority values implies higher priority
+ levels, such as on ARM Cortex M. If the opposite scheme is used, i.e.,
+ if higher IRQ priority values means higher priority, this should be 1. */
+ uint8_t irq_priority_order;
+
+ /* sizeof(RecorderDataType) - just for control */
+ uint32_t filesize;
+
+ /* Current number of events recorded */
+ uint32_t numEvents;
+
+ /* The buffer size, in number of event records */
+ uint32_t maxEvents;
+
+ /* The event buffer index, where to write the next event */
+ uint32_t nextFreeIndex;
+
+ /* 1 if the buffer is full, 0 otherwise */
+ uint32_t bufferIsFull;
+
+ /* The frequency of the clock/timer/counter used as time base */
+ uint32_t frequency;
+
+ /* The absolute timestamp of the last stored event, in the native
+ timebase, modulo frequency! */
+ uint32_t absTimeLastEvent;
+
+ /* The number of seconds in total - lasts for 136 years */
+ uint32_t absTimeLastEventSecond;
+
+ /* 1 if the recorder has been started, 0 if not yet started or stopped.
+ This is a 32 bit variable due to alignment issues. */
+ uint32_t recorderActive;
+
+ /* If > 0, tells the maximum time between two traced ISRs that execute
+ back-to-back. If the time between vTraceStoreISREnd and a directly
+ following vTraceISRBegin is above isrTailchainingThreshold, we assume a
+ return to the previous context in between the ISRs, otherwise we assume
+ the have executed back-to-back and don't show any fragment of the previous
+ context in between. */
+ uint32_t isrTailchainingThreshold;
+
+ /* Not used, remains for compatibility and future use */
+ uint8_t notused[24];
+
+ /* The amount of heap memory remaining at the last malloc or free event */
+ uint32_t heapMemUsage;
+
+ /* 0xF0F0F0F0 - for control only */
+ int32_t debugMarker0;
+
+ /* Set to value of TRC_CFG_USE_16BIT_OBJECT_HANDLES */
+ uint32_t isUsing16bitHandles;
+
+ /* The Object Property Table holds information about currently active
+ tasks, queues, and other recorded objects. This is updated on each
+ create call and includes object name and other properties. */
+ ObjectPropertyTableType ObjectPropertyTable;
+
+ /* 0xF1F1F1F1 - for control only */
+ int32_t debugMarker1;
+
+ /* The Symbol Table stores strings for User Events and is also used to
+ store names of deleted objects, which still may be in the trace but no
+ longer are available. */
+ symbolTableType SymbolTable;
+
+ /* For inclusion of float support, and for endian detection of floats.
+ The value should be (float)1 or (uint32_t)0 */
+#if (TRC_CFG_INCLUDE_FLOAT_SUPPORT == 1)
+ float exampleFloatEncoding;
+#else
+ uint32_t exampleFloatEncoding;
+#endif
+ /* This is non-zero if an internal error occurred in the recorder, e.g., if
+ one of the Nxxx constants was too small. The systemInfo string will then
+ contain an error message that is displayed when attempting to view the
+ trace file. */
+ uint32_t internalErrorOccured;
+
+ /* 0xF2F2F2F2 - for control only */
+ int32_t debugMarker2;
+
+ /* Error messages from the recorder. */
+ char systemInfo[80];
+
+ /* 0xF3F3F3F3 - for control only */
+ int32_t debugMarker3;
+
+ /* The event data, in 4-byte records */
+ uint8_t eventData[ (TRC_CFG_EVENT_BUFFER_SIZE) * 4 ];
+
+#if (TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER == 1)
+ UserEventBuffer userEventBuffer;
+#endif
+
+ /* This should always be 0 */
+ uint32_t endOfSecondaryBlocks;
+
+ uint8_t endmarker0;
+ uint8_t endmarker1;
+ uint8_t endmarker2;
+ uint8_t endmarker3;
+ uint8_t endmarker4;
+ uint8_t endmarker5;
+ uint8_t endmarker6;
+ uint8_t endmarker7;
+ uint8_t endmarker8;
+ uint8_t endmarker9;
+ uint8_t endmarker10;
+ uint8_t endmarker11;
+} RecorderDataType;
+
+extern RecorderDataType* RecorderDataPtr;
+
+/* Internal functions */
+
+/* Signal an error. */
+void prvTraceError(const char* msg);
+
+/*******************************************************************************
+ * prvTracePortGetTimeStamp
+ *
+ * Returns the current time based on the HWTC macros which provide a hardware
+ * isolation layer towards the hardware timer/counter.
+ *
+ * The HWTC macros and prvTracePortGetTimeStamp is the main porting issue
+ * or the trace recorder library. Typically you should not need to change
+ * the code of prvTracePortGetTimeStamp if using the HWTC macros.
+ *
+ ******************************************************************************/
+void prvTracePortGetTimeStamp(uint32_t *puiTimestamp);
+
+traceHandle prvTraceGetObjectHandle(traceObjectClass objectclass);
+
+void prvTraceFreeObjectHandle(traceObjectClass objectclass,
+ traceHandle handle);
+
+/* Private function. Use the public functions in trcKernelPort.h */
+void prvTraceSetObjectName(traceObjectClass objectclass,
+ traceHandle handle,
+ const char* name);
+
+/* Internal macros */
+
+#define TRACE_PROPERTY_NAME_GET(objectclass, objecthandle) \
+(const char*)(& RecorderDataPtr->ObjectPropertyTable.objbytes \
+[uiIndexOfObject(objecthandle, objectclass)])
+
+#define TRACE_PROPERTY_OBJECT_STATE(objectclass, handle) \
+RecorderDataPtr->ObjectPropertyTable.objbytes[uiIndexOfObject(handle, objectclass) \
++ RecorderDataPtr->ObjectPropertyTable.NameLengthPerClass[objectclass]]
+
+#define TRACE_PROPERTY_ACTOR_PRIORITY(objectclass, handle) \
+RecorderDataPtr->ObjectPropertyTable.objbytes[uiIndexOfObject(handle, objectclass) \
++ RecorderDataPtr->ObjectPropertyTable.NameLengthPerClass[objectclass] + 1]
+
+/* DEBUG ASSERTS */
+#if defined TRC_CFG_USE_TRACE_ASSERT && TRC_CFG_USE_TRACE_ASSERT != 0
+#define TRACE_ASSERT(eval, msg, defRetVal) \
+if (!(eval)) \
+{ \
+ prvTraceError("TRACE_ASSERT: " msg); \
+ return defRetVal; \
+}
+#else
+#define TRACE_ASSERT(eval, msg, defRetVal)
+#endif
+
+#endif /*(TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_SNAPSHOT)*/
+
+#if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)
+
+/******************************************************************************
+ * Default values for STREAM PORT macros
+ *
+ * As a normal user, this is nothing you don't need to bother about. This is
+ * only important if you want to define your own custom streaming interface.
+ *
+ * You may override these in your own trcStreamingPort.h to create a custom
+ * stream port, and thereby stream the trace on any host-target interface.
+ * These default values are suitable for most cases, except the J-Link port.
+ ******************************************************************************/
+
+/******************************************************************************
+ * TRC_STREAM_PORT_USE_INTERNAL_BUFFER
+ *
+ * There are two kinds of stream ports, those that store the event to the
+ * internal buffer (with periodic flushing by the TzCtrl task) and those that
+ * write directly to the streaming interface. Most stream ports use the
+ * recorder's internal buffer, except for the SEGGER J-Link port (also uses a
+ * RAM buffer, but one defined in the SEGGER code).
+ *
+ * If the stream port (trcStreamingPort.h) defines this as zero (0), it is
+ * expected to transmit the data directly using TRC_STREAM_PORT_COMMIT_EVENT.
+ * Otherwise it is expected that the trace data is stored in the internal buffer
+ * and the TzCtrl task will then send the buffer pages when they become full.
+ ******************************************************************************/
+#ifndef TRC_STREAM_PORT_USE_INTERNAL_BUFFER
+#define TRC_STREAM_PORT_USE_INTERNAL_BUFFER 1
+#endif
+
+ /******************************************************************************
+ * TRC_STREAM_PORT_ON_TRACE_BEGIN
+ *
+ * Defining any actions needed in the stream port when the recording is activated.
+ *******************************************************************************/
+#ifndef TRC_STREAM_PORT_ON_TRACE_BEGIN
+ #define TRC_STREAM_PORT_ON_TRACE_BEGIN() /* Do nothing */
+#endif
+
+ /******************************************************************************
+ * TRC_STREAM_PORT_ON_TRACE_BEGIN
+ *
+ * Defining any actions needed in the stream port when the tracing stops.
+ * Empty by default.
+ *******************************************************************************/
+#ifndef TRC_STREAM_PORT_ON_TRACE_END
+#define TRC_STREAM_PORT_ON_TRACE_END() /* Do nothing */
+#endif
+
+ /******************************************************************************
+ * TRC_STREAM_PORT_ALLOCATE_EVENT
+ *
+ * This macro is used to allocate memory for each event record, just before
+ * assigning the record fields.
+ * Depending on "TRC_STREAM_PORT_USE_INTERNAL_BUFFER", this either allocates
+ * space in the paged event buffer, or on the local stack. In the latter case,
+ * the COMMIT event is used to write the data to the streaming interface.
+ ******************************************************************************/
+#ifndef TRC_STREAM_PORT_ALLOCATE_EVENT
+#if (TRC_STREAM_PORT_USE_INTERNAL_BUFFER == 1)
+ #define TRC_STREAM_PORT_ALLOCATE_EVENT(_type, _ptrData, _size) _type* _ptrData; _ptrData = (_type*)prvPagedEventBufferGetWritePointer(_size);
+#else
+ #define TRC_STREAM_PORT_ALLOCATE_EVENT(_type, _ptrData, _size) _type _tmpArray[_size / sizeof(_type)]; _type* _ptrData = _tmpArray;
+#endif
+#endif
+
+ /******************************************************************************
+ * TRC_STREAM_PORT_ALLOCATE_DYNAMIC_EVENT
+ *
+ * This macro is used to allocate memory for each event record, just before
+ * assigning the record fields.
+ * This has the same purpose as TRC_STREAM_PORT_ALLOCATE_EVENT and by default
+ * it has the same definition as TRC_STREAM_PORT_ALLOCATE_EVENT. This is used
+ * for events carrying variable-sized payload, such as strings.
+ * In the SEGGER RTT port, we need this in order to make a worst-case
+ * allocation on the stack.
+ ******************************************************************************/
+#ifndef TRC_STREAM_PORT_ALLOCATE_DYNAMIC_EVENT
+#if (TRC_STREAM_PORT_USE_INTERNAL_BUFFER == 1)
+ #define TRC_STREAM_PORT_ALLOCATE_DYNAMIC_EVENT(_type, _ptrData, _size) TRC_STREAM_PORT_ALLOCATE_EVENT(_type, _ptrData, _size) /* We do the same thing as for non-dynamic event sizes */
+#else
+ #define TRC_STREAM_PORT_ALLOCATE_DYNAMIC_EVENT(_type, _ptrData, _size) _type _tmpArray[sizeof(largestEventType) / sizeof(_type)]; _type* _ptrData = _tmpArray;
+#endif
+#endif
+
+ /******************************************************************************
+ * TRC_STREAM_PORT_COMMIT_EVENT
+ *
+ * The COMMIT macro is used to write a single event record directly to the
+ * streaming inteface, without first storing the event in the internal buffer.
+ * This is currently only used in the SEGGER J-Link RTT port.
+ *
+ * This relies on the TRC_STREAM_PORT_WRITE_DATA macro, defined in by the
+ * stream port in trcStreamingPort.h. The COMMIT macro calls
+ * prvTraceWarning(TRC_STREAM_PORT_WRITE_DATA) if a non-zero value is returned
+ * from TRC_STREAM_PORT_WRITE_DATA. If zero (0) is returned, it is assumed
+ * that all data was successfully written.
+ *
+ * In ports using the internal buffer, this macro has no purpose as the events
+ * are written to the internal buffer instead. They are then flushed to the
+ * streaming interface in the TzCtrl task using TRC_STREAM_PORT_WRITE_DATA.
+ ******************************************************************************/
+#ifndef TRC_STREAM_PORT_COMMIT_EVENT
+#if (TRC_STREAM_PORT_USE_INTERNAL_BUFFER == 1)
+ #define TRC_STREAM_PORT_COMMIT_EVENT(_ptrData, _size) /* Not used */
+#else
+ #define TRC_STREAM_PORT_COMMIT_EVENT(_ptrData, _size) \
+ { \
+ if (TRC_STREAM_PORT_WRITE_DATA(_ptrData, _size, 0) != 0)\
+ prvTraceWarning(PSF_WARNING_STREAM_PORT_WRITE); \
+ }
+#endif
+#endif
+
+/******************************************************************************
+ * TRC_STREAM_PORT_READ_DATA (defined in trcStreamingPort.h)
+ *
+ * Defining how to read data from host (commands from Tracealyzer).
+ *
+ * If there is no direct interface to host (e.g., if streaming to a file
+ * system) this should be defined as 0. Instead use vTraceEnable(TRC_START) and
+ * vTraceStop() to control the recording from target.
+ *
+ * Parameters:
+ *
+ * - _ptrData: a pointer to a data buffer, where the received data shall be
+ * stored (TracealyzerCommandType*).
+ *
+ * - _size: the number of bytes to read (int).
+ *
+ * - _ptrBytesRead: a pointer to an integer (int), that should be assigned
+ * with the number of bytes that was received.
+ *
+ * Example:
+ *
+ * int32_t myRead(void* ptrData, uint32_t size, int32_t* ptrBytesRead);
+ *
+ * #define TRC_STREAM_PORT_READ_DATA(_ptrData, _size, _ptrBytesRead) \
+ * myRead(_ptrData, _size, _ptrBytesRead)
+ *
+ * Your "myRead" function should return 0 if successful, i.e. if at least some
+ * bytes were received. A non-zero value should be returned if the streaming
+ * interface returned an error (e.g. a closed socket), which results in the
+ * recorder calling prvTraceWarning with the error code
+ * PSF_WARNING_STREAM_PORT_WRITE.
+ *
+ * If developing your own custom stream port and using the default internal
+ * buffer, it is important that the _ptrBytesRead parameter is assigned
+ * correctly by "myRead", i.e. with the number of bytes actually written.
+ * Otherwise the data stream may get out of sync in case the streaming interface
+ * can't swallow all data at once.
+ ******************************************************************************/
+#ifndef TRC_STREAM_PORT_READ_DATA
+#error "No definition for TRC_STREAM_PORT_READ_DATA (should be in trcStreamingPort.h)"
+#endif
+
+/******************************************************************************
+ * TRC_STREAM_PORT_WRITE_DATA (defined in trcStreamingPort.h)
+ *
+ * Defining how to write trace data to the streaming interface.
+ *
+ * Parameters:
+ *
+ * - _ptrData: a pointer (void*) to the data to write.
+ *
+ * - _size: the number of bytes to write (uint32_t).
+ *
+ * - _ptrBytesWritten: a pointer to an integer (int32_t), that should be
+ * assigned with the number of bytes actually written.
+ *
+ * Example:
+ *
+ * int32_t myWrite(void* ptrData, uint32_t size, int32_t* ptrBytesWritten);
+ *
+ * #define TRC_STREAM_PORT_WRITE_DATA(_ptrData, _size, _ptrBytesWritten) \
+ * myWrite(_ptrData, _size, _ptrBytesWritten)
+ *
+ * Your "myWrite" function should return 0 if successful, i.e. if at least some
+ * bytes were sent. A non-zero value should be returned if the streaming interface
+ * returned an error (e.g. a closed socket), which results in the recorder calling
+ * prvTraceWarning with the error code PSF_WARNING_STREAM_PORT_WRITE.
+ *
+ * If developing your own custom stream port and using the default internal
+ * buffer, it is important that the _ptrBytesWritten parameter is assigned
+ * correctly by "myWrite", i.e. with the number of bytes actually written.
+ * Otherwise the data stream may get out of sync in case the streaming interface
+ * can't swallow all data at once.
+ *
+ * Assuming TRC_STREAM_PORT_USE_INTERNAL_BUFFER is 1 (default), the TzCtrl task
+ * will use this macro to send one buffer page at a time. In case all data can't
+ * be written at once (if _ptrBytesWritten is less than _size), the TzCtrl task
+ * is smart enough to make repeated calls (with updated parameters) in order to
+ * send the remaining data.
+ *
+ * However, if TRC_STREAM_PORT_USE_INTERNAL_BUFFER is 0, this is used from the
+ * COMMIT macro, directly in the "event functions". In that case, the
+ * _ptrBytesWritten parameter will be NULL and should be ignored by the write
+ * function. In this case, it is assumed that all data can be sent in a single
+ * call, otherwise the write function should return a non-zero error code.
+ ******************************************************************************/
+#ifndef TRC_STREAM_PORT_WRITE_DATA
+#error "No definition for TRC_STREAM_PORT_WRITE_DATA (should be in trcStreamingPort.h)"
+#endif
+
+/******************************************************************************
+* Data structure declaration, depending on TRC_CFG_RECORDER_BUFFER_ALLOCATION
+*******************************************************************************/
+#if (TRC_CFG_RECORDER_BUFFER_ALLOCATION == TRC_RECORDER_BUFFER_ALLOCATION_STATIC)
+
+ /* Static allocation. */
+
+ /* If not defined in trcStreamingPort.h */
+ #ifndef TRC_STREAM_PORT_ALLOCATE_FIELDS
+ #define TRC_STREAM_PORT_ALLOCATE_FIELDS() \
+ char _TzTraceData[(TRC_CFG_PAGED_EVENT_BUFFER_PAGE_COUNT) * (TRC_CFG_PAGED_EVENT_BUFFER_PAGE_SIZE)];
+ extern char _TzTraceData[(TRC_CFG_PAGED_EVENT_BUFFER_PAGE_COUNT) * (TRC_CFG_PAGED_EVENT_BUFFER_PAGE_SIZE)];
+ #endif
+
+ /* If not defined in trcStreamingPort.h */
+ #ifndef TRC_STREAM_PORT_MALLOC
+ #define TRC_STREAM_PORT_MALLOC() /* Static allocation. Not used. */
+ #endif
+#else
+ /* For Dynamic or Custom Allocation mode */
+
+ /* If not defined in trcStreamingPort.h */
+ #ifndef TRC_STREAM_PORT_ALLOCATE_FIELDS
+ #define TRC_STREAM_PORT_ALLOCATE_FIELDS() char* _TzTraceData = NULL;
+ extern char* _TzTraceData;
+ #endif
+
+ /* If not defined in trcStreamingPort.h */
+ #ifndef TRC_STREAM_PORT_MALLOC
+ #if (TRC_CFG_RECORDER_BUFFER_ALLOCATION == TRC_RECORDER_BUFFER_ALLOCATION_DYNAMIC)
+ #define TRC_STREAM_PORT_MALLOC() \
+ _TzTraceData = TRC_PORT_MALLOC((TRC_CFG_PAGED_EVENT_BUFFER_PAGE_COUNT) * (TRC_CFG_PAGED_EVENT_BUFFER_PAGE_SIZE));
+ extern char* _TzTraceData;
+ #else
+ #define TRC_STREAM_PORT_MALLOC() /* Custom allocation. Not used. */
+ #endif
+ #endif
+#endif
+
+#ifndef TRC_STREAM_PORT_INIT
+ #define TRC_STREAM_PORT_INIT() \
+ TRC_STREAM_PORT_MALLOC(); /* Empty if static allocation mode */ \
+ prvPagedEventBufferInit(_TzTraceData);
+#endif
+
+
+/* Signal an error. */
+void prvTraceError(int errCode);
+
+/* Signal an warning (does not stop the recorder). */
+void prvTraceWarning(int errCode);
+
+/******************************************************************************/
+/*** ERROR AND WARNING CODES (check using xTraceGetLastError) *****************/
+/******************************************************************************/
+
+#define PSF_ERROR_NONE 0
+#define PSF_ERROR_EVENT_CODE_TOO_LARGE 1
+#define PSF_ERROR_ISR_NESTING_OVERFLOW 2
+#define PSF_ERROR_DWT_NOT_SUPPORTED 3
+#define PSF_ERROR_DWT_CYCCNT_NOT_SUPPORTED 4
+#define PSF_ERROR_TZCTRLTASK_NOT_CREATED 5
+
+#define PSF_WARNING_SYMBOL_TABLE_SLOTS 101
+#define PSF_WARNING_SYMBOL_MAX_LENGTH 102
+#define PSF_WARNING_OBJECT_DATA_SLOTS 103
+#define PSF_WARNING_STRING_TOO_LONG 104
+#define PSF_WARNING_STREAM_PORT_READ 105
+#define PSF_WARNING_STREAM_PORT_WRITE 106
+
+/******************************************************************************/
+/*** INTERNAL STREAMING FUNCTIONS *********************************************/
+/******************************************************************************/
+
+/* Saves a symbol name (task name etc.) in symbol table */
+void prvTraceSaveSymbol(const void *address, const char *name);
+
+/* Deletes a symbol name (task name etc.) from symbol table */
+void prvTraceDeleteSymbol(void *address);
+
+/* Saves an object data entry (task base priority) in object data table */
+void prvTraceSaveObjectData(const void *address, uint32_t data);
+
+/* Removes an object data entry (task base priority) from object data table */
+void prvTraceDeleteObjectData(void *address);
+
+/* Store an event with zero parameters (event ID only) */
+void prvTraceStoreEvent0(uint16_t eventID);
+
+/* Store an event with one 32-bit parameter (pointer address or an int) */
+void prvTraceStoreEvent1(uint16_t eventID,
+ uint32_t param1);
+
+/* Store an event with two 32-bit parameters */
+void prvTraceStoreEvent2(uint16_t eventID,
+ uint32_t param1,
+ uint32_t param2);
+
+/* Store an event with three 32-bit parameters */
+void prvTraceStoreEvent3(uint16_t eventID,
+ uint32_t param1,
+ uint32_t param2,
+ uint32_t param3);
+
+/* Stores an event with <nParam> 32-bit integer parameters */
+void prvTraceStoreEvent(int nParam, uint16_t EventID, ...);
+
+/* Stories an event with a string and <nParam> 32-bit integer parameters */
+void prvTraceStoreStringEvent(int nArgs, uint16_t eventID, const char* str, ...);
+
+/* Initializes the paged event buffer used by certain stream ports */
+void prvPagedEventBufferInit(char* buffer);
+
+/* Retrieve a pointer to the paged event buffer */
+void* prvPagedEventBufferGetWritePointer(int sizeOfEvent);
+
+/* Transfer a full buffer page */
+uint32_t prvPagedEventBufferTransfer(void);
+
+/* The data structure for commands (a bit overkill) */
+typedef struct
+{
+ unsigned char cmdCode;
+ unsigned char param1;
+ unsigned char param2;
+ unsigned char param3;
+ unsigned char param4;
+ unsigned char param5;
+ unsigned char checksumLSB;
+ unsigned char checksumMSB;
+} TracealyzerCommandType;
+
+/* Checks if the provided command is a valid command */
+int prvIsValidCommand(TracealyzerCommandType* cmd);
+
+/* Executed the received command (Start or Stop) */
+void prvProcessCommand(TracealyzerCommandType* cmd);
+
+#define vTraceSetStopHook(x)
+
+#endif /*(TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)*/
+
+#else /* when TRC_USE_TRACEALYZER_RECORDER == 0 */
+
+#define vTraceEnable(x)
+#define xTraceRegisterString(x) 0; (void)x;
+#define vTracePrint(chn, ...) (void)chn
+#define vTracePrintF(chn, ...) (void)chn
+#define vTraceInstanceFinishedNow()
+#define vTraceInstanceFinishedNext()
+#define vTraceStoreISRBegin(x) (void)x
+#define vTraceStoreISREnd(x) (void)x
+#define xTraceSetISRProperties(a, b) 0
+#define vTraceStoreKernelObjectName(a, b)
+#define xTraceRegisterChannelFormat(eventLabel, formatStr) 0
+#define vTraceChannelPrint(label)
+#define vTraceUBData(label, ...)
+
+#define vTraceSetFilterGroup(x)
+#define vTraceSetFilterMask(x)
+
+#define prvTraceSetReadyEventsEnabled(status)
+
+#define vTraceExcludeTask(handle)
+
+#define uiTraceStart() (1)
+#define vTraceStart()
+#define vTraceStop()
+
+#ifndef vTraceSetRecorderDataBuffer
+#define vTraceSetRecorderDataBuffer(pRecorderData)
+#endif
+
+#define vTraceConsoleChannelPrintF(fmt, ...)
+
+#ifndef TRC_ALLOC_CUSTOM_BUFFER
+#define TRC_ALLOC_CUSTOM_BUFFER(bufname)
+#endif
+
+#define xTraceIsRecordingEnabled() (0)
+
+#define vTraceSetStopHook(x)
+
+#endif /*(TRC_USE_TRACEALYZER_RECORDER == 1)*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* TRC_RECORDER_H */
|