ETB trace

The experimental Embedded Trace Buffer (ETB) library enables the tracing of executed instructions and storing them in a dedicated RAM buffer. Traces are generated by the core’s Embedded Trace Macrocell (ETM) unit and are captured without CPU intervention. Currently, the nRF91 series devices are supported.

The ETB RAM buffer behaves as a circular buffer of 2 KB. New traces overwrite older traces once the buffer is full. The application reads the captured traces using the library’s APIs. See ARM CoreSight documentation for more information about the various CoreSight components, trace format, and trace processing. The ETB trace library is used in the Memfault sample that demonstrates how to read out the ETB buffer and store the data in a coredump in case of a system crash.

Configuration

To enable the library, set the CONFIG_ETB_TRACE Kconfig option to y. By default, the library automatically starts tracing at the earliest stage in the Zephyr boot sequence to capture instructions as early as possible. To disable auto-start tracing, set the CONFIG_ETB_TRACE_SYS_INIT Kconfig option to n.

To capture ETM-generated traces and store them in ETB, enable the SoC’s trace and debug system. This increases power consumption by serval milliamps. The library provides an option (CONFIG_ETB_TRACE_LOW_POWER) to reduce power consumption. It disables the debug system when the CPU goes to idle. This is a feature that requires the code to be executed both on entry and exit of the CPU idle state and introduces latency to the system. It might also have other unknown side effects on the system.

Usage

To initialize the library and start tracing, call the etb_trace_start() function. The function performs the following:

  1. Configures the ETM.

  2. Sets up the Advanced Trace Bus (ATB) funnels and replicator.

  3. Enables the ETB.

Traces are now written continuously to the ETB RAM.

To stop trace capture, use the etb_trace_stop() function.

The captured traces can now be read out using the etb_data_get() function. The ETB buffer can hold the maximum of 2 KB of data.

API documentation

Header file: include/debug/etb_trace.h
Source files: subsys/debug/etb_trace/
group etb_trace

Library for capturing instruction traces to Embedded Trace Buffer.

Defines

ETB_BUFFER_SIZE

Functions

void etb_trace_start(void)

Set up debug unit and start ETB tracing.

void etb_trace_stop(void)

Stop ETB tracing.

size_t etb_data_get(uint32_t *buf, size_t buf_size)

Retrieve ETB trace data to buffer.

Parameters:

  • buf – [out] Output buffer.

  • buf_size – [in] Size of output buffer in bytes.

Return values:

  • Number – of bytes of trace data returned in buf.

  • -EINVAL – On invalid input parameters.