Printing to a Console with swmTrace
We generally recommend establishing a method to view the internals of an application early on in development (before problems arise) to ensure that everything is working as expected. Comparing console outputs between successful and failed outcomes can help pinpoint problems. The swmTrace module provides data printing capability and is described in the RSL15 Firmware Reference. It supports the commonly known printf()
function to allow seamless printing to a PC console and a series of logging functions whose output characteristics are based on the logging level selected. The source code for swmTrace is available in the installation folder under firmware\source\lib\swmTrace. There is also a sample application called swmTrace_logger, which demonstrates the usage of the swmTrace library.
onsemi IDE Setup Requirements
newlib-nano is an open-source C library enabled in all sample applications. We strongly recommend that you enable it in the onsemi IDE when using swmTrace, by performing the following steps:
- Navigate in the onsemi IDE to Properties > C/C++ Build > Settings > Cross ARM C Linker > Miscellaneous.
- Check the Use newlib-nano checkbox.
Enabling newlib-nano in the onsemi IDE also minimizes the flash and RAM requirements of applications.
Printing Methods
The swmTrace module supports two printing methods:
- SEGGER Real Time Trace (RTT)
- UART
SEGGER® RTT works over JTAG (SWD) and pairs with the onsemi IDE's RTT viewer plugin. This is a specific view found under in the Window > Show View menu under onsemi, and features a console with controls for clearing the console, connecting once, stopping a connection, and enabling automatic reconnection. It remains connected in Sleep Mode. You must have the J-Link software installed to use this mode. Additional settings are available in the Window > Preferences menu.
UART works simply by transmitting characters out of the UART interface. Only the UART transmit pin and a ground pin are required to receive the signal. The UART is especially helpful in later stages of product development when the SWD pins might not be accessible, and the UART interface is not needed for host controller interface test communications with the Bluetooth hardware. No standard PC viewers for UART data exist, so programs such as Hyperterminal or other terminal programs are commonly used. The UART never establishes a connection with the PC; thus it can transmit immediately after waking from sleep (with minimal initialization).
NOTE: UART support using GPIOs 5 and 6 is possible with the onboard J-Link interface on the RSL15 Evaluation and Development Board. See the Evaluation and Development Board manual for more information.
The functions used most frequently are the various swmLog
functions, which allow you to output only trace messages if a particular log level has been selected. The log levels available are VERBOSE, INFO, WARNING, ERROR, and FATAL. For example, if you have some error messages being printed using swmLogError
, some info messages using swmLogInfo
, and some additional logging using swmLogVerbose
, the amount of text output can be controlled by changing the selected log level, rather than actually commenting out portions of code.
Indicators for a test pass and fail are also available. The swmTrace_printf
function always prints, regardless of the log level selected. Before using any swmTrace functions, the swmTrace_init
function needs to be called.
Blocking Versus Non-Blocking Modes
In blocking mode, the swmLog
function does not return until the output buffer is available. In low throughput scenarios, the buffer is almost always available, so little or no blocking occurs. In high throughput scenarios, the buffer might not always be available, so blocking might occur. Blocking mode is useful to ensure that the output data stream is not corrupted in high throughput scenarios; however, due to the swmLog function blocking, real-time performance of the system might be affected.
In non-blocking mode, the swmLog
function always returns immediately, whether the buffer is available or not. In low throughput scenarios, the buffer is almost always available, so the data stream is usually not corrupted. In high throughput scenarios, the buffer might not always be available, so the data stream might be corrupted. Non-blocking mode is useful to help to maintain the real-time performance of the system; however, due to the swmLog function not blocking, the data stream might be corrupted.
Different versions of the library are available for each mode, so the appropriate one can be linked in to your application accordingly.