Making a snapshot

This section describes how to upload the trace data from the target system to Tracealyzer, when using snapshot mode.

Integrated support for ST-LINK and SEGGER J-Link
Tracealyzer has built-in support for ST-LINK and SEGGER J-Link (including J-Link compatible debuggers such as Atmel SAM-ICE). This integration works independently of your IDE and supports snapshot trace (see below). The J-Link integration also supports streaming.
The ST-LINK support is currently limited to snapshot mode.

To upload a snapshot using a SEGGER J-Link or ST-LINK, click the snapshot button in the Navigation Bar.
The trace is then opened in Tracealyzer within a few seconds.

The first time, you get a dialog "Select Memory Region" where you need to enter the address range of the recorder's trace buffer. This can be found by inspecting the trace buffer (RecorderDataPtr) with your debugger (e.g., "watch"). However, you don't need to use the exact memory range, as long as the trace buffer is fully included in the specified memory range. We therefore recommend specifying a larger memory block, to get some tolerance for minor changes in between builds. This setting is saved and reused in between Tracealyzer sessions.

Typical values are 0x0, 0x10000000 or 0x20000000 as start address and 0x10000 or 0x20000 as size (64 KB or 128 KB).

Note: Even if you don't have a stand-alone J-Link or ST-LINK probe, the USB debug connection on your development boards may actually be a J-Link or ST-LINK interface. Those on-board debuggers are supported in the same way as stand-alone debug probes, although their performance may be lower. Look for a ST-LINK or SEGGER J-Link label next to a USB connection on your board.

Snapshot trace using Eclipse-based IDEs
The Percepio Trace Exporter plugin makes it easy to upload trace snapshots from Eclipse-based IDEs. The plugin supports any debug probe that is supported by your Eclipse IDE.

As shown in the above screenshot, the plugin gives you a new "Percepio" menu from which you can save snapshot traces via the currently active debug session, and then open these in Tracealyzer. The plugin finds the trace data automatically, so no need to enter the address of the trace buffer.

To install the plugin, see https://percepio.com/exporter/ for instructions. Note that the plugin does not include Tracealyzer itself, it is a separate download and runs as a standalone application.

The plugin works with most Eclipse-based IDE's, but we have noted issues with some IDEs where the vendors have made changes to the Eclipse debugging framework. In that case, please let us know (support@percepio.com) and we will try to fix it.

Snapshot trace using Xilinx SDK (2018.3)
Unfortunatly our Eclipse plugin is not compatible with Xilinx SDK, but you may use the XSCT Console to save snapshot traces (or otherwise use TCP/IP streaming). Just follow the below steps (but don't type in the quotation marks).

• Ensure that you are in an active debug session, the target system is halted (e.g. on a breakpoint) and that vTraceEnable(TRC_START) has been executed.
• Open the XSCT Console, found in the Xilinx menu.
• Set the working directory where the trace file should be saved by entering "cd [desired output directory]" or simply "cd" to move to your home directory.
• Enter "print RecorderDataPtr" to see the address of the trace data structure.
• Enter "print RecorderDataPtr->filesize" to see the size of the trace data structure (in bytes).
• Enter "mrd -bin -file trace.bin [address] [size in words]" to save the trace data to the host file "trace.bin".
  • Note that RecorderDataPtr->filesize expression gives the size in bytes, not words as expected by the mrd command. It is no problem is you enter the size in bytes instead of the size in words, but it might take a bit longer to save the data. Calculate the word size as [byte size] / [word length, 4 or 8] + 1. In general, you don't need to specify the exact address range. A larger range is fine, as long as the trace data is fully included.
  • You can use CTRL-C to copy the results from the "print" commands and then use CTRL-V to paste them into the "mrd" expression.
• Open the resulting file (trace.bin) in Tracealyzer.

Snapshot trace using Microchip MPLAB X IDE
We provide a plugin for MPLAB X IDE supporting snapshot data upload for Tracealyzer. The plugin can be downloaded here and supports any debug probe that is supported by MPLAB. To learn more about this plugin, read this blog post.

Snapshot trace using IAR Embedded Workbench for ARM
The IAR debugger can be configured to save the trace buffer to a host-side file, either manually or automatically, using a debugger macro. Follow these steps:

1. Create a macro file in the project directory (e.g. "save_trace_buffer.mac") with the following contents:

   
   __var start;
   __var end;
   
   save_trace_buffer()
   {
   	start = __smessage "Memory:0x",RecorderDataPtr:%x;
   	end  =  __smessage "Memory:0x",(RecorderDataPtr + 1):%x;
   	__memorySave(start,end,"intel-extended", "$PROJ_DIR$\\trace.hex");
   
   	return 0;
   }
                       

   
   
2. Add the macro file under Options -> Debugger -> Use Macro File(s).
3. When in a debug session, open View -> Macros -> Debugger Macros and check that "save_trace_buffer" is included.
4. Now, to call the macro and thereby save the trace, you have three options:
   • Manually: In the Debugger Macros view, right-click on you macro and select "Add to Quicklaunch window". Now you can save the trace by double-clicking on the blue "refresh" icon in the Quicklaunch window.
   • On a breakpoint: Place a breakpoint on a suitable location in the code. Open it in the breakpoint editor and enter your macro name (e.g., "save_trace_buffer()") in the Action -> Expression field. The trace is now saved every time that breakpoint is hit.
   • On every halt: To update the trace on every halt, rename the "save_trace_buffer" function to execUserExecutionStopped(). That is a special hook that is called every time the execution is halted. Note that this can slow down single-stepping if the buffer is large.

To enable quick access to Tracealyzer and the current trace, you may include Tracealyzer in the Tools menu, with "trace.hex" specified as parameter.

1. Select "Configure Tools..." in the Tools menu
2. Add a new entry "Tracealyzer"
3. Set the path to the Tracealyzer executable (the ".exe" file).
4. Set the argument to "$PROJ_DIR$\trace.hex"

Snapshot trace using Renesas High-performance Embedded Workshop (HEW)
In the debugger view, when stopped on a breakpoint:

• Select "Debug" menu, "Save Memory..." (keyboard shortcut: ALT,d,a)
• In the Save dialog
• Format: Binary
• Filename: "name.bin"
• Start Address: 00000000 (example start address)
• End Address: 0000FFFF (example end address)
• Access size: 1
• Press "Save" button and open "name.bin" in Tracealyzer.

Snapshot trace using Microchip MPLAB v8

• Select "View" -> "File Registers". This shows you the memory contents.
• Make sure "Hex" is selected in the bottom left (instead of "Symbolic"). Hex mode seems to be default.
• Right click in the view and select "Export Table...".
• In the dialog ("Export As"), make sure "Single Column Output" is selected (seems to be default).
• Select start address 0x0000 and make sure the end address is beyond the RecorderData structure. The default values seems to be the whole RAM, so you probably don't need to change this.
• Save as a .mch file and open this file in Tracealyzer.

Streaming trace using STM32 ST-LINK

Streaming is not yet directly supported on ST-LINK, but it is quite easy to reprogram an onboard ST-LINK debug interfaces, found on many ST development boards, with J-Link firmware. This effectively transforms the ST-LINK interface into a J-Link interface. In this way, you can use the built-in J-Link integration (also streaming), although performance will not be on the same level as a stand-alone J-Link. Note that this is an official initiative from SEGGER.

See this blog post for instructions.

Note: This does not work for stand-alone ST-LINK units.

Snapshot trace using Rowley CrossStudio for ARM v3.2

• Open a "Watch" window and enter "*RecorderDataPtr" (click in the right-side part of the "Name" field to enable editing).
• Right click on "*RecorderDataPtr" and select "Locate Memory", which opens the Memory view on that specific address range.
• Right-click anywhere in the Memory view table and select "Save As" and then "Intel Hex" or "Binary".
• Open the resulting file in Tracealyzer.

Snapshot trace using Keil MDK/µVision

• Open the "Command" window in µVision
• Enter the command exec("SAVE \"out.hex\" RecorderDataPtr , (RecorderDataPtr + 1)");
• Open the resulting file in Tracealyzer, located in the project directory.

You can automate this procedure and get a tool bar button for this command, as illustrated above. To do this, open the "Function Editor" (in "Debug" menu, enabled when debugging...) and add the below code:

FUNC void SavePercepioRecorderData(void) {
printf("Saving Recorder Data in out.hex!\n") ;
exec("SAVE \"out.hex\" RecorderDataPtr , (RecorderDataPtr + 1)");
}
DEFINE BUTTON "Save Recorder Data", "SavePercepioRecorderData()"


Snapshot trace using other IDEs or debug probes
Most debuggers are able to save the RAM contents to a file. Tracealyzer supports the following common formats:

• Binary (.bin or .dump), supporting gdb, J-Link and Renesas HEW.
• Intel Hex (.hex), supporting IAR Embedded Workbench and Atmel MemoryLogger.
• MCH (.mch), supporting Microchip MPLAB 8.

Connecting and Recording

To connect to the target system in streaming mode, select "Connect to Target System..." in the File menu and click "Start Recording". This establishes a connection with the target and activates the tracing. This assumes the following:

1. The recorder has been properly integrated in your system.
2. The recorder has been properly configured for streaming.
3. The system is running and vTraceEnable() has been called.

When recording, a live graph, updated in real-time, shows the CPU load in the target system.

The red line shows the CPU usage of the application tasks, i.e., the relative number of clock cycles used. This excludes the Idle task, so 100% load means that the Idle task is not executing at all.

Tasks and RTOS API calls are traced automatically. To trace ISRs, you need to call vTraceStoreISRBegin() and vTraceStoreISREnd() in your ISRs. See Recorder API for further details.

• Start Recording: Sends a "Start Recording" command to the target system (i.e., to the TzCtrl task), and begins capturing trace data from the target. This button toggles between "Start Recording" and "Stop Recording".
• Stop Recording: Sends a "Stop Recording" command to the target system, waits for the final data, and then finalizes the trace. This button toggles between "Start Recording" and "Stop Recording".
• Settings: Opens the streaming settings.
• Save Trace: Allows for saving the trace to a file, without opening it.
• View Trace: Opens the trace in the main Tracealyzer application. If the trace has not been saved, you'll be prompted to do so.

Stream ports

A stream port is a set of macros that define how the recorder shall write the trace data to the streaming interface, and how to read commands (Start/Stop) from Tracealyzer. The recorder includes several predefined stream ports, defined by the trcStreamingPort.h files found in the streamports directory. The header file contains preprocessor macros and prototypes, while the I/O functions referred to are typically implemented in trcStreamingPort.c. These predefined ports include support for streaming via Arm ITM, e.g. for IAR Embedded Workbench and Keil µVision, SEGGER J-Link debug probes, as well as examples of USB streaming, TCP/IP streaming and streaming to a device file system.

The stream port is selected by including the appropriate trcStreamingPort.h in your compiler's search path. The stream ports may also contain some .c files, that also needs to be included in the build.

Some stream ports use an internal RAM buffer in the trace recorder for temporary storage of the data, periodically flushed to the streaming interface by the trace control task (TzCtrl). This is the default setup. For other stream ports, like the Arm ITM port, the WRITE_DATA macro however writes directly to the streaming interface without involving the trace control task. This requires a fast interface where the data transfer doesn't generate any new trace events (e.g., by RTOS calls) as this would cause infinite recursion.

You can also create your own stream port to utilize any suitable communications interface in your system. Check the provided stream ports and this blog post for a quick introduction.

The main definitions of a stream port (in trcStreamingPort.h) are:

• TRC_STREAM_PORT_READ_DATA - How to read commands (start/stop) from Tracealyzer via the streaming interface. Should return 0 on success. If streaming e.g. to a device file system (without a PC connection to Tracealyzer) this should be defined as 0.
• TRC_STREAM_PORT_WRITE_DATA - How the recorder should write trace data to the streaming interface. Should return 0 on success.

SEGGER J-Link Streaming

The J-Link stream port works on all ARM Cortex-M and Renesas RX MCUs. It also works on many ARM Cortex-R and ARM Cortex-A processors, see this application note from SEGGER. With a sufficient RAM buffer size, this allows for streaming the trace data at speeds upwards of 700 KB/s on a standard J-Link (Version 9) and upwards of 2 MB/s on the high-end models. It works even on the J-Link On Board (OB), found integrated on many development boards, although these have lower performance (around 100 KB/s). RTOS tracing usually generates about 20-200 KB/s, so systems with high event rate may require a proper stand-alone J-Link probe.

The SEGGER J-Link streaming uses a proprietary SEGGER feature called RTT, Real-Time Transfer. It relies on RAM buffers in the target system, which the J-Link reads in the background without disturbing the execution. The Tracealyzer recorder uses two RTT buffers, one control channel for receiving commands from Tracealyzer and one data channel for streaming the trace. All source code required for SEGGER RTT is included in the J-Link stream port directory and relevant settings are found in trcStreamingPort.h.

• TRC_CFG_RTT_BUFFER_SIZE_UP: The size of the target->host RTT buffer, used for streaming the trace data. Default 5000 bytes.
• TRC_CFG_RTT_BUFFER_SIZE_DOWN: The size of the host->target RTT buffer, used for start/stop commands. Default 32 bytes.
• TRC_CFG_RTT_UP_BUFFER_INDEX: The RTT buffer index to use for the UP buffer (target->host). Must match the corresponding setting in Tracealyzer (File -> Settings). Default 1.
• TRC_CFG_RTT_DOWN_BUFFER_INDEX: The RTT buffer index to use for the DOWN buffer (host->target). Must match the corresponding setting in Tracealyzer (File -> Settings). Default 1.
• TRC_CFG_RTT_MODE: What to do if the streaming buffer becomes full...
  • SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL: The recorder blocks (stalls) the system until the J-Link has made room in the buffer. This is default, since it ensures correct data transfer.
  • SEGGER_RTT_MODE_NO_BLOCK_SKIP: Events are skipped if the RTT buffer is full. If this should occur, the number of dropped events is displayed in Tracealyzer while receiving the trace. Moreover, Tracealyzer also highlights the intervals with incomplete data using a light red background color. We recommend trying this mode as well, to see that the RTT buffer is large enough.

Note that the UP buffer (target->host) is quite large by default (5000 bytes). If you have a stand-alone J-Link probe, you can typically reduce this buffer size to 1-2 KB. If using an integrated J-Link On-board, 5-10 KB can be necessary to maximize throughput - the maximum seem to be about 140 KB/s in this case.

If there would be recorder blocking or dropped trace events, try the following:

• Verify the J-Link Speed in the Settings dialog of Tracealyzer. Default is 4 MHz, but can be increased a lot depending on your J-Link model. In many cases speeds of 10-20 MHz is possible, but according to SEGGER there is a small risk of getting poor signal quality (i.e., problems) if going above 6 MHz, depending on the development board. But don't worry, nothing will break and any corrupted data will result in obvious error messages when processing the trace. And if you set the J-Link Speed higher than the maximum supported speed, the J-Link driver will instead use the highest speed supported.
• Increase the trace buffer size (TRC_CFG_RTT_BUFFER_SIZE_UP in trcStreamingPort.h).
• Reduce the amount of data produced, e.g., by excluding frequent User Events.
• If using an integrated J-Link OB on your development board, consider upgrading to a stand-alone J-Link probe (which is several times faster).

Before making your first trace recording, please install the latest J-Link drivers and make sure all listed development tools are updated, including Tracealyzer. Also make sure the firmware of your J-Link debug probe is updated correctly, if the J-Link drivers would propose this.

Check J-Link Settings, found under File -> Settings... in Tracealyzer.

• Debugger: Select the connected J-Link debug probe to use.
• J-Link Speed: The debugger clock frequency for the JTAG/SWD interface (KHz).
• Debugger Interface:
  • JTAG: Configures the debug probe for JTAG. This is the default setting of J-Link debug probes.
  • SWD: Configures the debug probe for SWD.
  • Default (don't change): Tracealyzer does not change the JTAG/SWD setting of the debug probe.
    NOTE! It is recommended to explicitly select JTAG or SWD, matching the corresponding setting in your IDE. This "passive" option is known to cause problems with certain J-Link driver versions.
• Target Device: Opens a SEGGER J-Link dialog where you can select the device (processor). This is necessary in order for SEGGER RTT to connect automatically.

Also check PSF Streaming Settings.

• Target Connection: Should be "SEGGER RTT".
• RTT Control Block Address: How to find the RTT control block in the target memory. Normally this should be "auto-detect" (translates to 0). In case the automatic detection fails, we recommend to add the SEGGER_RTT_SECTION definition in the recorder code, as described in Troubleshooting J-Link RTT streaming - The RTT Control Block. It is also possible to specify the address of the RTT control block (_SEGGER_RTT) explicitly in this field, but that option might not work if using Tracealyzer in parallel with an IDE.
• RTT Up Buffer Index: The RTT buffer to use for the trace data channel (target -> host). Default is 1 and must match the setting in trcStreamingPort.h.
• RTT Down Buffer Index: The RTT buffer to use for the control channel (host -> target). Default is 1 and must match the setting in trcStreamingPort.h.
• Reset Target on Connect: Enable this to reset the target system when the recording is started, in order to trace the system startup. For use together with the TRC_START option for vTraceEnable().
• Target Starts Tracing: Enable this if using the TRC_START option for vTraceEnable(). This way, Tracealyzer won't send a start command when the recording session begins, just wait for the data.

Troubleshooting J-Link RTT streaming

If you will only see "Starting session..." in the Live Stream window, Tracealyzer is not getting any data. In that case, double-check the below steps.

In case Tracealyzer gets some data, but you are having performance problems (e.g. missing events or high overhead) please refer to this FAQ post on our website. Also see the general Troubleshooting section.

1. Target Device
   

   Under Settings -> J-Link Settings, make sure you have specified the "Target Device" correctly. The "Select Device..." button shows a list of all devices supported by your SEGGER J-Link driver. This setting is required for the SEGGER driver to locate the RAM address range(s) and find the RTT data structure.

2. J-Link Driver Version
   

   Make sure to install the latest J-Link drivers from SEGGER. They are frequently updated, especially for new devices. It is important that the same version of the J-Link driver version is used by Tracealyzer and your IDE. Therefore, make sure to install the latest J-Link drivers as the last step, after Tracealyzer has been installed. After updating the J-Link driver, it may want to update the J-Link firmware as well. We strongly recommend allowing that.

3. Debugger Interface (JTAG/SWD)
   

   Make sure the Debugger Interface setting (JTAG/SWD) is the same in Tracealyzer (Settings -> J-Link Settings) as in your debugger IDE. If case they differ, you get a warning from the J-Link driver ("Second debugger connection to the same J-Link detected...", as shown below) and a question if to change the interface setting. In that case, just abort and correct the Tracealyzer setting under Settings -> J-Link Settings.

   

   Note that Tracealyzer offers a third option in the Debugger Interface setting, Default (don't change). This means that Tracealyzer will not attempt to change the JTAG/SWD selection and instead uses the current setting (e.g. applied by the debugger IDE). This can be convenient in some cases. However, the J-Link probes use JTAG by default and will revert to JTAG if power-cycled. So if using "Default (don't change)" you may get conflicts under certain circumstances and thereby a warning from the J-Link driver (like above). Moreover, some J-Link driver versions (around v6.22 - v6.30) are known to cause problems if not setting the JTAG/SWD selection explicitly in Tracealyzer.

4. Tool Connection Order
   

   If using Tracealyzer together with a debugger IDE, make sure to first start the debug session and thereafter connect with Tracealyzer. If modifying your code and reprogramming the device, you need to stop the Tracealyzer recording and then restart the Tracealyzer recording for the new debug session.

   Note that you don't need to start the target system before connecting with Tracealyzer. It is sufficient that the debug session has been launched and that the target is halted in main.

   When using vTraceEnable(TRC_START), we recommend the following order:

   1. Launch the debug session and let the target halt on a breakpoint in main, before vTraceEnable is called.
   2. Select "Start Recording" in Tracealyzer. The "Live Stream" window it should now say "Starting session...", as it waits for data.
   3. Start your target system (resume/run). You will now capture every event after vTraceEnable.
   NOTE: Make sure to CHECK the option "Target Starts Tracing" when using the TRC_START option (Tracealyzer settings -> PSF Streaming Settings).

   If using vTraceEnable(TRC_START_AWAIT_HOST) or vTraceEnable(TRC_INIT), the order is simply:

   1. Launch the debug session and start the target system.
   2. Click "Start Recording" in Tracealyzer.
   NOTE: Make sure to UNCHECK the option "Target Starts Tracing" when using these start options (Tracealyzer settings -> PSF Streaming Settings).

5. The RTT Control Block
   

   The J-Link driver needs to locate the address of the RTT control block before the RTT interface can be used. Normally this works automatically, but in some cases it is necessary to configure this manually.

   You can see the status of the J-Link RTT interface in the J-Link Control Panel, that can be accessed via the "J-Link" icons in the task bar (if using Windows). Note that there might be two icons, as shown below. This is not a mistake. Each development tool using the J-Link drivers spawns a separate driver instance, with a separate Control Panel. So if you are using a debugger IDE and Tracealyzer at the same time, you get two control panels. This is normal and supported by SEGGER.

   

   The J-Link RTT interface is handled by the primary J-Link Control Panel (the first started) while the secondary J-Link Control Panel instance will report "RTT handled by other J-Link instance". If the primary Control Panel reports "Looking for RTT CB", it means that the J-Link driver is still searching for the RTT control block and is not yet ready. This is normal before vTraceEnable has been called, where the J-Link RTT interface is initialized. The J-Link driver should find it directly after vTraceEnable has been called, and then start receiving data.

   In case Tracealyzer is not getting any data and the "Looking for RTT CB" message is still shown after vTraceEnable has been called, it typically means that the J-Link driver is scanning wrong address range. You can verify this by checking the address of _SEGGER_RTT in your debugger and compare with the addresses shown next to the "Looking for RTT CB" message. If incorrect, you can specify the address of the RTT control block (_SEGGER_RTT) in the "RTT Address" field. Make sure that you are using the primary J-Link Control Panel, where the "Looking for RTT CB" message is shown.

   Tracealyzer allows for specifying the address of the RTT Control Block in the PSF Streaming Settings. However, this requires that you know the exact address, and that it does not move between builds. Moreover, it seems the SEGGER J-Link driver only allows for specifying the RTT address in the primary driver instance, i.e. the first one started. The RTT communication is handled by the primary J-Link driver instance. So, if you have started a debug session in your IDE before connecting with Tracealyzer, it seems as the secondary J-Link driver just ignores the RTT address specified by Tracealyzer.

   A better way of resolving this issue is to add a definition of SEGGER_RTT_SECTION in your SEGGER_RTT_Conf.h. This instructs the linker where to place the RTT control block. The J-Link driver only seems to scan the "primary" RAM bank of the device (and only the first 64 KB of this, it seems), but by specifying SEGGER_RTT_SECTION you can make sure _SEGGER_RTT is placed where the J-Link will find it. The _SEGGER_RTT control block is pretty small, so moving it should not be a big deal. This does not contain the actual RTT data buffers, only pointers to them.

   First you need to check what address range that is scanned by the J-Link driver. You see this in the J-Link Control Panel, under "RTT". The scanned addresses appear next to the "Looking for RTT CB" messages.

   Once you know where the J-Link driver expects to find the RTT control block, you need to take a look at your linker file (or linker project settings). The easiest approach is to identify an existing section that is already placed in the right address range, i.e. where the J-Link scans. If so, specify this section in your SEGGER_RTT_SECTION definition to place the RTT control block there.

   In the below example, the scanned address range was 0x20000000 - 0x2000FFFF. In the linker file we noted that this address range contained the ".data" section of RAM2, so we placed it there.

   			   
   /* In SEGGER_RTT_Conf.h */
   #define SEGGER_RTT_SECTION ".data.$RAM2" /* for NXP LPC54018 */
   

   Another solution, that might be "cleaner" but a bit more difficult, is to create a new section dedicated for the RTT control block, that is placed in the desired address range.

TCP/IP Streaming

To stream the trace data over a network connection, i.e., TCP/IP transfer, select the TCPIP stream port. The existing example is for lwIP, so if you are using a different TCP/IP stack you need to modify this accordingly.

The TCP/IP stream port should act as a server, to which Tracealyzer connects as a client. You need to decide on an available TCP port and specify this in the stream port as well as in the Tracealyzer TCP/IP settings, shown below.

This stream port uses the recorder's internal RAM buffer. This is necessary since a TCP/IP stack is quite complex and should not be called directly from the kernel instrumentation code. That may even cause infinite recursive calls, if the TCP/IP stack generates new RTOS events when sending the data.

In Tracealyzer, check the PSF Streaming Settings, found under File -> Settings... in Tracealyzer.

• Target Connection: Should be "TCP".
• TCP/IP Address: The IP address of your target system.
• Port: The port used by target-side TCP/IP socket that you have created for the recorder.

ITM Streaming

The ARM_ITM stream port is a generic solution for streaming over the ITM interface on Arm processors. This is available on virtually all Arm Cortex-M3/M4/M7 MCUs, but not on Arm Cortex-M0/M0+ MCUs.

The benefit of the ITM interface is that the data can be transferred over the SWO pin, available on all Arm Cortex debug connectors. ITM provides hardware buffering, allowing for high data rates. Due to this, it is not necessary to use a RAM buffer for temporary storage, so this stream port instead writes the data directly to the ITM stimulus register. Assuming the ITM buffer has room for the data, a 32-bit word can be written in less than 10 clock cycles.

However, the hardware ITM buffer is pretty small (typically 10 bytes) and the trace data are often generated in bursts that can easily fill the ITM buffer. It is therefore important to use a high SWO frequency (ideally over 30 MHz, in Manchester mode), so the debug probe can pull out the data fast enough.

The stream port blocks in case the ITM buffer is full, but typically only for very brief durations. The worst case blocking time corresponds to the time needed to transmit the full 10 bytes ITM buffer over SWO. At 24 MHz SWO frequency, we have measured this to about 15 µs. However, if you have a fast debug probe like a Keil ULINKpro, blocking does typically not occur.

To receive the data on host side, you need a debugger with high-speed SWO support, at least 10 Mhz, but the faster the better. This is supported by e.g. Keil ULINKpro and IAR I-jet. Moreover, your debugger must allow for outputting the ITM data so Tracealyzer can read it. Both Keil µVision and IAR Embedded Workbench offer such possibilities.

By default, this uses ITM port 1, but this is possible to change in trcStreamingPort.h.

For detailed instructions on how to use this with Keil µVision, see Percepio Application Note PA-021.

For users of IAR Embedded Workbench, see Percepio Application Note PA-023.

USB Streaming

The USB_CDC stream port provides an example of how to stream trace data over a USB connection, using a CDC class endpoint. The example provided is for STM32, with USB drivers generated by STM32Cube. If you are using a different MCU, you need to modify the stream port accordingly.

If your system is already using the USB controller for other purposes, you may consider setting up a Composite Device that includes also a CDC endpoint. The performance of USB (even USB 2.0) is many times more than required for RTOS trace streaming.

The USB stream port uses the recorder's internal RAM buffer. This may not be necessary, depending on the internal buffers in the USB stack. If you need to reduce RAM usage, you can try writing directly in the WRITE_DATA macro, like in the J-Link stream port.

In Tracealyzer, check the PSF Streaming Settings, found under File -> Settings... in Tracealyzer. Select "SerialPort" and specify the COM port (e.g. "COM5") created for this connection. The other settings are not relevant for USB CDC connections. They allow for streaming over a classic UART-based serial connection. This however requires a fast UART and an appropriate stream port.

• Target Connection: Should be "SerialPort".
• Device: The COM port created for your USB CDC connection (e.g. "COM5").
• Others: Not applicable for USB CDC connections.

Custom Streaming

You may configure the streaming to use any interface you have available between target and the host PC, assuming it provides sufficient throughput. The data rate resulting from RTOS tracing depends on your application and RTOS configuration (like tick rate), but typically you need something like 20-200 KB/s. Read more about custom trace streaming in this blog post, RTOS Tracing, your way. For instance, if you have a flash file system on your target system (e.g., a memory card) you can stream to a local file.

To setup a custom transfer method, copy one of the stream port directories and use that as a starting point. The main file is trcStreamingPort.h.

Typically, you only need to define the following macros, together with prototypes for the functions they use:

• TRC_STREAM_PORT_READ_DATA - How to read commands (start/stop) from Tracealyzer via the streaming interface. Should return 0 on success. If streaming e.g. to a device file system (without a PC connection to Tracealyzer) this should be defined as 0.
• TRC_STREAM_PORT_WRITE_DATA - How the recorder should write trace data to the streaming interface. Should return 0 on success.

Most stream ports should use the internal RAM buffer in the recorder, in the same way as the TCP/IP port and the USB CDC port. In this case, trcStreamingRecorder.c writes the data to the internal buffer, which is periodically flushed by the trace control task (TzCtrl) to the streaming interface. Note that the buffer used a multi-page structure. The data is not sent until a page becomes full. You may want to tweak the settings for trace control task (periodicity and priority) and also the buffer layout (bytes per page and number of pages). These settings are found in trcStreamingConfig.h.

It is however possible to omit the internal buffer and instead write directly to the transfer channel, but only if (1) the streaming channel is dedicated for this purpose, and (2) the writes do not generate any kernel events, e.g., from Mutex or Semaphore operations.

Tracealyzer can receive the data in four ways, using a TCP connection, a COM port, by opening a file, or via a Named Pipe. The latter is for Windows only. If there the streaming interface doesn't provide two-way communication between Tracealyzer and the target system, you can start the tracing programmatically from target using vTraceEnable(TRC_START), which assumes that the trace interface is ready to receive the data. If using another target connection, you may consider creating a proxy tool that forwards the data to a TCP or COM port, or writes it to a host-side file. The trace data is a binary format and should be stored to a binary file exactly as received. Name the output file ".psf" to make it easier to find in Tracealyzer.

Tuning the Snapshot Configuration

In snapshot mode, there are several settings that affect RAM usage, e.g., TRC_CFG_EVENT_BUFFER_SIZE, TRC_CFG_SYMBOL_TABLE_SIZE, TRC_CFG_NTASK, TRC_CFG_NQUEUE and a few more. TRC_CFG_EVENT_BUFFER_SIZE is usually the main factor, as it controls the size of the main event buffer. This is by default 4000 bytes. The usage of this buffer can be reduced in several ways described in the Recorder API e.g. by excluding certain objects or by only including task-switches.

TRC_CFG_SYMBOL_TABLE_SIZE is typically the second largest factor, by default 800 bytes. This controls the size of the symbol table, allowing efficient storage of names, format strings, etc.
TRC_CFG_NTASK, TRC_CFG_NQUEUE and a few similar ones controls the size of the object table, that is used for keeping track of the active RTOS objects.

TRC_CFG_SYMBOL_TABLE_SIZE and TRC_CFG_NTASK etc. must not be too small, as that would cause the recorder to report an error and stop recording. It is therefore advised to start with relatively large values. But too large values will waste precious RAM. Tracealyzer can however report the resource usage from a trace session, allowing you to tune these settings and thereby optimize the RAM usage. Assuming you have a snapshot trace open in Tracealyzer, this is found under View -> Trace Overview.

Note the entries under Object Table - they show the number of slots allocated, based on TRC_CFG_NTASK, TRC_CFG_NQUEUE, etc., and also the actual usage of these slots. Each Object Table slot holds meta data about an active RTOS object, like a task or a queue, and requires about 20 bytes each, depending on the maximum name lengths specified in TRC_CFG_NAME_LEN_TASK etc. (this can also be tuned, to further reduce RAM usage). In this example, TRC_CFG_NQUEUE was set to 10 but only 3 queues were created by the system, meaning that TRC_CFG_NQUEUE can be reduced to 3. If optimizing all these settings, we can thereby eliminate 34 slots and free up about 680 bytes of RAM.

Common API

vTraceEnable

void vTraceEnable(int startOption)

Initializes and optionally starts the trace, depending on the start option.

When the trace recorder is included, you must call vTraceEnable in your startup code, before any RTOS calls are made (including "create" calls) but after the initial hardware setup (of clocks etc.).

The parameter startOption should be one of:

• TRC_START:

  Starts the tracing directly.
  

  vTraceEnable(TRC_START) can be called in two ways - either directly in the startup, or from a task after the kernel has started. However, the recorder must always be initialized before the RTOS is started, so if not starting the trace directly, you should call vTraceEnable(TRC_INIT) in the startup code.
  

  In streaming mode, this option is recommended if the recorder is controlled from target code, without a direct Tracealyzer connection, e.g., if streaming to a device file system.

  The TRC_START option may also be used when streaming directly to the Tracealyzer application. In that case, make sure to enable "Target Starts Tracing" in the Tracealyzer PSF streaming settings. Or, if you are using TCP/IP tracing, make sure to use the "TCP (Target initiated)" option.

  If using J-Link RTT streaming, you may combine vTraceEnable(TRC_START) with the "Reset on Connect" option. This will reset the target system when clicking "Start Recording" in Tracealyzer and trace the system from the startup, without having to reset it manually in your debugger IDE.

  An alternative to "Reset on Connect" is to instead set a breakpoint in the early startup. Launch a debug session and let the system halt on the breakpoint. Then select Start Recording in Tracealyzer so it begins waiting for data, and finally resume the target system execution.

• TRC_START_AWAIT_HOST:

  Waits for a Start command from Tracealyzer ("Start Recording" button) and then begins tracing from this point. This way, you don't miss the initial events.

  This is not supported in snapshot mode, but for streaming mode only. Intentionally blocking!
  

  This option is only intended to be used when calling vTraceEnable from the startup code, i.e., before the RTOS has been started. Thus, this option requires that the stream port has two-way communication and that the stream port is fully operational before the RTOS kernel has started. It works fine with J-Link RTT streaming, but we don't recommend this method for other stream ports.

  When using this option, make sure that "Target Starts Tracing" is NOT selected in the Tracealyzer PSF streaming settings.

• TRC_INIT:

  Initializes the trace recorder, but does not start the tracing.

  You don't need to call vTraceEnable(TRC_INIT) if you call vTraceEnable(TRC_START) or vTraceEnable(TRC_START_AWAIT_HOST) in the startup code, as these options also initialize the recorder if needed. However, if you prefer to start the recording at a later point (after the RTOS has started) you need to call vTraceEnable(TRC_INIT) in the startup code.

  If using streaming mode, you can start the tracing from Tracealyzer ("Start Recording" button) as long as vTraceEnable(TRC_INIT) or vTraceEnable(TRC_START_AWAIT_HOST) has been called.

  When using this option in streaming mode, make sure that "Target Starts Tracing" is NOT selected in the Tracealyzer PSF streaming settings.

Examples:

Snapshot mode	Streaming mode
myBoardInit(); ... /* From startup */ vTraceEnable(TRC_START); ... /* RTOS scheduler starts */ vTaskStartScheduler();	myBoardInit(); ... /* From startup - blocks until start from host */ vTraceEnable(TRC_START_AWAIT_HOST); ... /* RTOS scheduler starts */ vTaskStartScheduler();
myBoardInit(); ... /* Init only, trace starts later...*/ vTraceEnable(TRC_INIT); ... /* RTOS scheduler starts */ vTaskStartScheduler(); ... /* In a task or ISR */ vTraceEnable(TRC_START);	myBoardInit(); ... /* Init only, trace starts later...*/ vTraceEnable(TRC_INIT); ... /* RTOS scheduler starts */ vTaskStartScheduler(); ... /* "Trace Start" command from Tracealyzer is received by TzCtrl task. */

The tracing does not start if the recorder has detected an error, e.g. related to the configuration. An error message is then presented when opening the trace. To see the context of the error, put a breakpoint inside prvTraceError. Note that prvTraceError has two alternative implementations, one for snapshot mode and another for streaming.

vTraceStop

void vTraceStop(void)

Stops the recording. Mainly intended for snapshot mode or if streaming to device storage or a USB drive, without host control.

vTracePrintF

void vTracePrintF(traceString chn, const char* fmt, ...)

Generates User Events, i.e., formatted text and data, with similar interface as a classic "printf" call. 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 measured in microseconds on a 32-bit MCU.

User Events are shown as yellow labels in the main trace view, if enabled in the View Filter.

User Events with data arguments can also be plotted in the User Event Signal Plot. This way, you can visualize any kind of data that your code can access, such as software states, hardware states, system inputs and outputs.

You may group User Events into named channels, for filtering in Tracealyzer. The yellow User Event labels show the logged string, preceded by the channel name within brackets ("[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 specifiers. For example, assuming -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 mode you simply provide a char* as argument.

Snapshot:

vTracePrintF(myChn, "my string: %s", str);

vTracePrintF(myChn, "my string: %s", xTraceRegisterString(str));

In snapshot mode you can specify 8-bit or 16-bit arguments to reduce RAM usage.

vTracePrintF(myChn, "%hd", val); // 16 bit (h) signed integer (d)

vTracePrintF(myChn, "%bu", val); // 8 bit (b) unsigned integer (u)

In streaming mode all data arguments are assumed to be 32 bit wide. Width specifiers (e.g. %hd) are accepted but ignored, so e.g., %hd is 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 limit 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.

vTraceVPrintF

void vTraceVPrintF(traceString chn, const char* fmt, va_list vl)

vTracePrintF variant that accepts a va_list. This can be used to integrate with existing logging solutions. See vTracePrintF documentation for further details.

Example:

traceString debugChannel = xTraceRegisterString("Debug");
...
void vDebugPrintF(char* fmt, ...)
{
	va_list vl;

	va_start(vl, fmt);
	vTraceVPrintF(debugChannel, fmt, vl);
	va_end(vl);
}
                  

vTracePrint

void vTracePrint(traceString chn, const char* str)

A faster version of vTracePrintF for logging strings without data arguments.

Example:

traceString chn = xTraceRegisterString("MyChannel");
...
vTracePrint(chn, "Hello World!");
                  

xTraceRegisterString

traceString xTraceRegisterString(const char* name)

Storing strings generally require that they are assigned a traceString handle, provided by this function. Duplicates are avoided by reusing any previous handle, if there already is an identical string saved.

traceString chn = xTraceRegisterString("MyChannel");
...
vTracePrint(chn, "Hello World!");
vTracePrintF(chn, "Value: %d", myValue);
                

vTraceConsoleChannelPrintF

void vTraceConsoleChannelPrintF(const char* fmt, ...)

Wrapper for vTracePrint, intended to be used as a drop-in replacement for printf and similar console print functions, e.g. in a debug logging macro.

// Replace this old logging macro
// #define LogString uart_printf
                  
// Log to Tracealyzer instead                  
#define LogString vTraceConsoleChannelPrintF 
...                  
LogString("My value is: %d", myValue);
                

vTraceSet...Name

void vTraceSetQueueName(void* object, const char* name)

void vTraceSetSemaphoreName(void* object, const char* name)

void vTraceSetMutexName(void* object, const char* name)

void vTraceSetEventGroupName(void* object, const char* name)

void vTraceSetStreamBufferName(void* object, const char* name)

void vTraceSetMessageBufferName(void* object, const char* name)

Functions for setting names of kernel objects, for display in Tracealyzer.

Parameter object: pointer to the kernel object that shall be named (e.g., a queue).
Parameter name: the name to display in Tracealyzer.

xTraceSetISRProperties

traceHandle xTraceSetISRProperties(const char* name, uint8_t priority)

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 level */
traceHandle Timer1Handle;

void main()
{
	Timer1Handle = xTraceSetISRProperties("ISRTimer1", PRIO_ISR_TIMER1);
	...
}

void ISR_handler()
{
	vTraceStoreISRBegin(Timer1Handle);
	...
	vTraceStoreISREnd(0);
}
                

vTraceStoreISRBegin

void vTraceStoreISRBegin(traceHandle handle);

Registers the beginning of an Interrupt Service Routine, using a traceHandle provided by xTraceSetISRProperties.

Example:

#define PRIO_ISR_TIMER1 3 /* the hardware priority level */
...
traceHandle Timer1Handle = xTraceSetISRProperties("ISRTimer1", PRIO_ISR_TIMER1);
...
void ISR_handler()
{
	vTraceStoreISRBegin(Timer1Handle);
	...
	vTraceStoreISREnd(0);
}
                

vTraceStoreISREnd

void vTraceStoreISREnd(int isTaskSwitchRequired)

Registers the end of an Interrupt Service Routine.

The parameter pendingISR indicates if the interrupt has caused 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_ISR_TIMER1 3 /* the hardware priority level */
...
traceHandle Timer1Handle = xTraceSetISRProperties("ISRTimer1", PRIO_ISR_TIMER1);
...
void ISR_handler()
{
  signed BaseType_t xHigherPriorityTaskWoken;
  vTraceStoreISRBegin(Timer1Handle);

  /* Wakes up a pending task, causing a task-switch */
  xSemaphoreGiveFromISR(xSemaphore, &xHigherPriorityTaskWoken);
  vTraceStoreISREnd(xHigherPriorityTaskWoken);
}
				

vTraceInstanceFinishedNow

void vTraceInstanceFinishedNow(void)

Creates an event that ends the current task instance at this very instant.
This informs the viewer to split the current fragment at this point and begin a new actor instance, even if no task-switch has occurred.

vTraceInstanceFinishedNext

void vTraceInstanceFinishedNext(void)

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.

vTraceSetRecorderDataBuffer

void vTraceSetRecorderDataBuffer(void* pRecorderData)

The recorder supports three modes of allocating the trace data structure: static, dynamic and custom allocation mode. In custom allocation mode (TRC_RECORDER_BUFFER_ALLOCATION_CUSTOM) you are expected to declare and allocate the buffer yourself, intended for maximum control. If you combine this with linker directives, you can place the recorder data in a specific memory location. Then use vTraceSetRecorderDataBuffer to register the buffer in the recorder, before calling vTraceEnable.

To declare a trace buffer, use the macro TRC_ALLOC_CUSTOM_BUFFER. This is portable and independent of recording mode. Moreover, it is ignored if you don't use custom allocation mode.

Example:

/* Allocate, typically in global context */
TRC_ALLOC_CUSTOM_BUFFER(myTraceBuffer)

/* Register the buffer, before vTraceEnable */
vTraceSetRecorderDataBuffer(&myTraceBuffer);

vTraceEnable(TRC_INIT);
                

xTraceGetLastError

char* xTraceGetLastError(void)

Returns the first registered error in the recorder, if any, as a string. The return value is NULL if no errors have been registered. The errors reported here are typically from internal "assert" statements within the recorder code, that checks the configuration and inputs.

Any error or warning is also shown in Tracealyzer when loading the trace, assuming a trace could be created. In streaming mode, this however requires User Events to be enabled (see trcConfig.h).

To get more information about the context of the error, put a breakpoint in prvTraceError and/or prvTraceWarning. Then start a debug session and reproduce the problem. Then check the call stack in your debugger to see what recorder operation that resulted in the error.

vTraceClearError

void vTraceClearError(void)

Clears any internal errors from the recorder (see also xTraceGetLastError).

vTraceSetFrequency

void vTraceSetFrequency(uint32_t frequency)

Registers the clock rate of the timestamping time source. Allows for overriding the default value (TRC_HWTC_FREQ_HZ) in case this would be incorrect for your setup.

Note: In snapshot mode, the frequency value is divided by the TRC_HWTC_DIVISOR, and may therefore seem lower than expected in the Trace Overview.

xTraceIsRecordingEnabled

int xTraceIsRecordingEnabled(void)

Returns true (1) if the recorder is enabled (i.e. is recording), otherwise 0.

vTraceSetFilterMask

void vTraceSetFilterMask(uint16_t filterMask)

Note: This is disabled in FreeRTOS v7.3 since it uses an incompatible data type for object numbers.

Sets the Filter Mask, used for filtering the events based on the object they refer to, such as tasks, queues, semaphores and mutexes. 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.

The parameter filterMask should include one or several Filter Group IDs (FilterGroup0 .. FilterGroup15). Multiple filter groups can be included using a bitwise OR expression, for example: FilterGroup0 | FilterGroup3 | FilterGroup6.

Every kernel object is assigned to a specific filter group. By default, all kernel object are assigned to FilterGroup0, but this can be changed using vTraceSetFilterGroup.

An event is included if the following bitwise AND condition is true:

Object.FilterGroup & FilterMask != 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]
                

vTraceSetFilterGroup

void vTraceSetFilterGroup(uint16_t filterGroup)

Note: This is disabled in FreeRTOS v7.3 since it uses an incompatible data type for object numbers.

Sets the Filter Group for kernel objects created after this point, such as tasks, queues, semaphores and mutexes. Together with vTraceSetFilterMask, this allows you to filter the events based on the objects they refer to. 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. And by grouping related objects into filter groups, you can exclude whole subsystems from the trace simply by changing the filter mask.

The parameter filterGroup should be one of the 16 predefined filter groups IDs, named FilterGroup0 .. FilterGroup15, corresponding to each bit in the filter mask. The provided ID is stored and assigned to every kernel object created after this point, including tasks, queues, semaphores and mutexes. You typically call vTraceSetFilterGroup at multiple occations in your startup code to divide your kernel objects into multiple filter groups.
Note: We don't recommend filtering out tasks, as this can affect the visualizations in unexpected ways. It can however be motivated for frequent, periodic tasks with short execution time. To avoid filtering out the Idle task by accident, make sure to call vTraceSetFilterGroup(FilterGroup0) before starting the RTOS scheduler in order to restore the default assignment.

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
...
vTraceSetFilterMask( BASE | CAN_EVENTS );
                

Extended API for Snapshot Mode

This section describes the extended API for snapshot mode, with extra functions that are typically only needed for more advanced setups. The extended API is not self-contained but should be used together with the Common API when in snapshot mode.

xTraceGetTraceBuffer

void* xTraceGetTraceBuffer(void)

Returns a pointer to the snapshot trace buffer, for programmatic access. See also uiTraceGetTraceBufferSize.

Example:

/* Save the snapshot trace buffer */
f = fopen("mytrace.bin","wb");
ptr = xTraceGetTraceBuffer();
size = uiTraceGetTraceBufferSize();
vTraceStop();
fwrite(ptr, size, 1, f);
fclose(f);
vTraceClear();
vTraceEnable(TRC_START);
                

uiTraceGetTraceBufferSize

uint32_t uiTraceGetTraceBufferSize(void)

Returns the size of the snapshot trace buffer, in bytes. See also xTraceGetTraceBuffer.

Example:

/* Save the snapshot trace buffer */
f = fopen("mytrace.bin","wb");
ptr = xTraceGetTraceBuffer();
size = uiTraceGetTraceBufferSize();
vTraceStop();
fwrite(ptr, size, 1, f);
fclose(f);
vTraceClear();
vTraceEnable(TRC_START);
                

vTraceSetStopHook

void vTraceSetStopHook(TRACE_STOP_HOOK stopHookFunction)

Sets a callback function to be called when the recorder is stopped. The data type TRACE_STOP_HOOK is defined as typedef void(TRACE_STOP_HOOK)(void).

Example:

void mySaveTraceFunction(void);
...
vTraceSetStopHook(mySaveTraceFunction);
                  

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.

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).

vTraceClear

void vTraceClear(void)

Resets the recorder. This is not needed in the normal initialization, only if you want a clean restart of the tracing while the system is running.

xTraceRegisterUBChannel

traceUBChannel xTraceRegisterUBChannel(traceString channel, traceString formatStr)

The separate user event buffer (UB) allows for storing User Events separately from other events, e.g., RTOS events. Thereby you can get a much longer history of user events as they don't need to share the buffer space with more frequent events. User events in the UB are structured as UB channels, which contain a channel name and a default format string.

This function looks up an existing UB channel matching the parameters, or registers a new UB channel if no match is found.

The parameter channel is the name of the UB channel, that is to be shown in Tracealyzer. The parameter formatStr is a format string or a plain event name, that is to be used for all events stored on this channel using vTraceUBEvent and vTraceUBData. Both parameters are traceStrings, obtained using xTraceRegisterString.

Returns a channel handle for use in vTraceUBEvent and vTraceUBData.

Events and data arguments are written using vTraceUBEvent and vTraceUBData. They are designed to provide efficient logging of repeating events, using the same format string within each channel.

Examples:

traceString chn1 = xTraceRegisterString("Channel 1");
traceString fmt1 = xTraceRegisterString("Event!");
traceUBChannel UBCh1 = xTraceRegisterUBChannel(chn1, fmt1);

traceString chn2 = xTraceRegisterString("Channel 2");
traceString fmt2 = xTraceRegisterString("X: %d, Y: %d");
traceUBChannel UBCh2 = xTraceRegisterUBChannel(chn2, fmt2);

// Results in "[Channel 1] Event!"
vTraceUBEvent(UBCh1);

// Results in "[Channel 2] X: 23, Y: 19"
vTraceUBData(UBCh2, 23, 19);
                

Set TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER to 1 in trcSnapshotConfig.h to enable the UB mode and related functions.

Only a certain number of UB channels are allowed, by default 32, defined by TRC_CFG_UB_CHANNELS.

The buffer uses ring-buffer semantics, meaning that older events are overwritten if the buffer gets full. The buffer size is defined by TRC_CFG_SEPARATE_USER_EVENT_BUFFER_SIZE, by default 200 slots (x 4 byte each).

When using the UB, if using ring-buffer mode also for the main event buffer (quite typical), the earliest part of the trace often only contains User Event data (from the UB) and no RTOS events (since overwritten). Tracealyzer displays such intervals using a placeholder "task" labeled "Unknown Actor".

You may use vTracePrintF and vTracePrint also in UB mode, as they are then rerouted to the UB instead of the main event buffer. vTracePrintF then looks up the correct UB channel based on the provided channel name and format string, or creates a new UB channel if no match is found (combination of channel name and format string). To avoid running out of UB channels, the format string should therefore not contain "random" messages but mainly format specifiers. Random strings should be stored using %s and with the string as an argument.

vTraceUBData

void vTraceUBData(traceUBChannel channel, ...)

Writes a user event to the separate user event buffer (UB), with data arguments. The parameter channel is obtained from xTraceRegisterUBChannel and specifies the format string for this event.

In UB mode, user events are stored separately from other events, e.g., RTOS events. Thereby you can get a much longer history of user events as they don't need to share the buffer space with more frequent events.

Set TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER to 1 in trcSnapshotConfig.h to enable the UB mode and related functions.

Examples:

traceString chn2 = xTraceRegisterString("Channel 2");
traceString fmt2 = xTraceRegisterString("X: %d, Y: %d");
traceUBChannel UBCh2 = xTraceRegisterUBChannel(chn2, fmt2);

// Results in "[Channel 2] X: 23, Y: 19"
vTraceUBData(UBCh2, 23, 19);
                

vTraceUBEvent

void vTraceUBEvent(traceUBChannel channel)

Writes a user event to the separate user event buffer (UB), without data arguments. The parameter channel is obtained from xTraceRegisterUBChannel and specifies the format string for this event. Since this function is intended for basic events without data arguments, the "format string" set in the UB channel should not contain any format specifiers, but is simply a string.

In UB mode, user events are stored separately from other events, e.g., RTOS events. Thereby you can get a much longer history of user events as they don't need to share the buffer space with more frequent events.

Set TRC_CFG_USE_SEPARATE_USER_EVENT_BUFFER to 1 in trcSnapshotConfig.h to enable the UB mode and related functions.

Examples:

traceString chn1 = xTraceRegisterString("Channel 1");
traceString fmt1 = xTraceRegisterString("Event!");
traceUBChannel UBCh1 = xTraceRegisterUBChannel(chn1, fmt1);

// Results in "[Channel 1] Event!"
vTraceUBEvent(UBCh1);