Skip to content

Commit 2bc73a7

Browse files
lrgirdwolgirdwood
lrgirdwo
authored and
lgirdwood
committed
doc: telemetry: document telemetry, logging, probes, and debug streams
Add comprehensive Doxygen documentation across all SOF telemetry, logging, probe, and debug stream subsystems, organizing them into four dedicated subgroups under probe_api: 1. trace_logging_api: DMA trace buffer management, circular host streaming, dictionary-based logger (.ldc), runtime log level filtering, and panic crash dumps. 2. audio_probe_api: Audio probe injection and extraction tap points, probe DMA frame format encoding (0xBABEBEBA), and IPC commands. 3. telemetry_perf_api: Hardware telemetry metrics, CPU cycle accounting, Memory Window 3 component performance tracking, and SRAM Window 0 firmware status registers. 4. debug_stream_api: Abstract debug stream packet protocol (0x1ED15EED), Memory Window 2 debug slots, early mailbox debug dumping macros, and GDB target debug stub. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
1 parent 2d2476f commit 2bc73a7

18 files changed

Lines changed: 813 additions & 515 deletions

‎doc/groups.dox‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,30 @@
118118
* @brief Real-time DSP trace logging, probe extraction/injection buffers, DMA telemetry, and panic dumps.
119119
*/
120120

121+
/**
122+
* @defgroup trace_logging_api Trace DMA & Dictionary Logging
123+
* @ingroup probe_api
124+
* @brief Circular host DMA trace buffers, dictionary-based logger (.ldc), runtime log level filtering, and panic crash dumps.
125+
*/
126+
127+
/**
128+
* @defgroup audio_probe_api Audio Probes & Stream Tap Points
129+
* @ingroup probe_api
130+
* @brief Dynamic pipeline buffer extraction and injection probes, probe DMA frames, and synchronization sync words.
131+
*/
132+
133+
/**
134+
* @defgroup telemetry_perf_api Hardware Telemetry & Performance Monitoring
135+
* @ingroup probe_api
136+
* @brief Core system ticks, CPU cycle utilization, component performance tracking, and SRAM Window 0/3 telemetry status registers.
137+
*/
138+
139+
/**
140+
* @defgroup debug_stream_api Debug Streams & Low-Level Debugging
141+
* @ingroup probe_api
142+
* @brief Structured debug stream records, Memory Window 2 debug slots, mailbox debug dumps, and GDB target stub.
143+
*/
144+
121145
/**
122146
* @defgroup platform_drivers_api Platform & Hardware Drivers
123147
* @brief Digital Audio Interfaces (DAI), Direct Memory Access (DMA), and Power Management (PM) runtime.

‎doc/sof.doxygen.in‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,9 @@ PREDEFINED = "__attribute__(x)= " \
6060
"CONFIG_SOF_USERSPACE_INTERFACE_ALLOC=1" \
6161
"CONFIG_SOF_FULL_ZEPHYR_APPLICATION=1" \
6262
"CONFIG_SOF_USERSPACE_USE_SHARED_HEAP=1" \
63+
"CONFIG_SOF_TELEMETRY_PERFORMANCE_MEASUREMENTS=1" \
64+
"CONFIG_INTEL_ADSP_DEBUG_SLOT_MANAGER=1" \
65+
"CONFIG_GDB_DEBUG=1" \
6366
"__DOXYGEN__=1" \
6467
"__coherent=" \
6568
"__syscall=" \

‎src/include/ipc/probe_dma_frame.h‎

Lines changed: 40 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -3,81 +3,59 @@
33
* Copyright(c) 2022 Intel Corporation. All rights reserved.
44
*/
55

6+
/**
7+
* \file include/ipc/probe_dma_frame.h
8+
* \brief Audio probe extraction stream packet frame headers and format bitfield encoding.
9+
* \ingroup audio_probe_api
10+
*/
11+
612
#ifndef __IPC_PROBE_DMA_FRAME_H__
713
#define __IPC_PROBE_DMA_FRAME_H__
814

915
#include <rtos/bit.h>
1016

1117
/**
12-
* Header for data packets sent via compressed PCM from extraction probes
18+
* \brief Header for data packets sent via compressed PCM from extraction probes.
19+
* \ingroup audio_probe_api
1320
*/
1421
struct probe_data_packet {
15-
uint32_t sync_word; /**< PROBE_EXTRACT_SYNC_WORD */
22+
uint32_t sync_word; /**< Magic synchronization marker (PROBE_EXTRACT_SYNC_WORD) */
1623
uint32_t buffer_id; /**< Buffer ID from which data was extracted */
17-
uint32_t format; /**< Encoded data format */
18-
uint32_t timestamp_low; /**< Low 32 bits of timestamp in us */
19-
uint32_t timestamp_high; /**< High 32 bits of timestamp in us */
20-
uint32_t data_size_bytes; /**< Size of following audio data */
21-
uint8_t data[]; /**< Audio data extracted from buffer */
24+
uint32_t format; /**< Encoded 32-bit audio data format */
25+
uint32_t timestamp_low; /**< Low 32 bits of hardware timestamp in microseconds */
26+
uint32_t timestamp_high; /**< High 32 bits of hardware timestamp in microseconds */
27+
uint32_t data_size_bytes; /**< Byte length of extracted payload in data[] */
28+
uint8_t data[]; /**< Extracted audio samples */
2229
} __attribute__((packed, aligned(4)));
2330

31+
/** Extraction packet sync marker (0xBABEBEBA) */
2432
#define PROBE_EXTRACT_SYNC_WORD 0xBABEBEBA
2533

26-
/**
27-
* \brief Definitions of shifts and masks for format encoding in probe
28-
* extraction stream
29-
*
30-
* Audio format from extraction probes is encoded as 32 bit value. Following
31-
* graphic explains encoding.
32-
*
33-
* A|BBBB|CCCC|DDDD|EEEEE|FF|GG|H|I|J|XXXXXXX
34-
* A - 1 bit - Specifies Type Encoding - 1 for Standard encoding
35-
* B - 4 bits - Specify Standard Type - 0 for Audio
36-
* C - 4 bits - Specify Audio format - 0 for PCM
37-
* D - 4 bits - Specify Sample Rate - value enumerating standard sample rates:
38-
* 8000 Hz = 0x0
39-
* 11025 Hz = 0x1
40-
* 12000 Hz = 0x2
41-
* 16000 Hz = 0x3
42-
* 22050 Hz = 0x4
43-
* 24000 Hz = 0x5
44-
* 32000 Hz = 0x6
45-
* 44100 Hz = 0x7
46-
* 48000 Hz = 0x8
47-
* 64000 Hz = 0x9
48-
* 88200 Hz = 0xA
49-
* 96000 Hz = 0xB
50-
* 128000 Hz = 0xC
51-
* 176400 Hz = 0xD
52-
* 192000 Hz = 0xE
53-
* none of the above = 0xF
54-
* E - 5 bits - Specify Number of Channels minus 1
55-
* F - 2 bits - Specify Sample Size, number of valid sample bytes minus 1
56-
* G - 2 bits - Specify Container Size, number of container bytes minus 1
57-
* H - 1 bit - Specifies Sample Format - 0 for Integer, 1 for Floating point
58-
* I - 1 bit - Specifies Sample Endianness - 0 for LE
59-
* J - 1 bit - Specifies Interleaving - 1 for Sample Interleaving
34+
/** \name Probe Extraction Audio Format Bitfield Shifts & Masks
35+
* Bitfield encoding for probe extraction stream audio formats.
36+
* @{
6037
*/
61-
#define PROBE_SHIFT_FMT_TYPE 31
62-
#define PROBE_SHIFT_STANDARD_TYPE 27
63-
#define PROBE_SHIFT_AUDIO_FMT 23
64-
#define PROBE_SHIFT_SAMPLE_RATE 19
65-
#define PROBE_SHIFT_NB_CHANNELS 14
66-
#define PROBE_SHIFT_SAMPLE_SIZE 12
67-
#define PROBE_SHIFT_CONTAINER_SIZE 10
68-
#define PROBE_SHIFT_SAMPLE_FMT 9
69-
#define PROBE_SHIFT_SAMPLE_END 8
70-
#define PROBE_SHIFT_INTERLEAVING_ST 7
38+
#define PROBE_SHIFT_FMT_TYPE 31 /**< Type encoding shift (1 = standard) */
39+
#define PROBE_SHIFT_STANDARD_TYPE 27 /**< Standard type shift (0 = audio) */
40+
#define PROBE_SHIFT_AUDIO_FMT 23 /**< Audio format shift (0 = PCM) */
41+
#define PROBE_SHIFT_SAMPLE_RATE 19 /**< Sample rate enumeration index shift */
42+
#define PROBE_SHIFT_NB_CHANNELS 14 /**< Channel count minus 1 shift */
43+
#define PROBE_SHIFT_SAMPLE_SIZE 12 /**< Valid sample bytes minus 1 shift */
44+
#define PROBE_SHIFT_CONTAINER_SIZE 10 /**< Container bytes minus 1 shift */
45+
#define PROBE_SHIFT_SAMPLE_FMT 9 /**< Sample format (0 = integer, 1 = float) */
46+
#define PROBE_SHIFT_SAMPLE_END 8 /**< Endianness (0 = little-endian) */
47+
#define PROBE_SHIFT_INTERLEAVING_ST 7 /**< Interleaving (1 = sample interleaved) */
7148

72-
#define PROBE_MASK_FMT_TYPE MASK(31, 31)
73-
#define PROBE_MASK_STANDARD_TYPE MASK(30, 27)
74-
#define PROBE_MASK_AUDIO_FMT MASK(26, 23)
75-
#define PROBE_MASK_SAMPLE_RATE MASK(22, 19)
76-
#define PROBE_MASK_NB_CHANNELS MASK(18, 14)
77-
#define PROBE_MASK_SAMPLE_SIZE MASK(13, 12)
78-
#define PROBE_MASK_CONTAINER_SIZE MASK(11, 10)
79-
#define PROBE_MASK_SAMPLE_FMT MASK(9, 9)
80-
#define PROBE_MASK_SAMPLE_END MASK(8, 8)
81-
#define PROBE_MASK_INTERLEAVING_ST MASK(7, 7)
49+
#define PROBE_MASK_FMT_TYPE MASK(31, 31) /**< Type encoding mask */
50+
#define PROBE_MASK_STANDARD_TYPE MASK(30, 27) /**< Standard type mask */
51+
#define PROBE_MASK_AUDIO_FMT MASK(26, 23) /**< Audio format mask */
52+
#define PROBE_MASK_SAMPLE_RATE MASK(22, 19) /**< Sample rate mask */
53+
#define PROBE_MASK_NB_CHANNELS MASK(18, 14) /**< Channel count mask */
54+
#define PROBE_MASK_SAMPLE_SIZE MASK(13, 12) /**< Sample size mask */
55+
#define PROBE_MASK_CONTAINER_SIZE MASK(11, 10) /**< Container size mask */
56+
#define PROBE_MASK_SAMPLE_FMT MASK(9, 9) /**< Sample format mask */
57+
#define PROBE_MASK_SAMPLE_END MASK(8, 8) /**< Endianness mask */
58+
#define PROBE_MASK_INTERLEAVING_ST MASK(7, 7) /**< Interleaving mask */
59+
/** @} */
8260

83-
#endif
61+
#endif /* __IPC_PROBE_DMA_FRAME_H__ */

‎src/include/ipc/trace.h‎

Lines changed: 56 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,8 @@
88

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

1715
#ifndef __IPC_TRACE_H__
@@ -21,35 +19,41 @@
2119
#include <ipc/stream.h>
2220
#include <stdint.h>
2321

24-
/*
25-
* DMA for Trace
26-
*/
27-
22+
/** Maximum filename string length embedded in panic reports */
2823
#define SOF_TRACE_FILENAME_SIZE 32
2924

30-
/* DMA for Trace params info - SOF_IPC_TRACE_DMA_PARAMS */
31-
/* Deprecated - use sof_ipc_dma_trace_params_ext */
25+
/**
26+
* \brief Legacy host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS).
27+
* \ingroup trace_logging_api
28+
* @deprecated Use sof_ipc_dma_trace_params_ext instead.
29+
*/
3230
struct sof_ipc_dma_trace_params {
33-
struct sof_ipc_cmd_hdr hdr;
34-
struct sof_ipc_host_buffer buffer;
35-
uint32_t stream_tag;
31+
struct sof_ipc_cmd_hdr hdr; /**< IPC command header */
32+
struct sof_ipc_host_buffer buffer; /**< Host-allocated circular buffer descriptor */
33+
uint32_t stream_tag; /**< Assigned host DMA stream tag */
3634
} __attribute__((packed, aligned(4)));
3735

38-
/* DMA for Trace params info - SOF_IPC_TRACE_DMA_PARAMS_EXT */
36+
/**
37+
* \brief Extended host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS_EXT).
38+
* \ingroup trace_logging_api
39+
*/
3940
struct sof_ipc_dma_trace_params_ext {
40-
struct sof_ipc_cmd_hdr hdr;
41-
struct sof_ipc_host_buffer buffer;
42-
uint32_t stream_tag;
43-
uint64_t timestamp_ns; /* in nanosecnd */
44-
uint32_t reserved[8];
41+
struct sof_ipc_cmd_hdr hdr; /**< IPC command header */
42+
struct sof_ipc_host_buffer buffer; /**< Host-allocated circular buffer descriptor */
43+
uint32_t stream_tag; /**< Assigned host DMA stream tag */
44+
uint64_t timestamp_ns; /**< Host wallclock timestamp at synchronization point in ns */
45+
uint32_t reserved[8]; /**< Reserved for future expansion */
4546
} __attribute__((packed, aligned(4)));
4647

47-
/* DMA for Trace params info - SOF_IPC_TRACE_DMA_POSITION */
48+
/**
49+
* \brief DMA trace circular buffer position report sent to host (SOF_IPC_TRACE_DMA_POSITION).
50+
* \ingroup trace_logging_api
51+
*/
4852
struct sof_ipc_dma_trace_posn {
49-
struct sof_ipc_reply rhdr;
50-
uint32_t host_offset; /* Offset of DMA host buffer */
51-
uint32_t overflow; /* overflow bytes if any */
52-
uint32_t messages; /* total trace messages */
53+
struct sof_ipc_reply rhdr; /**< IPC reply header */
54+
uint32_t host_offset; /**< Current write offset in host DMA buffer in bytes */
55+
uint32_t overflow; /**< Cumulative count of dropped bytes due to buffer overflow */
56+
uint32_t messages; /**< Total trace messages processed since boot */
5357
} __attribute__((packed, aligned(4)));
5458

5559
/* Values used in sof_ipc_trace_filter_elem */
@@ -85,34 +89,37 @@ struct sof_ipc_trace_filter {
8589
* Commom debug
8690
*/
8791

88-
/*
89-
* SOF panic codes
92+
/** \name SOF Panic Codes
93+
* Firmware panic identifiers written to mailboxes or reported upon crash.
94+
* @{
9095
*/
91-
#define SOF_IPC_PANIC_MAGIC 0x0dead000
92-
#define SOF_IPC_PANIC_MAGIC_MASK 0x0ffff000
93-
#define SOF_IPC_PANIC_CODE_MASK 0x00000fff
94-
95-
#define SOF_IPC_PANIC_MEM (SOF_IPC_PANIC_MAGIC | 0x0)
96-
#define SOF_IPC_PANIC_WORK (SOF_IPC_PANIC_MAGIC | 0x1)
97-
#define SOF_IPC_PANIC_IPC (SOF_IPC_PANIC_MAGIC | 0x2)
98-
#define SOF_IPC_PANIC_ARCH (SOF_IPC_PANIC_MAGIC | 0x3)
99-
#define SOF_IPC_PANIC_PLATFORM (SOF_IPC_PANIC_MAGIC | 0x4)
100-
#define SOF_IPC_PANIC_TASK (SOF_IPC_PANIC_MAGIC | 0x5)
101-
#define SOF_IPC_PANIC_EXCEPTION (SOF_IPC_PANIC_MAGIC | 0x6)
102-
#define SOF_IPC_PANIC_DEADLOCK (SOF_IPC_PANIC_MAGIC | 0x7)
103-
#define SOF_IPC_PANIC_STACK (SOF_IPC_PANIC_MAGIC | 0x8)
104-
#define SOF_IPC_PANIC_IDLE (SOF_IPC_PANIC_MAGIC | 0x9)
105-
#define SOF_IPC_PANIC_WFI (SOF_IPC_PANIC_MAGIC | 0xa)
106-
#define SOF_IPC_PANIC_ASSERT (SOF_IPC_PANIC_MAGIC | 0xb)
107-
108-
/* panic info include filename and line number
109-
* filename array will not include null terminator if fully filled
96+
#define SOF_IPC_PANIC_MAGIC 0x0dead000 /**< Magic pattern identifying valid panic packet */
97+
#define SOF_IPC_PANIC_MAGIC_MASK 0x0ffff000 /**< Mask isolating panic magic pattern */
98+
#define SOF_IPC_PANIC_CODE_MASK 0x00000fff /**< Mask isolating specific panic category */
99+
100+
#define SOF_IPC_PANIC_MEM (SOF_IPC_PANIC_MAGIC | 0x0) /**< Memory allocation exhaustion panic */
101+
#define SOF_IPC_PANIC_WORK (SOF_IPC_PANIC_MAGIC | 0x1) /**< Scheduling task failure panic */
102+
#define SOF_IPC_PANIC_IPC (SOF_IPC_PANIC_MAGIC | 0x2) /**< Host IPC transport failure panic */
103+
#define SOF_IPC_PANIC_ARCH (SOF_IPC_PANIC_MAGIC | 0x3) /**< Architecture exception panic */
104+
#define SOF_IPC_PANIC_PLATFORM (SOF_IPC_PANIC_MAGIC | 0x4) /**< Platform device driver panic */
105+
#define SOF_IPC_PANIC_TASK (SOF_IPC_PANIC_MAGIC | 0x5) /**< Real-time task deadline panic */
106+
#define SOF_IPC_PANIC_EXCEPTION (SOF_IPC_PANIC_MAGIC | 0x6) /**< Unhandled CPU exception panic */
107+
#define SOF_IPC_PANIC_DEADLOCK (SOF_IPC_PANIC_MAGIC | 0x7) /**< Multicore spinlock deadlock panic */
108+
#define SOF_IPC_PANIC_STACK (SOF_IPC_PANIC_MAGIC | 0x8) /**< Stack guard overflow panic */
109+
#define SOF_IPC_PANIC_IDLE (SOF_IPC_PANIC_MAGIC | 0x9) /**< Idle power state transition panic */
110+
#define SOF_IPC_PANIC_WFI (SOF_IPC_PANIC_MAGIC | 0xa) /**< Wait-For-Interrupt lockup panic */
111+
#define SOF_IPC_PANIC_ASSERT (SOF_IPC_PANIC_MAGIC | 0xb) /**< Assertion failure panic */
112+
/** @} */
113+
114+
/**
115+
* \brief DSP panic crash dump descriptor reported to host.
116+
* \ingroup trace_logging_api
110117
*/
111118
struct sof_ipc_panic_info {
112-
struct sof_ipc_hdr hdr;
113-
uint32_t code; /* SOF_IPC_PANIC_ */
114-
char filename[SOF_TRACE_FILENAME_SIZE];
115-
uint32_t linenum;
119+
struct sof_ipc_hdr hdr; /**< IPC base header */
120+
uint32_t code; /**< Panic classification code (SOF_IPC_PANIC_*) */
121+
char filename[SOF_TRACE_FILENAME_SIZE]; /**< Source filename where panic occurred */
122+
uint32_t linenum; /**< Source line number where panic occurred */
116123
} __attribute__((packed, aligned(4)));
117124

118125
#endif /* __IPC_TRACE_H__ */

0 commit comments

Comments
 (0)