Tracealyzer--Integrated support for SEGGER J-Link
File Structure
The recorder consists of the below files and directories. Some code is specific for the snapshot or streaming modes, but we recommend including all these source files in your build. Any code that is not used by the selected recording mode, is automatically excluded by the preprocessor when compiling the recorder. Check the Recorder Integration section for a step-by-step guide of how to integrate the recorder in your system.
| /config | trcConfig.h | The main configuration of the recorder library. |
| /config | trcSnapshotConfig.h | Specific configuration for the snapshot mode. |
| /config | trcStreamingConfig.h | Specific configuration for the streaming mode. |
| /include | trcRecorder.h | The public API of the recorder. Needs to be included from FreeRTOSConfig.h, as described in the integration guide. |
| /include | trcHardwarePort.h | All hardware dependencies. Contains several predefined hardware ports, including ARM Cortex-M, PIC32, Renesas RX etc. |
| /include | trcKernelPort.h | FreeRTOS-specific definitions, most notably the trace hook definitions. |
| /include | trcPortDefines.h | Various constants for the configuration files. |
| /streamports | JLink_RTT | A stream port for SEGGER J-Link debug probes. See trcStreamingPort.h for relevant settings. |
| /streamports | TCPIP | A stream port for TCP/IP network connections. The example provided is for lwIP. Defined by trcStreamingPort.h. |
| /streamports | USB_CDC | A stream port for USB CDC connections. The example provided is for STM32, with USB drivers generated by STM32Cube. Defined by trcStreamingPort.h. |
| / | trcSnapshotRecorder.c | Implementation of snapshot recording mode. |
| / | trcStreamingRecorder.c | Implementation of streaming recording mode. |
| / | trcKernelPort.c | FreeRTOS-specific functions and definitions. |
Integrating the Recorder
Follow the steps below to integrate the trace recorder in an existing project, using snapshot mode with default settings. To use streaming mode, some additional steps are needed.
Step 1. Make sure your project uses FreeRTOS version 7.3 or later. If using an older version of FreeRTOS, upgrading is usually just a drop-in replacement, since backwards-compatible.
Step 2. Locate the trace recorder library in the Tracealyzer installation directory. On Windows, this is found in <Program Files>\Percepio\Tracealyzer 4\FreeRTOS\TraceRecorder. Copy this directory to suitable location in your code repository, e.g. next to FreeRTOS.
Step 3. Add all three .c files to your project. The files are stripped of any unused code by the preprocessor, based on the recorder configuration.
Step 4. Copy all config headers to a suitable location your project structure, e.g., next to FreeRTOSConfig.h. It is not advised to share these between multiple projects.
Step 5. Add the include directory to your compilers "include paths" to ensure the header files are found, or just copy the headers files to an existing directory where you have other header files for your project.
Step 6. Configure TRC_CFG_HARDWARE_PORT and TRC_CFG_FREERTOS_VERSION in trcConfig.h to reflect your system. Also check the settings in trcSnapshotConfig.h, especially TRC_CFG_NTASK, TRC_CFG_NQUEUE etc. Read more in Configuration and in Tuning the Snapshot Configuration.
Step 7. In your FreeRTOSConfig.h, ensure that you have the following setting:#define configUSE_TRACE_FACILITY 1
This is the "master switch" for the trace recorder. If you set this to 0, the trace recorder is completely disabled and excluded from the build.
Step 8. Insert the following in FreeRTOSConfig.h, in the end.
/* Integrates the Tracealyzer recorder with FreeRTOS */
#if ( configUSE_TRACE_FACILITY == 1 )
#include "trcRecorder.h"
#endif
Step 9. Call vTraceEnable(TRC_START) in your main function to initialize and start the recording. This must be after the initial hardware setup, but beforeany RTOS objects (tasks etc.) have been created.
For ARM Cortex-M devices, the recorder needs the ARM's CMSIS library. To ensure this is accessible from the recorder code, we recommend including your processor's header file (e.g., "lpc17xx.h", "stm32f4xx.h", "board.h", etc.) from your trcConfig.h.
If you run into problems, please refer to the Troubleshooting section.
Setting up streaming
Assuming you have followed the recommended steps for basic integration, the following additional steps are needed to enable streaming.
- In trcConfig.h, set TRC_CFG_RECORDER_MODE to TRC_RECORDER_MODE_STREAMING.
- Decide on which stream port to use, i.e., how to transfer the trace data from target to host.
- Specify the stream port to use. This is done by updating your compiler's include search paths to include the directory of your trcStreamingPort.h (e.g, "/streamports/Jlink_RTT/include").
- If the selected stream port contains any .c files, those should also be added to your project.
- In your vTraceEnable call, for streaming you should normally use TRC_INIT or TRC_START_AWAIT_HOST. See the vTraceEnable documentation for details.
If you run into problems, please refer to the Troubleshooting section.
Making a snapshot
This section describes how to upload the trace data from the target system to Percepio Tracealyzer, when using snapshot mode.
Integrated support for SEGGER J-Link
Percepio Tracealyzer supports SEGGER J-Link and J-Link compatible debuggers directly (e.g. Atmel SAM-ICE). The J-Link integration works independently of your IDE and supports both snapshot trace (see below) and streaming.
To upload a snapshot using a SEGGER J-Link, select "Read Trace (Snapshot)" in the "J-Link" menu. The trace is then opened in Percepio 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 Percepio Tracealyzer sessions. Typical values are 0x0, 0x10000000 or 0x20000000 as start address and 0x10000 or 0x20000 as size (64 KB or 128 KB). J-Link compatible debug probes also include Atmel SAM-ICE and many built-in debug interfaces on demonstration/evaluation boards (where there is a USB connection directly to the board). Look for a SEGGER J-Link label on the board.