By default, the Tracealyzer Recorder Library allows for tracing two kinds of information: (1) RTOS kernel events such as context-switches and RTOS API calls, and (2) User Events in the application code, such as debug logging, state changes and variable values.

With the release of Tracealyzer 4.2.9 we added a third way to trace your application, with recorder extensions. These self-contained modules make it easy to add tracing of library function calls, such as middleware APIs, driver APIs, or any other important functions you would like to trace. An example screenshot from Tracealyzer is shown below, where the “Secure Socket” API in FreeRTOS has been traced using the extension system.

This does not require any code changes in targeted functions. Only a single #include line needs to be added in application source code files using the traced API. The rest is handled by the preprocessor and trace recorder, based on definitions in the extension.

Example code included

Tracealyzer includes two example extensions that we have created for FreeRTOS, allowing for tracing calls to some of the functions in aws_secure_sockets.h (SOCKETS_Connect, SOCKETS_Send, SOCKETS_Recv) and aws_wifi.h (WIFI_On, WIFI_Off, WIFI_ConnectAP). Each extension has two components, a header file with target-side definitions and an XML file with host-side metadata that tells Tracealyzer how to interpret the events, e.g. as an I/O operation. This way, Tracealyzer understands the meaning of the events and includes them in relevant views, such as the I/O Plot.

To enable tracing with these extensions in FreeRTOS, make sure you are running Tracealyzer 4.2.9 or later and follow these steps:

1. Integrate the trace recorder library as described in the Tracealyzer User Manual, and configure it for streaming mode.
2. Open include/trcExtensions.h and set TRC_CFG_EXTENSION_COUNT to 2.
3. Search for all files in your application containing #include “aws_secure_sockets.h” or #include “aws_wifi.h”.
4. In these files, add #include “trcExtensions.h” as illustrated below, except in the .c files containing the targeted functions, i.e. aws_secure_sockets.c and aws_wifi.c. Do not change those.
   #include ...
#include "aws_secure_sockets.h" /* The traced API */
#include "trcExtensions.h" /* Should be after, or last */
5. Recompile your code and run a Tracealyzer recording in streaming mode. The new function call events should appear in the trace.

In case you get compiler errors about “duplicate definitions” or similar, you have most likely included trcExtensions.h also in the .c files implementing the traced APIs (i.e. aws_secure_sockets.c or aws_wifi.c), perhaps indirectly via a header file they include. Remove those include statements in that case.

The include of trcExtensions.h can remain in the code base, if desired. This leaves the trace wrapper functions available even when tracing is disabled, but as they are then only calling through to the original functions they will most likely be eliminated by compiler optimizations.

How it Works

An extension is typically made for a specific API, i.e. a group of related functions, such as a device driver or middleware library, or a specific module of your application. The automatic function tracing relies on preprocessor definitions in the extension header file, that redefine the selected function names to refer to a corresponding trace wrapper function. The wrapper function calls the trace recorder library to store an event about the call, and then calls the original function. Any return value is propagated back, which makes the tracing functionally transparent.

Easy to integrate and distribute

Tracealyzer recorder extensions are self-contained and easy to integrate, which makes them convenient for distribution. Embedded software vendors can develop and provide custom Tracealyzer extensions for their customers, without having to integrate instrumentation code in their existing code base.

A more detailed description of the extension mechanism can be found in Percepio App Note PA-027.

Learn More

If you have not tried Tracealyzer before, visit Download Tracealyzer and sign up for an evaluation. An example trace is included, so you can begin exploring the capabilities of Tracealyzer immediately.

Also make sure to check out our RTOS Debug Portal, with many articles and hands-on examples.

In case you have any questions, don’t hesitate to contact us at support@percepio.com.