.. _etb_trace:

ETB trace
#########

.. contents::
   :local:
   :depth: 2

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 :ref:`memfault_sample` 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 :kconfig:option:`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 :kconfig:option:`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 (:kconfig: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 :c:func:`etb_trace_start` function.
The function performs the following:

#. Configures the ETM.
#. Sets up the Advanced Trace Bus (ATB) funnels and replicator.
#. Enables the ETB.

Traces are now written continuously to the ETB RAM.

To stop trace capture, use the :c:func:`etb_trace_stop` function.

The captured traces can now be read out using the :c:func:`etb_data_get` function.
The ETB buffer can hold the maximum of 2 KB of data.


API documentation
*****************

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

.. doxygengroup:: etb_trace
   :project: nrf
   :members: