Modem traces

The modem trace APIs in the Modem library are used to retrieve binary trace data from the modem core. The application is responsible for forwarding the trace data to a host computer, where it can be collected with the Cellular Monitor PC tool to extract PCAP data, or to save them to file for further inspection by Nordic Semiconductor.

In the nRF Connect SDK, the Modem library integration layer takes care of retrieving and forwarding the trace data, for example to a computer or to a non-volatile memory.

Enabling modem traces

To enable traces the application must initialize the Modem library with a non-zero trace region size. The trace output from the modem can be toggled at runtime using the AT command %XMODEMTRACE, which can also be used to change the trace output level. For more information, see the Modem trace activation %XMODEMTRACE section in the nRF9160 AT Commands Reference Guide or the same section in the nRF91x1 AT Commands Reference Guide depending on the SiP you are using.

In the nRF Connect SDK, the Modem library integration layer offers a dedicated function to simplify the task of enabling and disabling the trace output, and setting the trace level.

Fetching modem traces

Modem traces are retrieved by the application and output to a trace medium, typically UART. You can call the nrf_modem_trace_get() function to retrieve traces from the Modem library.

The trace data, containing multiple fragments, must be processed in order, starting from the first array index.

Once the trace data is processed, the application must call the nrf_modem_trace_processed() function to release the memory allocated in the trace memory area. If the trace data is processed in fragments, this can be split into multiple calls, for example, one call for each fragment of processed data.

Modem library trace processing

Processing modem traces

The application must call the nrf_modem_trace_processed() function as it processes the trace data to inform the Modem library that the trace data has been handled and can be released. It is not necessary that the application has processed a whole trace fragment before calling the nrf_modem_trace_processed() function. To maximize the availability of the shared memory in the trace region, the application must call the nrf_modem_trace_processed() function frequently as soon as some bytes are processed. Hence, the nrf_modem_trace_processed() function must be called with the total number of bytes in the trace fragments before making a new call to the nrf_modem_trace_get() function.

An example is shown in the following figure:

Modem library asynchronous trace processing

Tracing and modem faults

When a fault occurs in the modem and traces are enabled, the modem will send a coredump using the trace interface. The nrf_modem_trace_get() function returns trace fragments until there are no more fragments to process. In the case where there are no more trace fragments after a modem coredump is complete, the nrf_modem_trace_get() function returns -NRF_ENODATA as shown in the following figure:

Modem library coredump trace sequence

Note

The nrf_modem_trace_get() function returns with an error when the modem is uninitialized or shut down, or when there is no more trace data after a coredump. In these cases, the application must wait for the modem to be reinitialized before calling the nrf_modem_trace_get() function again.