Troubleshooting
In order to get the best result when tracing, please consider the following:
- It is advised to call EventRecorderInitialize() early in main, before creating any kernel objects, but make sure this is called after the core clock (i.e., the timestamping source) has been configured.
- Start the recording session at the system startup. While it is possible to connect to a running system and receive a trace, it will lack information about all previous events.
- Use constant strings instead of local (stack) variables when registering object names. This way Percepio Tracealyzer can read the names from target memory even when it is not receiving all create events.
- If the time scale presented in Percepio Tracealyzer seems to be scaled incorrectly, verify the Core Clock setting, as explained in Step 7 in the Enabling Trace guide.
- If the debug probe used is not fast enough there may be overflows, i.e., that the Event Recorder is not able to keep up with the stream of events. Percepio Tracealyzer will generate a warning if this is detected and mark the location in the trace where the overflow was detected. The result is normally a gap in the trace, during which the last logged task seem to execute and may seem to have an unusually long execution time. To avoid such problems, try the following:
- Increase the size of the Event Recorder buffer (see Step 3 in the Enabling Trace guide).
- Increase the clock frequency of the debug interface (see Step 6 in the Enabling Trace guide.
- Try a faster debug probe - a ULINKplus or ULINKpro is recommended.
- Keil µVision allows for filtering of events in order to reduce the amount of data produced. But assuming your debug probe can manage the data rate, we recommend recording all events. This since Percepio Tracealyzer does some pretty advanced analysis of the trace and calculate the states of objects based on the operations observed. If you want to filter the trace in runtime, don't exclude kernel events related to task scheduling. You may exclude API calls, if excluding ALL events related to that kind of object. Otherwise, if some kernel object is partially traced, it may be displayed incorrectly.
Troubleshooting
If you get build errors, make sure that TRC_CFG_FREERTOS_VERSION is specified correctly in trcConfig.h.
Runtime errors in the recorder are often captured by the ASSERT macros. They call prvTraceError or prvTraceWarning if an internal error is detected in the recorder code, e.g., due to incorrect parameters or configuration. This attempts to save the error message in the trace and then stops the recorder. The error message is then presented when opening the trace.
But if no error message is presented, or you like to see the context of the error, it is advised to put a breakpoint inside prvTraceError and/or prvTraceWarning. Note that this function has two implementations, one in trcSnapshotRecorder.c and another in trcStreamingRecorder.c.
You may also call xTraceGetLastError() in order to obtain any error messages in your target code. This returns NULL if no error messages are available.
In case you have problems connecting to the recorder in streaming mode, or it reports lost events, make sure to check the following.
- Double-check the streaming settings in Percepio Tracealyzer (File -> Settings). Also check that the stream port settings match where relevant.
- If using the SEGGER J-Link RTT streaming, see this FAQ post on our website about J-Link RTT connections and performance issues. But a general advice is to install the latest J-Link drivers from SEGGER, after Tracealyzer has been installed, and make sure the J-Link drivers update all your development tools, both your IDE and Tracealyzer, so the use the same version of the J-Link driver. Moreover, if the J-Link driver wants to update the J-Link firmware, it is advised to allow that.
- Put a breakpoint in prvIsValidCommand() in trcStreamingRecorder.c. Then press "Start Recording" in Percepio Tracealyzer, which will connect and send two commands (Stop, Start). If the breakpoint is not hit, no data is received from the connection. If this function would return 0, the received data is not a valid command and probably junk data.
- Is the trace control task (TzCtrl) executing? Put a breakpoint in the start of this task to verify this. Note that TzCtrl normally is started automatically from vTraceEnable.
- Is your streaming interface sufficiently fast to handle the data produced? If not, there may be lost events or blocking in the recorder, depending on your recorder settings. If blocking mode is used, this may affect the timing of your system, but ensures that data is not lost. In case of data loss, Tracealyzer will show a counter for "dropped events" in the "Connect to target system" window.
- Make sure the trace buffer is sufficiently large. If using J-Link streaming, you find the buffer size setting in trcStreamingPort.h, otherwise in trcStreamingConfig.h.
- In most stream ports except J-Link, the trace control task (TzCtrl) performs the writing to the streaming interface. In such cases, try reducing TRC_CFG_CTRL_TASK_DELAY to make it execute more frequently. Especially if you don't have enough RAM for a larger buffer.
- If your system is highly loaded, you might need to increase the priority of the trace control task to make sure it runs periodically. This is done by increasing TRC_CFG_CTRL_TASK_PRIORITY. This is relevant for stream ports that use the internal paged buffer, e.g., TCP/IP and UDB CDC, but not J-Link.
- Check if you get any warnings related to TRC_STREAM_PORT_WRITE_DATA or TRC_STREAM_PORT_READ_DATA. These define the I/O functions used by the stream port to read commands and write trace data, and should return zero (0) on success. Any other return values result in warnings (e.g. "TRC_STREAM_PORT_WRITE_DATA returned error (!= 0)"). This can be checked by calling xTraceGetLastError() (returns a string, or NULL if no error), or by placing a breakpoint in prvTraceWarning().
What if the trace can be recorded, loaded into Tracealyzer but doesn't contain any task-switches or kernel calls? This typically means that the trace macro definitions are not included into the kernel, so the recorder is not notified of the events. Make sure you have included trcRecorder.h from your FreeRTOSConfig.h, as described in the integration guide.
And finally, don't hesitate to contact [email protected] if you need assistance.