Skip to content

doc: telemetry: comprehensive Doxygen documentation for telemetry, logging, probes, and debug streams #11311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lgirdwood merged 1 commit into from
Oct 15, 2026
Merged

doc: telemetry: comprehensive Doxygen documentation for telemetry, logging, probes, and debug streams #11311

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions doc/groups.dox
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,30 @@
* @brief Real-time DSP trace logging, probe extraction/injection buffers, DMA telemetry, and panic dumps.
*/

/**
* @defgroup trace_logging_api Trace DMA & Dictionary Logging
* @ingroup probe_api
* @brief Circular host DMA trace buffers, dictionary-based logger (.ldc), runtime log level filtering, and panic crash dumps.
*/

/**
* @defgroup audio_probe_api Audio Probes & Stream Tap Points
* @ingroup probe_api
* @brief Dynamic pipeline buffer extraction and injection probes, probe DMA frames, and synchronization sync words.
*/

/**
* @defgroup telemetry_perf_api Hardware Telemetry & Performance Monitoring
* @ingroup probe_api
* @brief Core system ticks, CPU cycle utilization, component performance tracking, and SRAM Window 0/3 telemetry status registers.
*/

/**
* @defgroup debug_stream_api Debug Streams & Low-Level Debugging
* @ingroup probe_api
* @brief Structured debug stream records, Memory Window 2 debug slots, mailbox debug dumps, and GDB target stub.
*/

/**
* @defgroup platform_drivers_api Platform & Hardware Drivers
* @brief Digital Audio Interfaces (DAI), Direct Memory Access (DMA), and Power Management (PM) runtime.
Expand Down
3 changes: 3 additions & 0 deletions doc/sof.doxygen.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,9 @@ PREDEFINED = "__attribute__(x)= " \
"CONFIG_SOF_USERSPACE_INTERFACE_ALLOC=1" \
"CONFIG_SOF_FULL_ZEPHYR_APPLICATION=1" \
"CONFIG_SOF_USERSPACE_USE_SHARED_HEAP=1" \
"CONFIG_SOF_TELEMETRY_PERFORMANCE_MEASUREMENTS=1" \
"CONFIG_INTEL_ADSP_DEBUG_SLOT_MANAGER=1" \
"CONFIG_GDB_DEBUG=1" \
"__DOXYGEN__=1" \
"__coherent=" \
"__syscall=" \
Expand Down
102 changes: 40 additions & 62 deletions src/include/ipc/probe_dma_frame.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,81 +3,59 @@
* Copyright(c) 2022 Intel Corporation. All rights reserved.
*/

/**
* \file include/ipc/probe_dma_frame.h
* \brief Audio probe extraction stream packet frame headers and format bitfield encoding.
* \ingroup audio_probe_api
*/

#ifndef __IPC_PROBE_DMA_FRAME_H__
#define __IPC_PROBE_DMA_FRAME_H__

#include <rtos/bit.h>

/**
* Header for data packets sent via compressed PCM from extraction probes
* \brief Header for data packets sent via compressed PCM from extraction probes.
* \ingroup audio_probe_api
*/
struct probe_data_packet {
uint32_t sync_word; /**< PROBE_EXTRACT_SYNC_WORD */
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 data format */
uint32_t timestamp_low; /**< Low 32 bits of timestamp in us */
uint32_t timestamp_high; /**< High 32 bits of timestamp in us */
uint32_t data_size_bytes; /**< Size of following audio data */
uint8_t data[]; /**< Audio data extracted from buffer */
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 */
} __attribute__((packed, aligned(4)));

/** Extraction packet sync marker (0xBABEBEBA) */
#define PROBE_EXTRACT_SYNC_WORD 0xBABEBEBA

/**
* \brief Definitions of shifts and masks for format encoding in probe
* extraction stream
*
* Audio format from extraction probes is encoded as 32 bit value. Following
* graphic explains encoding.
*
* A|BBBB|CCCC|DDDD|EEEEE|FF|GG|H|I|J|XXXXXXX
* A - 1 bit - Specifies Type Encoding - 1 for Standard encoding
* B - 4 bits - Specify Standard Type - 0 for Audio
* C - 4 bits - Specify Audio format - 0 for PCM
* D - 4 bits - Specify Sample Rate - value enumerating standard sample rates:
* 8000 Hz = 0x0
* 11025 Hz = 0x1
* 12000 Hz = 0x2
* 16000 Hz = 0x3
* 22050 Hz = 0x4
* 24000 Hz = 0x5
* 32000 Hz = 0x6
* 44100 Hz = 0x7
* 48000 Hz = 0x8
* 64000 Hz = 0x9
* 88200 Hz = 0xA
* 96000 Hz = 0xB
* 128000 Hz = 0xC
* 176400 Hz = 0xD
* 192000 Hz = 0xE
* none of the above = 0xF
* E - 5 bits - Specify Number of Channels minus 1
* F - 2 bits - Specify Sample Size, number of valid sample bytes minus 1
* G - 2 bits - Specify Container Size, number of container bytes minus 1
* H - 1 bit - Specifies Sample Format - 0 for Integer, 1 for Floating point
* I - 1 bit - Specifies Sample Endianness - 0 for LE
* J - 1 bit - Specifies Interleaving - 1 for Sample Interleaving
/** \name Probe Extraction Audio Format Bitfield Shifts & Masks
* Bitfield encoding for probe extraction stream audio formats.
* @{
*/
#define PROBE_SHIFT_FMT_TYPE 31
#define PROBE_SHIFT_STANDARD_TYPE 27
#define PROBE_SHIFT_AUDIO_FMT 23
#define PROBE_SHIFT_SAMPLE_RATE 19
#define PROBE_SHIFT_NB_CHANNELS 14
#define PROBE_SHIFT_SAMPLE_SIZE 12
#define PROBE_SHIFT_CONTAINER_SIZE 10
#define PROBE_SHIFT_SAMPLE_FMT 9
#define PROBE_SHIFT_SAMPLE_END 8
#define PROBE_SHIFT_INTERLEAVING_ST 7
#define PROBE_SHIFT_FMT_TYPE 31 /**< Type encoding shift (1 = standard) */
#define PROBE_SHIFT_STANDARD_TYPE 27 /**< Standard type shift (0 = audio) */
#define PROBE_SHIFT_AUDIO_FMT 23 /**< Audio format shift (0 = PCM) */
#define PROBE_SHIFT_SAMPLE_RATE 19 /**< Sample rate enumeration index shift */
#define PROBE_SHIFT_NB_CHANNELS 14 /**< Channel count minus 1 shift */
#define PROBE_SHIFT_SAMPLE_SIZE 12 /**< Valid sample bytes minus 1 shift */
#define PROBE_SHIFT_CONTAINER_SIZE 10 /**< Container bytes minus 1 shift */
#define PROBE_SHIFT_SAMPLE_FMT 9 /**< Sample format (0 = integer, 1 = float) */
#define PROBE_SHIFT_SAMPLE_END 8 /**< Endianness (0 = little-endian) */
#define PROBE_SHIFT_INTERLEAVING_ST 7 /**< Interleaving (1 = sample interleaved) */

#define PROBE_MASK_FMT_TYPE MASK(31, 31)
#define PROBE_MASK_STANDARD_TYPE MASK(30, 27)
#define PROBE_MASK_AUDIO_FMT MASK(26, 23)
#define PROBE_MASK_SAMPLE_RATE MASK(22, 19)
#define PROBE_MASK_NB_CHANNELS MASK(18, 14)
#define PROBE_MASK_SAMPLE_SIZE MASK(13, 12)
#define PROBE_MASK_CONTAINER_SIZE MASK(11, 10)
#define PROBE_MASK_SAMPLE_FMT MASK(9, 9)
#define PROBE_MASK_SAMPLE_END MASK(8, 8)
#define PROBE_MASK_INTERLEAVING_ST MASK(7, 7)
#define PROBE_MASK_FMT_TYPE MASK(31, 31) /**< Type encoding mask */
#define PROBE_MASK_STANDARD_TYPE MASK(30, 27) /**< Standard type mask */
#define PROBE_MASK_AUDIO_FMT MASK(26, 23) /**< Audio format mask */
#define PROBE_MASK_SAMPLE_RATE MASK(22, 19) /**< Sample rate mask */
#define PROBE_MASK_NB_CHANNELS MASK(18, 14) /**< Channel count mask */
#define PROBE_MASK_SAMPLE_SIZE MASK(13, 12) /**< Sample size mask */
#define PROBE_MASK_CONTAINER_SIZE MASK(11, 10) /**< Container size mask */
#define PROBE_MASK_SAMPLE_FMT MASK(9, 9) /**< Sample format mask */
#define PROBE_MASK_SAMPLE_END MASK(8, 8) /**< Endianness mask */
#define PROBE_MASK_INTERLEAVING_ST MASK(7, 7) /**< Interleaving mask */
/** @} */

#endif
#endif /* __IPC_PROBE_DMA_FRAME_H__ */
105 changes: 56 additions & 49 deletions src/include/ipc/trace.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,8 @@

/**
* \file include/ipc/trace.h
* \brief IPC definitions
* \author Liam Girdwood <liam.r.girdwood@linux.intel.com>
* \author Keyon Jie <yang.jie@linux.intel.com>
* \author Karol Trzcinski <karolx.trzcinski@linux.intel.com>
* \brief Host-DSP IPC trace DMA configuration, filtering, and panic descriptors.
* \ingroup trace_logging_api
*/

#ifndef __IPC_TRACE_H__
Expand All @@ -21,35 +19,41 @@
#include <ipc/stream.h>
#include <stdint.h>

/*
* DMA for Trace
*/

/** Maximum filename string length embedded in panic reports */
#define SOF_TRACE_FILENAME_SIZE 32

/* DMA for Trace params info - SOF_IPC_TRACE_DMA_PARAMS */
/* Deprecated - use sof_ipc_dma_trace_params_ext */
/**
* \brief Legacy host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS).
* \ingroup trace_logging_api
* @deprecated Use sof_ipc_dma_trace_params_ext instead.
*/
struct sof_ipc_dma_trace_params {
struct sof_ipc_cmd_hdr hdr;
struct sof_ipc_host_buffer buffer;
uint32_t stream_tag;
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 */
} __attribute__((packed, aligned(4)));

/* DMA for Trace params info - SOF_IPC_TRACE_DMA_PARAMS_EXT */
/**
* \brief Extended host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS_EXT).
* \ingroup trace_logging_api
*/
struct sof_ipc_dma_trace_params_ext {
struct sof_ipc_cmd_hdr hdr;
struct sof_ipc_host_buffer buffer;
uint32_t stream_tag;
uint64_t timestamp_ns; /* in nanosecnd */
uint32_t reserved[8];
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 */
} __attribute__((packed, aligned(4)));

/* DMA for Trace params info - SOF_IPC_TRACE_DMA_POSITION */
/**
* \brief DMA trace circular buffer position report sent to host (SOF_IPC_TRACE_DMA_POSITION).
* \ingroup trace_logging_api
*/
struct sof_ipc_dma_trace_posn {
struct sof_ipc_reply rhdr;
uint32_t host_offset; /* Offset of DMA host buffer */
uint32_t overflow; /* overflow bytes if any */
uint32_t messages; /* total trace messages */
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 */
} __attribute__((packed, aligned(4)));

/* Values used in sof_ipc_trace_filter_elem */
Expand Down Expand Up @@ -85,34 +89,37 @@ struct sof_ipc_trace_filter {
* Commom debug
*/

/*
* SOF panic codes
/** \name SOF Panic Codes
* Firmware panic identifiers written to mailboxes or reported upon crash.
* @{
*/
#define SOF_IPC_PANIC_MAGIC 0x0dead000
#define SOF_IPC_PANIC_MAGIC_MASK 0x0ffff000
#define SOF_IPC_PANIC_CODE_MASK 0x00000fff

#define SOF_IPC_PANIC_MEM (SOF_IPC_PANIC_MAGIC | 0x0)
#define SOF_IPC_PANIC_WORK (SOF_IPC_PANIC_MAGIC | 0x1)
#define SOF_IPC_PANIC_IPC (SOF_IPC_PANIC_MAGIC | 0x2)
#define SOF_IPC_PANIC_ARCH (SOF_IPC_PANIC_MAGIC | 0x3)
#define SOF_IPC_PANIC_PLATFORM (SOF_IPC_PANIC_MAGIC | 0x4)
#define SOF_IPC_PANIC_TASK (SOF_IPC_PANIC_MAGIC | 0x5)
#define SOF_IPC_PANIC_EXCEPTION (SOF_IPC_PANIC_MAGIC | 0x6)
#define SOF_IPC_PANIC_DEADLOCK (SOF_IPC_PANIC_MAGIC | 0x7)
#define SOF_IPC_PANIC_STACK (SOF_IPC_PANIC_MAGIC | 0x8)
#define SOF_IPC_PANIC_IDLE (SOF_IPC_PANIC_MAGIC | 0x9)
#define SOF_IPC_PANIC_WFI (SOF_IPC_PANIC_MAGIC | 0xa)
#define SOF_IPC_PANIC_ASSERT (SOF_IPC_PANIC_MAGIC | 0xb)

/* panic info include filename and line number
* filename array will not include null terminator if fully filled
#define SOF_IPC_PANIC_MAGIC 0x0dead000 /**< Magic pattern identifying valid panic packet */
#define SOF_IPC_PANIC_MAGIC_MASK 0x0ffff000 /**< Mask isolating panic magic pattern */
#define SOF_IPC_PANIC_CODE_MASK 0x00000fff /**< Mask isolating specific panic category */

#define SOF_IPC_PANIC_MEM (SOF_IPC_PANIC_MAGIC | 0x0) /**< Memory allocation exhaustion panic */
#define SOF_IPC_PANIC_WORK (SOF_IPC_PANIC_MAGIC | 0x1) /**< Scheduling task failure panic */
#define SOF_IPC_PANIC_IPC (SOF_IPC_PANIC_MAGIC | 0x2) /**< Host IPC transport failure panic */
#define SOF_IPC_PANIC_ARCH (SOF_IPC_PANIC_MAGIC | 0x3) /**< Architecture exception panic */
#define SOF_IPC_PANIC_PLATFORM (SOF_IPC_PANIC_MAGIC | 0x4) /**< Platform device driver panic */
#define SOF_IPC_PANIC_TASK (SOF_IPC_PANIC_MAGIC | 0x5) /**< Real-time task deadline panic */
#define SOF_IPC_PANIC_EXCEPTION (SOF_IPC_PANIC_MAGIC | 0x6) /**< Unhandled CPU exception panic */
#define SOF_IPC_PANIC_DEADLOCK (SOF_IPC_PANIC_MAGIC | 0x7) /**< Multicore spinlock deadlock panic */
#define SOF_IPC_PANIC_STACK (SOF_IPC_PANIC_MAGIC | 0x8) /**< Stack guard overflow panic */
#define SOF_IPC_PANIC_IDLE (SOF_IPC_PANIC_MAGIC | 0x9) /**< Idle power state transition panic */
#define SOF_IPC_PANIC_WFI (SOF_IPC_PANIC_MAGIC | 0xa) /**< Wait-For-Interrupt lockup panic */
#define SOF_IPC_PANIC_ASSERT (SOF_IPC_PANIC_MAGIC | 0xb) /**< Assertion failure panic */
/** @} */

/**
* \brief DSP panic crash dump descriptor reported to host.
* \ingroup trace_logging_api
*/
struct sof_ipc_panic_info {
struct sof_ipc_hdr hdr;
uint32_t code; /* SOF_IPC_PANIC_ */
char filename[SOF_TRACE_FILENAME_SIZE];
uint32_t linenum;
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 */
} __attribute__((packed, aligned(4)));

#endif /* __IPC_TRACE_H__ */
Loading
Loading