Telemetry, Logging & Probes API

Sound Open Firmware (SOF) incorporates a multi-tiered diagnostic, tracing, and telemetry architecture. The subsystem provides comprehensive visibility into real-time firmware execution, pipeline audio quality, hardware performance metrics, and system health with minimal latency and zero audio glitching.

Architecture & Subsystem Overview

Diagnostic data in SOF is partitioned across four primary functional domains:

1. Host DMA Tracing & Dictionary Logging: High-throughput binary logging via dedicated host DMA streams, early bootloader checkpoint trace codes (TRACE_BOOT_*), and panic crash dumps. Log strings, file names, and line numbers are stripped at compile time and indexed into a static dictionary (.ldc file). The DSP transmits only compressed 32-bit tokens and parameters, which user-space host tools (sof-logger, dut-monitor, sof_probe_client.py) decode in real time.

2. Audio Probes & Stream Tap Points: Dynamic non-intrusive tap points attached to pipeline interconnect buffers. Probes allow host developers to extract uncompressed PCM audio at any intermediate stage in the signal processing graph (e.g. pre-EQ, post-AEC) or inject reference audio directly into running pipelines without reconfiguring topologies.

3. Hardware Telemetry & Performance Monitoring: Real-time CPU cycle accounting, system tick counters, active power state transitions, and component cycle budgets published to shared memory windows (SRAM Window 0 and Window 3). Host drivers and performance monitors read these registers to measure per-core DSP load and detect pipeline underruns.

4. Abstract Debug Streams & Low-Level Debugging: Structured debug packet framing (DEBUG_STREAM_IDENTIFIER 0x1ED15EED) routed over SRAM Window 2 Debug Slots, mailbox debug memory dumps, and GDB target debug stubs.

+-------------------------------------------------------------------------+
|                       DSP Firmware Trace Pipeline                       |
|                                                                         |
|  tr_info() / tr_err()                                                   |
|        |                                                                |
|        v                                                                |
|  _log_sofdict() ----> Filter Check (UUID / Comp / Pipe / Level)         |
|        |                                |                               |
|        | (Pass)                         | (Fail -> Suppressed)          |
|        v                                                                |
|  dtrace_event()                                                         |
|        |                                                                |
|        v                                                                |
|  +--------------------+                                                 |
|  | Internal Circular  |                                                 |
|  | DMA Trace Buffer   | <------- Periodic Task (dmat_work)              |
|  | (dma_trace_buf)    |                                                 |
|  +---------+----------+                                                 |
|            | Host DMA Stream (stream_tag)                               |
|            v                                                            |
+------------+------------------------------------------------------------+
             |
             | Host Gateway / HD-Audio Stream DMA
             v
+-------------------------------------------------------------------------+
|                       Linux Host / Userspace                            |
|                                                                         |
|  +-----------------------------+                                        |
|  | Host Circular Ring Buffer   |                                        |
|  | (sof_ipc_dma_trace_posn)    |                                        |
|  +--------------+--------------+                                        |
|                 |                                                       |
|                 v                                                       |
|         sof-logger / probe_client                                       |
|                 |                                                       |
|                 +<------ Firmware Dictionary (.ldc)                     |
|                 v                                                       |
|         Decoded ASCII Log Output (Terminal / dut-monitor)               |
+-------------------------------------------------------------------------+

Audio Probe Tap Points

Audio probes tap directly into interconnect ring buffers between processing modules:

+-------------------------------------------------------------------------+
|                   Audio Pipeline with Attached Probes                   |
|                                                                         |
|   [ Host DMA ]                                                          |
|        |                                                                |
|        v                                                                |
|   [ Buffer 1 ] <====== [ Probe Point: INJECTION ] <--- Host Stream      |
|        |                                                                |
|        v                                                                |
|   [ Module A ] (e.g. Volume)                                            |
|        |                                                                |
|        v                                                                |
|   [ Buffer 2 ] ======> [ Probe Point: EXTRACTION ] ---> Host Stream     |
|        |                                                (0xBABEBEBA)    |
|        v                                                                |
|   [ Module B ] (e.g. EQ / DRC)                                          |
|        |                                                                |
|        v                                                                |
|   [ Buffer 3 ] ======> [ Probe Point: EXTRACTION ] ---> Host Stream     |
|        |                                                                |
|        v                                                                |
|   [ DAI / Speaker ]                                                     |
+-------------------------------------------------------------------------+

Shared SRAM Memory Windows Layout

SOF partitions DSP shared memory windows into distinct diagnostic and telemetry regions:

+-------------------------------------------------------------------------+
|                       Shared SRAM Mailbox Windows                       |
|                                                                         |
|  +-------------------------------------------------------------------+  |
|  | Window 0: Mailbox & Firmware Status Registers (FSR / LEC / LTR)   |  |
|  |   - Offset 0x00: FW Status (FSR)     - Offset 0x04: Last Error    |  |
|  |   - Offset 0x08: Power Status (FPS)  - Offset 0x0C: Secondary STS |  |
|  |   - Offset 0x10: Pipeline State      - Offset 0x14: Peak Volume   |  |
|  +-------------------------------------------------------------------+  |
|  | Window 1: IPC Mailbox (Host Command / DSP Reply Payloads)         |  |
|  +-------------------------------------------------------------------+  |
|  | Window 2: Debug Window Slot Manager (Magic: 0x1ED15EED)           |  |
|  |   - Slot 0: Reserved / Firmware Ready                             |  |
|  |   - Slot 1: Hardware Telemetry (system_tick_info per core)        |  |
|  |   - Slot 2+: Per-core Debug Stream circular buffers               |  |
|  +-------------------------------------------------------------------+  |
|  | Window 3: Performance Measurement Window (ADSP_PMW)               |  |
|  |   - Memory Window 3: Component cycle budgets & profiling slots    |  |
|  +-------------------------------------------------------------------+  |
+-------------------------------------------------------------------------+

Trace DMA & Dictionary Logging

group Trace DMA & Dictionary Logging

Circular host DMA trace buffers, dictionary-based logger (.ldc), runtime log level filtering, and panic crash dumps.

Typedefs

typedef void (*log_func_t)(bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args)

Function pointer type for formatted trace logger backends.

Param send_atomic:

[in] True if logging from atomic or interrupt context.

Param log_entry:

[in] Pointer to static log entry descriptor.

Param ctx:

[in] Pointer to caller trace context.

Param lvl:

[in] Severity log level (LOG_LEVEL_*).

Param id_1:

[in] Primary component/pipe identifier.

Param id_2:

[in] Secondary component/subid identifier.

Param arg_count:

[in] Number of variable arguments.

Param args:

[in] Variable arguments list.

Functions

int dma_trace_init_early(struct sof *sof)

Early initialization of the DMA trace subsystem during bootstrap.

Parameters:

• sof – [inout] Global SOF system context.

Returns:

0 on success, or negative error code on failure.

int dma_trace_init_complete(struct dma_trace_data *d)

Complete initialization of DMA trace once host channel is negotiated.

Parameters:

• d – [inout] DMA trace data context.

Returns:

0 on success, or negative error code on failure.

int dma_trace_host_buffer(struct dma_trace_data *d, struct dma_sg_elem_array *elem_array, uint32_t host_size)

Configure the host-side destination scatter-gather buffer for DMA trace.

Parameters:

• d – [inout] DMA trace data context.

• elem_array – [in] Array of scatter-gather buffer page elements.

• host_size – [in] Total size in bytes of the host buffer.

Returns:

0 on success, or negative error code on failure.

int dma_trace_enable(struct dma_trace_data *d)

Enable DMA trace streaming to the host.

Parameters:

• d – [inout] DMA trace data context.

Returns:

0 on success, or negative error code on failure.

void dma_trace_disable(struct dma_trace_data *d)

Disable DMA trace streaming and cancel pending periodic tasks.

Parameters:

• d – [inout] DMA trace data context.

void dma_trace_flush(void *destination)

Flush residual trace data from local DSP buffer to destination memory or mailbox.

Parameters:

• destination – [out] Pointer to destination memory buffer, or NULL for default mailbox.

void dma_trace_on(void)

Globally unpause and resume trace event logging.

void dma_trace_off(void)

Globally pause trace event logging.

void dtrace_event(const char *e, uint32_t size)

Append a binary trace event to the circular buffer.

Parameters:

• e – [in] Pointer to binary event packet.

• size – [in] Packet size in bytes.

void dtrace_event_atomic(const char *e, uint32_t length)

Append a binary trace event to the buffer from atomic or interrupt context.

Parameters:

• e – [in] Pointer to binary event packet.

• length – [in] Size of packet in bytes.

static inline bool dma_trace_initialized(const struct dma_trace_data *d)

Check whether DMA trace subsystem has been initialized.

Parameters:

• d – [in] DMA trace context.

Returns:

True if initialized with valid buffer memory, false otherwise.

static inline struct dma_trace_data *dma_trace_data_get(void)

Retrieve global DMA trace data context from system runtime.

Returns:

Pointer to struct dma_trace_data.

static inline uint32_t dtrace_calc_buf_margin(struct dma_trace_buf *buffer)

Calculate contiguous bytes remaining until the end of the circular buffer.

Parameters:

• buffer – [in] Pointer to circular trace buffer descriptor.

Returns:

Contiguous byte margin before write wrap-around.

static inline struct trace *trace_get(void)

Retrieve global trace subsystem context from SOF runtime.

Returns:

Pointer to struct trace.

void trace_flush_dma_to_mbox(void)

Flush buffered trace data from DMA buffer to Mailbox Window.

void trace_on(void)

Globally resume trace event logging.

void trace_off(void)

Globally pause trace event logging.

void trace_init(struct sof *sof)

Initialize the trace subsystem and allocate global trace buffers.

Parameters:

• sof – [inout] Global SOF runtime context.

void trace_log_filtered(bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args)

Emit a filtered dictionary trace message.

Parameters:

• send_atomic – [in] True if logging from atomic context.

• log_entry – [in] Pointer to static log entry.

• ctx – [in] Trace context.

• lvl – [in] Log level.

• id_1 – [in] Primary identifier.

• id_2 – [in] Secondary identifier.

• arg_count – [in] Argument count.

• args – [in] Argument list.

void trace_log_unfiltered(bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args)

Emit an unfiltered dictionary trace message directly to buffers.

Parameters:

• send_atomic – [in] True if logging from atomic context.

• log_entry – [in] Pointer to static log entry.

• ctx – [in] Trace context.

• lvl – [in] Log level.

• id_1 – [in] Primary identifier.

• id_2 – [in] Secondary identifier.

• arg_count – [in] Argument count.

• args – [in] Argument list.

struct sof_ipc_trace_filter_elem *trace_filter_fill(struct sof_ipc_trace_filter_elem *elem, struct sof_ipc_trace_filter_elem *end, struct trace_filter *filter)

Populate an IPC trace filter element array.

Parameters:

• elem – [inout] Pointer to current output filter element.

• end – [in] Boundary pointer of element array.

• filter – [in] Source trace filter configuration.

Returns:

Pointer to next available filter element slot.

int trace_filter_update(const struct trace_filter *elem)

Update runtime trace filtering configuration from IPC payload.

Parameters:

• elem – [in] Trace filter descriptor to apply.

Returns:

0 on success, or negative error code on failure.

void mtrace_dict_entry(bool atomic_context, uint32_t log_entry_pointer, int n_args, ...)

Appends one SOF dictionary entry and log statement to shared memory mtrace.

Parameters:

• atomic_context – Take the trace->lock if false.

• log_entry_pointer – Dictionary index produced by _DECLARE_LOG_ENTRY macro.

• n_args – Number of variable arguments.

void mtrace_event(const char *complete_packet, uint32_t length)

Posts a fully prepared log header and log entry packet to mtrace buffer.

Parameters:

• complete_packet – Pointer to prepared log packet buffer.

• length – Packet size in bytes.

void _log_sofdict(log_func_t sofdict_logf, bool atomic, const void *log_entry, const struct tr_ctx *ctx, const uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, ...)

Internal dictionary logger formatting and dispatch helper.

Parameters:

• sofdict_logf – Backend log emission callback function.

• atomic – True if executed in atomic context.

• log_entry – Pointer to static log entry.

• ctx – Trace context.

• lvl – Log severity level.

• id_1 – Primary identifier.

• id_2 – Secondary identifier.

• arg_count – Number of format arguments.

struct sof_ipc_dma_trace_params

#include <src/include/ipc/trace.h>

Legacy host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS).

Deprecated:

Use sof_ipc_dma_trace_params_ext instead.

Public Members

struct sof_ipc_cmd_hdr hdr

IPC command header.

struct sof_ipc_host_buffer buffer

Host-allocated circular buffer descriptor.

uint32_t stream_tag

Assigned host DMA stream tag.

struct sof_ipc_dma_trace_params_ext

#include <src/include/ipc/trace.h>

Extended host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS_EXT).

Public Members

struct sof_ipc_cmd_hdr hdr

IPC command header.

struct sof_ipc_host_buffer buffer

Host-allocated circular buffer descriptor.

uint32_t stream_tag

Assigned host DMA stream tag.

uint64_t timestamp_ns

Host wallclock timestamp at synchronization point in ns.

uint32_t reserved[8]

Reserved for future expansion.

struct sof_ipc_dma_trace_posn

#include <src/include/ipc/trace.h>

DMA trace circular buffer position report sent to host (SOF_IPC_TRACE_DMA_POSITION).

Public Members

struct sof_ipc_reply rhdr

IPC reply header.

uint32_t host_offset

Current write offset in host DMA buffer in bytes.

uint32_t overflow

Cumulative count of dropped bytes due to buffer overflow.

uint32_t messages

Total trace messages processed since boot.

struct sof_ipc_panic_info

#include <src/include/ipc/trace.h>

DSP panic crash dump descriptor reported to host.

Public Members

struct sof_ipc_hdr hdr

IPC base header.

uint32_t code

Panic classification code (SOF_IPC_PANIC_*).

char filename[SOF_TRACE_FILENAME_SIZE]

Source filename where panic occurred.

uint32_t linenum

Source line number where panic occurred.

struct log_entry_header

#include <src/include/user/trace.h>

Binary log packet header preceding variable arguments in DMA trace stream.

Each dictionary log packet in the DMA buffer begins with this header, followed by up to 4 parameters (uint32_t values) matching the format string referenced by log_entry_address in the ELF dictionary (.ldc).

Public Members

uint32_t uid

Unique log entry sequence number.

uint32_t id_0

Primary identifier (e.g.

Pipeline ID)

uint32_t id_1

Secondary identifier (e.g.

Component ID)

uint32_t core_id

Reporting DSP core identifier.

uint64_t timestamp

High-resolution hardware clock timestamp in DSP ticks.

uint32_t log_entry_address

Linker address of static log entry descriptor in firmware ELF.

struct dma_trace_buf

#include <src/include/sof/trace/dma-trace.h>

Internal ring buffer descriptor for DSP trace packets.

Public Members

void *w_ptr

Buffer write pointer where new trace packets are appended.

void *r_ptr

Buffer read pointer tracking data transferred by DMA.

void *addr

Base address of the circular trace buffer.

void *end_addr

Upper boundary address of the trace buffer.

uint32_t size

Total size of the buffer in bytes.

uint32_t avail

Number of readable bytes currently available.

struct dma_trace_data

#include <src/include/sof/trace/dma-trace.h>

Main DMA trace context and state machine descriptor.

Public Members

struct dma_sg_config config

Scatter-gather configuration for host DMA.

struct dma_trace_buf dmatb

Internal circular buffer tracking read/write pointers.

struct dma_copy dc

DMA copy engine instance.

struct sof_ipc_dma_trace_posn posn

Position report payload sent to host.

struct ipc_msg *msg

IPC message used to report buffer position.

uint32_t host_size

Total size of host-allocated trace buffer.

struct task dmat_work

Periodic scheduling task driving DMA transfers.

uint32_t enabled

1 if DMA trace streaming is active, 0 otherwise

uint32_t copy_in_progress

1 if a DMA copy operation is currently underway

uint32_t stream_tag

Assigned host DMA stream tag.

uint32_t active_stream_tag

Current active stream tag.

uint32_t dma_copy_align

Minimal byte alignment required for DMA transfer chunks.

uint32_t dropped_entries

Cumulative counter of dropped entries due to buffer overflow.

struct k_spinlock lock

Spinlock synchronizing buffer writes and DMA triggers.

uint64_t time_delta

Offset between host wallclock and DSP hardware timer.

struct trace_filter

#include <src/include/sof/trace/trace-soflogger.h>

Runtime trace filter criteria for components and pipelines.

Public Members

uint32_t uuid_id

Component UUID type identifier, or 0 for wildcard.

int32_t comp_id

Component ID, or -1 for wildcard.

int32_t pipe_id

Pipeline ID, or -1 for wildcard.

int32_t log_level

Target log level threshold (LOG_LEVEL_*).

Audio Probes & Stream Tap Points

group Audio Probes & Stream Tap Points

Dynamic pipeline buffer extraction and injection probes, probe DMA frames, and synchronization sync words.

Typedefs

typedef ssize_t (*probe_logging_hook_t)(uint8_t *buffer, size_t length)

Callback hook invoked when a chunk of probe logging data is ready.

Param buffer:

Pointer to raw probe buffer payload.

Param length:

Byte length of data available.

Return:

Number of bytes processed, or negative error code.

Functions

void probe_logging_init(probe_logging_hook_t hook)

Initialize the probe logging backend.

Parameters:

• hook – Callback invoked when new logging data is written out.

int probe_init(const struct probe_dma *extraction_probe_dma)

Initialize the audio probes subsystem.

Parameters:

• extraction_probe_dma – [in] Host DMA channel configured for data extraction, or NULL if extraction probes are not used.

Returns:

0 on success, or negative error code on failure.

int probe_deinit(void)

Deinitialize the probes subsystem and detach extraction DMA.

Returns:

0 on success, or -EINVAL if active probe points remain connected.

int probe_dma_add(uint32_t count, const struct probe_dma *probe_dma)

Configure injection DMA channels for inserting audio streams into pipelines.

Parameters:

• count – [in] Number of DMA descriptors provided in array.

• probe_dma – Array of probe DMA descriptors specifying stream tags and buffer sizes.

Returns:

0 on success, or negative error code on failure.

int probe_dma_info(struct sof_ipc_probe_info_params *data, uint32_t max_size)

Query configuration information for active injection DMAs.

Parameters:

• data – [out] Reply payload structure populated with connected DMA details.

• max_size – [in] Maximum available capacity in data buffer in bytes.

Returns:

0 on success, or negative error code on failure.

int probe_dma_remove(uint32_t count, const uint32_t *stream_tag)

Disconnect and remove active injection DMA channels.

Parameters:

• count – [in] Number of stream tags in array.

• stream_tag – [in] Array of host DMA stream tags to remove.

Returns:

0 on success, or negative error code on failure.

int probe_point_add(uint32_t count, const struct probe_point *probe)

Attach probe points to audio pipeline buffers for stream tap/injection.

Parameters:

• count – [in] Number of probe points in array.

• probe – [in] Array of probe point descriptors specifying buffer IDs and purpose.

Returns:

0 on success, or negative error code on failure.

int probe_point_info(struct sof_ipc_probe_info_params *data, uint32_t max_size)

Query configuration of currently active probe points.

Parameters:

• data – [out] Reply payload structure populated with connected probe points.

• max_size – [in] Maximum available capacity in data buffer in bytes.

Returns:

0 on success, or negative error code on failure.

int probe_point_remove(uint32_t count, const uint32_t *buffer_id)

Detach and remove probe points from pipeline buffers.

Parameters:

• count – [in] Number of buffer IDs in array.

• buffer_id – [in] Array of buffer IDs from which probe points should be detached.

Returns:

0 on success, or negative error code on failure.

static inline struct probe_pdata *probe_get(void)

Retrieve global probes private data context from SOF runtime.

Returns:

Pointer to struct probe_pdata.

struct probe_data_packet

#include <src/include/ipc/probe_dma_frame.h>

Header for data packets sent via compressed PCM from extraction probes.

Public Members

uint32_t sync_word

Magic synchronization marker (PROBE_EXTRACT_SYNC_WORD).

uint32_t buffer_id

Buffer ID from which data was extracted.

uint32_t format

Encoded 32-bit audio data format.

uint32_t timestamp_low

Low 32 bits of hardware timestamp in microseconds.

uint32_t timestamp_high

High 32 bits of hardware timestamp in microseconds.

uint32_t data_size_bytes

Byte length of extracted payload in data[].

uint8_t data[]

Extracted audio samples.

struct probe_dma

#include <src/include/ipc3/probe.h>

Host DMA channel descriptor allocated for audio probes.

Probe DMA channel descriptor.

Public Members

uint32_t stream_tag

Stream tag associated with this DMA channel.

Node ID / stream tag associated with this DMA.

uint32_t dma_buffer_size

Size of host DMA buffer in bytes.

Size of buffer in bytes associated with this DMA.

union probe_point_id_t

#include <src/include/ipc3/probe.h>

Packed identifier identifying target audio buffer for probe attachment.

Unique identifier for a probe attachment point.

Public Members

uint32_t full_id

Packed buffer identifier.

Raw 32-bit probe point identifier.

uint32_t module_id

Target module ID.

uint32_t instance_id

Target module instance ID.

uint32_t type

Probe point type (PROBE_TYPE_xxx).

uint32_t index

Pin / queue index inside target module.

struct probe_point_id_t fields

Bitfield access structure.

struct probe_point

#include <src/include/ipc3/probe.h>

Probe tap point descriptor binding a pipeline buffer to a probe purpose.

Probe point attachment descriptor.

Public Members

probe_point_id_t buffer_id

ID of pipeline buffer to which probe is attached.

ID of module buffer/pin to which probe is attached.

uint32_t purpose

Probe role (PROBE_PURPOSE_*).

Extraction or injection (PROBE_PURPOSE_xxx).

uint32_t stream_tag

Stream tag of DMA for injection; ignored on extraction request and populated on reply.

Stream tag of DMA providing injection data (for injection probes); ignored for extraction where firmware automatically binds the configured extraction DMA tag.

struct sof_ipc_probe_dma_add_params

#include <src/include/ipc3/probe.h>

DMA ADD for probes payload (SOF_IPC_PROBE_INIT, SOF_IPC_PROBE_DMA_ADD).

Public Members

struct sof_ipc_cmd_hdr hdr

Header.

uint32_t num_elems

Count of DMAs specified in array.

struct probe_dma probe_dma[]

Array of DMAs to be added.

struct sof_ipc_probe_info_params

#include <src/include/ipc3/probe.h>

Reply to INFO queries (SOF_IPC_PROBE_DMA_INFO, SOF_IPC_PROBE_POINT_INFO).

Discovery response listing active probe points or DMA channels.

Public Members

struct sof_ipc_reply rhdr

Header.

uint32_t num_elems

Count of elements in array.

Count of elements in payload array.

struct probe_dma probe_dma[0]

DMA info.

Array of active DMA descriptors.

struct probe_point probe_point[0]

Probe Point info.

Array of active probe point descriptors.

union sof_ipc_probe_info_params

union sof_ipc_probe_info_params

struct sof_ipc_probe_dma_remove_params

#include <src/include/ipc3/probe.h>

Probe DMA remove payload (SOF_IPC_PROBE_DMA_REMOVE).

Public Members

struct sof_ipc_cmd_hdr hdr

Header.

uint32_t num_elems

Count of stream tags specified in array.

uint32_t stream_tag[]

Array of stream tags associated with DMAs to remove.

struct sof_ipc_probe_point_add_params

#include <src/include/ipc3/probe.h>

Add probe points payload (SOF_IPC_PROBE_POINT_ADD).

Public Members

struct sof_ipc_cmd_hdr hdr

Header.

uint32_t num_elems

Count of Probe Points specified in array.

struct probe_point probe_point[]

Array of Probe Points to add.

struct sof_ipc_probe_point_remove_params

#include <src/include/ipc3/probe.h>

Remove probe points payload (SOF_IPC_PROBE_POINT_REMOVE).

Public Members

struct sof_ipc_cmd_hdr hdr

Header.

uint32_t num_elems

Count of buffer IDs specified in array.

uint32_t buffer_id[]

Array of buffer IDs from which Probe Points should be removed.

Hardware Telemetry & Performance Monitoring

group Hardware Telemetry & Performance Monitoring

Core system ticks, CPU cycle utilization, component performance tracking, and SRAM Window 0/3 telemetry status registers.

Common SRAM Window 0 firmware status and telemetry register offsets.

Defines

SRAM_REG_FW_STATUS

Offset to Firmware Status Register (FSR).

SRAM_REG_LAST_ERROR_CODE

Offset to Last Error Code (LEC).

SRAM_REG_FW_PWR_STATUS

Offset to Firmware Power Status (FPS).

SRAM_REG_LNEC

Offset to Last Native Error Code (LNEC).

SRAM_REG_LTR

Offset to Latency Tolerance Reporting (LTR).

SRAM_REG_ROM_INFO

Offset to ROM bootstrap information.

SRAM_REG_ABI_VER

Offset to ABI version field.

SRAM_REG_SLAVE_CORE_STS

Offset to Secondary core power/run status.

SRAM_REG_PIPELINE_REGS

Offset to pipeline state register array.

SRAM_REG_PEAK_VOL_REGS

Offset to peak volume meter register array.

SRAM_REG_LLP_GPDMA_READING_SLOTS

Offset to GPDMA linear link position reading slots.

SRAM_REG_LLP_SNDW_READING_SLOTS

Offset to SoundWire link position reading slots.

SRAM_REG_LLP_EVAD_SLOTS

Offset to EVAD position reading slot.

SRAM_REG_FW_END

Total size boundary of Window 0 firmware register block.

Functions

void perf_data_item_comp_init(struct perf_data_item_comp *perf, uint32_t resource_id, uint32_t power_mode)

Initializer for component performance data record.

Parameters:

• perf – [out] Structure to be initialized.

• resource_id – [in] Unique resource/component identifier.

• power_mode – [in] Active power mode.

struct perf_data_item_comp *perf_data_getnext(void)

Allocate next free performance data slot from Memory Window 3.

Returns:

Pointer to allocated performance data record, or NULL if window is full.

int free_performance_data(struct perf_data_item_comp *item)

Release an allocated performance data slot in Memory Window 3.

Parameters:

• item – [inout] Pointer to performance data item to release.

Returns:

0 on success, or negative error code if slot was already free.

void perf_meas_set_state(enum ipc4_perf_measurements_state_set state)

Set global performance measurement state machine.

Parameters:

• state – [in] Target measurement state (disabled, paused, enabled).

enum ipc4_perf_measurements_state_set perf_meas_get_state(void)

Query current global performance measurement state.

Returns:

Current measurement state enumeration value.

int get_performance_data(struct global_perf_data *const global_perf_data)

Retrieve global aggregated performance telemetry data.

Parameters:

• global_perf_data – Destination structure to populate.

Returns:

0 on success, or negative error code on failure.

int get_extended_performance_data(struct extended_global_perf_data *const ext_global_perf_data)

Retrieve extended global performance telemetry data with per-core breakdown.

Parameters:

• ext_global_perf_data – [out] Destination structure to populate.

Returns:

0 on success, or negative error code on failure.

int reset_performance_counters(void)

Reset all performance measurement counters across all components.

Returns:

0 on success, or negative error code on failure.

int enable_performance_counters(void)

Reinitialize and activate performance counters for all created components.

Returns:

0 on success, or negative error code on failure.

void disable_performance_counters(void)

Disable performance counters and unregister records marked for removal.

void telemetry_update(uint32_t begin_ccount, uint32_t current_ccount)

Update periodic telemetry metrics with elapsed core clock cycles.

Parameters:

• begin_ccount – Cycle count snapshot at start of measurement interval.

• current_ccount – Cycle count snapshot at end of measurement interval.

struct system_tick_info *telemetry_get_systick_info_ptr(void)

Retrieve pointer to system tick telemetry structure for current core.

Returns:

Pointer to struct system_tick_info in shared memory.

struct system_tick_info

#include <src/include/sof/debug/telemetry/telemetry.h>

Per-core system tick and cycle execution metrics.

Note

In this context, “systick” is a legacy terminology for counting DSP execution time intervals. It is neither related to the Zephyr RTOS system tick nor the SOF scheduler tick.

Public Members

uint32_t count

Total tick / measurement iteration count.

uint32_t last_time_elapsed

Cycles consumed during previous tick interval.

uint32_t max_time_elapsed

Peak cycle consumption observed across all intervals.

uint32_t last_ccount

Cycle counter snapshot at end of previous tick.

uint32_t avg_utilization

Rolling average CPU utilization percentage (0-100).

uint32_t peak_utilization

Peak CPU utilization percentage observed.

uint32_t peak_utilization_4k

Peak utilization over 4K sample rolling window.

uint32_t peak_utilization_8k

Peak utilization over 8K sample rolling window.

uint32_t rsvd[2]

Reserved for padding and future metrics.

struct telemetry_wnd_data

#include <src/include/sof/debug/telemetry/telemetry.h>

Layout of telemetry data published in shared Memory Window.

Public Members

uint32_t separator_1

Header boundary delimiter.

struct system_tick_info system_tick_info[CONFIG_MAX_CORE_COUNT]

Per-core execution metrics.

struct telemetry_perf_queue

#include <src/include/sof/debug/telemetry/telemetry.h>

Circular queue tracking execution cycle history for rolling averages.

Public Members

size_t elements[SOF_AVG_PERF_MEAS_DEPTH]

Historic cycle measurements.

size_t index

Current head index in circular queue.

uint8_t full

1 if queue has wrapped, 0 otherwise

size_t size

Number of valid measurements stored.

size_t sum

Running cumulative sum of valid measurements.

Debug Streams & Low-Level Debugging

group Debug Streams & Low-Level Debugging

Structured debug stream records, Memory Window 2 debug slots, mailbox debug dumps, and GDB target stub.

Functions

int debug_stream_slot_send_record(struct debug_stream_record *rec)

Send a debug stream record over the memory window debug slot.

Parameters:

• rec – [in] Pointer to abstract debug stream record to transmit.

Returns:

0 on success, -ENODEV if debug slot is unconfigured, or -ENOMEM if record exceeds capacity.

void ds_msg(const char *format, ...)

Format and transmit a text message record over the active debug stream slot.

Parameters:

• format – [in] Printf-style format string.

• ... – [in] Variable arguments matching format.

void ds_vamsg(const char *format, va_list ap)

Transmit a text message record over debug stream using va_list arguments.

Parameters:

• format – [in] Printf-style format string.

• ap – [in] Variable arguments list.

void gdb_handle_exception(void)

Exception handler hook triggered on GDB breakpoint or watchpoint trap.

void gdb_debug_info(unsigned char *str)

Output diagnostic debug string to connected GDB client.

Parameters:

• str – [in] Null-terminated string to transmit.

void gdb_init_debug_exception(void)

Initialize debug exception vectors and trap handlers.

void gdb_init(void)

Initialize the GDB target debugging stub and register listeners.

struct debug_stream_hdr

#include <src/include/user/debug_stream.h>

Stream preamble header recognized by host debug tools.

Public Members

uint32_t magic

Magic identifier (DEBUG_STREAM_IDENTIFIER).

uint32_t hdr_size

Total size of stream header in bytes.

struct debug_stream_record

#include <src/include/user/debug_stream.h>

Abstract debug record envelope carrying application-specific payloads.

Public Members

uint32_t id

Record identifier (DEBUG_STREAM_RECORD_ID_*).

uint32_t seqno

Monotonically increasing sequence number.

uint32_t size_words

Total size of the record including header in 32-bit words.

uint32_t data[]

Application-specific record payload.

struct debug_stream_section_descriptor

#include <src/include/user/debug_stream_slot.h>

Core-specific section descriptor within the debug window slot.

Each descriptor maps a core-specific circular buffer inside Memory Window 2. The offset field defines the byte offset from the start of debug_stream_slot_hdr to the core’s debug_stream_circular_buf structure (aligned to cache line and 4-byte word boundaries). The buf_words field defines the capacity of the circular buffer data[] array in 32-bit words.

Public Members

uint32_t core_id

Reporting DSP core identifier.

uint32_t buf_words

Circular buffer data capacity in 32-bit words.

uint32_t offset

Byte offset from slot base (4-byte aligned).

struct debug_stream_slot_hdr

#include <src/include/user/debug_stream_slot.h>

Preamble header placed at the beginning of Memory Window 2 Debug Slot.

Public Members

struct debug_stream_hdr hdr

Base stream identifier and size.

uint32_t total_size

Total size of payload across all core sections.

uint32_t num_sections

Number of active core-specific sections.

struct debug_stream_section_descriptor section_desc[]

Array of per-core section descriptors.

struct debug_stream_circular_buf

#include <src/include/user/debug_stream_slot.h>

Per-core circular buffer layout within a debug stream slot.

Public Members

uint32_t next_seqno

Sequence counter of next record to write.

uint32_t w_ptr

Current write position in 32-bit words.

uint32_t data[]

Circular data buffer holding stream records.

struct debug_stream_text_msg

#include <src/include/user/debug_stream_text_msg.h>

Formatted text message record within a debug stream.

The record payload is length-delimited by hdr.size_words. The text data in msg[] is ASCII/UTF-8 encoded and padded with trailing NUL bytes to a 32-bit word boundary. Receivers should calculate maximum payload capacity as (hdr.size_words * sizeof(uint32_t) - sizeof(struct debug_stream_record)) and stop parsing at either the capacity limit or the first internal NUL terminator.

Public Members

struct debug_stream_record hdr

Stream record header specifying size_words.

char msg[]

Length-delimited text message, padded to 32-bit boundary.