Repository navigation
doc: telemetry: comprehensive Doxygen documentation for telemetry, logging, probes, and debug streams - #11311
Merged
lgirdwood merged 1 commit intoOct 15, 2026
Conversation
lgirdwood
requested review from
a team,
abonislawski,
dbaluta,
kv2019i,
lbetlej,
mmaka1,
pblaszko,
plbossart and
tmleman
as code owners
October 14, 2026 19:11
Contributor
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Copilot review overview
3 open findings
What changed in this PR
Adds comprehensive Doxygen documentation across SOF telemetry, trace/logging, audio probe, and debug stream subsystems by introducing dedicated API subgroups and annotating public structs/macros/functions for full documentation coverage.
Changes:
- Adds file-level and symbol-level Doxygen comments across trace/logging, probes, telemetry/perf monitoring, and debug stream headers.
- Introduces four new Doxygen subgroups under
probe_apiand assigns relevant headers to them via\ingroup. - Updates Doxygen configuration (
PREDEFINED) to document config-gated APIs.
| File | Description |
|---|---|
| src/include/user/trace.h | Documents user-space ABI log levels and binary log packet header. |
| src/include/user/debug_stream_text_msg.h | Documents debug stream text message record and send helpers. |
| src/include/user/debug_stream_slot.h | Documents debug slot layout structures and record send syscall. |
| src/include/user/debug_stream.h | Documents debug stream protocol header/record envelope and record IDs. |
| src/include/sof/trace/trace-soflogger.h | Adds Doxygen docs for dictionary logger, filtering, and helper APIs. |
| src/include/sof/trace/trace-boot.h | Documents bootloader/boot checkpoint trace codes. |
| src/include/sof/trace/dma-trace.h | Documents DMA trace buffer structures and host streaming APIs. |
| src/include/sof/probe/probe.h | Documents probe subsystem APIs and callback semantics. |
| src/include/sof/debug/telemetry/telemetry.h | Documents telemetry window layout and tick/perf queue structures. |
| src/include/sof/debug/telemetry/performance_monitor.h | Documents perf monitor APIs and exposes them to Doxygen when config-gated. |
| src/include/sof/debug/gdb/gdb.h | Documents GDB stub APIs and exception hook. |
| src/include/sof/debug/debug.h | Documents debug mailbox dump macros and firmware-ready flags. |
| src/include/kernel/mailbox.h | Re-groups and documents SRAM Window 0 FW register offsets for telemetry/perf. |
| src/include/ipc3/probe.h | Documents IPC3 probe structures, purposes, and IPC payloads. |
| src/include/ipc/trace.h | Documents IPC trace DMA params/position and panic codes/descriptor. |
| src/include/ipc/probe_dma_frame.h | Documents probe extraction packet header and format bitfields. |
| doc/sof.doxygen.in | Adds PREDEFINED config symbols so Doxygen includes gated APIs. |
| doc/groups.dox | Adds the four new Doxygen subgroups under probe_api. |
🧠 Review effort: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Copilot stopped reviewing on behalf of
lgirdwood due to an error
October 14, 2026 19:30
lgirdwood
force-pushed
the
topic/doxygen-telemetry-probes
branch
from
October 14, 2026 19:30
20cecda to
5d58a6e
Compare
Contributor
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Copilot review overview
5 open findings
buf_wordsfield is explicitly documented in 32-bit words, butoffsetis documented in… · Newmsg[]is null-terminated, but the struct layout itself does not guarantee a… · Newdebug_stream_apibrief claims it includes \"early bootloader trace codes\", but the boot…
🧠 Review effort: Lite
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>
lgirdwood
force-pushed
the
topic/doxygen-telemetry-probes
branch
from
October 14, 2026 20:00
5d58a6e to
111b07e
Compare
PR 11311: test resultsRun date: 2026-10-15 10:03 UTC Tested commit: 111b07e774fa0b0cf21f180e6e1e326c8d220593
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR provides comprehensive Doxygen documentation across all SOF telemetry, logging, audio probe, and debug stream subsystems. It organizes the diagnostic infrastructure into four dedicated subgroups under
probe_api, bringing the Doxygen documentation coverage from 0% to 100% across these headers:Subgroups & Architecture
trace_logging_api(Trace DMA & Dictionary Logging):dma_trace_buf,dma_trace_data).dma_trace_init_early(),dma_trace_enable(),dma_trace_flush(),dtrace_event(),dtrace_event_atomic())._log_sofdict(),trace_log_filtered(),trace_log_unfiltered(),trace_filter_update(),trace_flush_dma_to_mbox()).TRACE_BOOT_*).sof_ipc_dma_trace_params,sof_ipc_dma_trace_posn, panic crash codesSOF_IPC_PANIC_*).struct log_entry_header,LOG_LEVEL_*).audio_probe_api(Audio Probes & Stream Tap Points):probe_init(),probe_dma_add(),probe_point_add(),probe_get()).struct probe_data_packet, sync word0xBABEBEBA, format shift/mask bitfields).PROBE_PURPOSE_*,probe_point_id_t).telemetry_perf_api(Hardware Telemetry & Performance Monitoring):struct system_tick_info,struct telemetry_wnd_data,struct telemetry_perf_queue).WIN3_MBASE,ADSP_PMW) and performance measurement APIs (get_performance_data(), etc.).SRAM_REG_FW_STATUS,SRAM_REG_FW_TRACEP,SRAM_REG_PEAK_VOL, etc.).debug_stream_api(Abstract Debug Streams & Low-Level Debugging):DEBUG_STREAM_IDENTIFIER 0x1ED15EED,struct debug_stream_hdr,struct debug_stream_record).debug_stream_section_descriptor,debug_stream_slot_hdr,debug_stream_circular_buf).ds_msg(),ds_vamsg()).DEBUG_SET_FW_READY_FLAGS,dbg(),dbg_at(),dump()) and GDB target debug stubs.Verification
/** ... */,/**< ... */) and configuration directives.ninja -C build_doxygen doccompletes with 0 errors and 0 warnings.