Repository navigation
doc: overhaul Doxygen C API architecture, group taxonomy, and header documentation - #11294
Merged
lgirdwood merged 4 commits intoOct 11, 2026
Merged
Conversation
lgirdwood
requested review from
a team,
abonislawski,
dbaluta,
iuliana-prodan,
kv2019i,
lbetlej,
lyakh,
mmaka1,
pblaszko,
plbossart,
singalsu and
tmleman
as code owners
October 11, 2026 19:02
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Multiple unrelated API and structure edits currently introduce compilation failures and one uninitialized DMA-status read.
15 open findings
What changed in this PR
This PR restructures SOF’s generated C API documentation around nine architectural subsystems and expands Doxygen coverage across firmware interfaces.
Changes:
- Adds a Doxygen landing page, taxonomy, navigation, and broader source coverage.
- Documents RTOS, IPC, pipeline, driver, DSP math, and audio-component APIs.
- Consolidates legacy documentation groups and modifies several related declarations and structures.
| File | Description |
|---|---|
zephyr/include/sof/trace/trace.h |
Documents timer access. |
zephyr/include/sof/lib/pm_runtime.h |
Regroups and documents PM runtime. |
zephyr/include/sof/lib/dma.h |
Regroups DMA APIs. |
zephyr/include/sof/lib/dma-legacy.h |
Documents legacy DMA copy. |
zephyr/include/rtos/userspace_helper.h |
Documents mailbox stub. |
zephyr/include/rtos/timer.h |
Adds RTOS timer metadata. |
zephyr/include/rtos/spinlock.h |
Documents spinlock initialization. |
zephyr/include/rtos/sof.h |
Documents global runtime context. |
zephyr/include/rtos/mutex.h |
Adds mutex API metadata. |
zephyr/include/rtos/kernel.h |
Documents privilege helper. |
zephyr/include/rtos/clk.h |
Adds clock API metadata. |
zephyr/include/rtos/cache.h |
Documents cache operations. |
zephyr/include/rtos/alloc.h |
Regroups and documents allocation APIs. |
src/probe/probe.c |
Adjusts probe comments and DMA error handling. |
src/math/mu_law.c |
Converts implementation documentation style. |
src/math/dct.c |
Removes duplicate implementation documentation. |
src/math/auditory/auditory.c |
Converts implementation comments. |
src/math/atan2.c |
Converts function documentation style. |
src/include/sof/schedule/schedule.h |
Regroups and documents scheduler APIs. |
src/include/sof/schedule/ll_schedule.h |
Documents LL scheduling. |
src/include/sof/schedule/edf_schedule.h |
Documents EDF scheduling. |
src/include/sof/schedule/dp_schedule.h |
Documents DP scheduling. |
src/include/sof/platform.h |
Regroups platform APIs. |
src/include/sof/math/window.h |
Adds window API metadata. |
src/include/sof/math/trig.h |
Documents trigonometric APIs. |
src/include/sof/math/numbers.h |
Adds fixed-point API metadata. |
src/include/sof/math/matrix.h |
Adds matrix API metadata. |
src/include/sof/math/lut_trig.h |
Documents lookup-table sine. |
src/include/sof/math/iir_df2t.h |
Adds DF2T metadata. |
src/include/sof/math/iir_df2t_generic.h |
Documents generic DF2T helpers. |
src/include/sof/math/iir_df1.h |
Documents DF1 lifecycle APIs. |
src/include/sof/math/iir_df1_generic.h |
Documents generic DF1 helpers. |
src/include/sof/math/fft.h |
Documents FFT plan APIs. |
src/include/sof/math/decibels.h |
Documents decibel conversions. |
src/include/sof/math/dct.h |
Documents DCT lifecycle APIs. |
src/include/sof/math/auditory.h |
Expands mel-filterbank documentation. |
src/include/sof/lib/uuid.h |
Regroups UUID APIs. |
src/include/sof/lib/dai-zephyr.h |
Regroups and documents DAI stubs. |
src/include/sof/lib/dai-legacy.h |
Regroups legacy DAI APIs. |
src/include/sof/lib/agent.h |
Documents system-agent APIs. |
src/include/sof/ipc/topology.h |
Documents parameter verification. |
src/include/sof/drivers/ssp.h |
Documents SSP register helpers. |
src/include/sof/debug/telemetry/telemetry.h |
Documents telemetry access. |
src/include/sof/audio/smart_amp/smart_amp.h |
Documents callback selection. |
src/include/sof/audio/pipeline.h |
Documents and changes pipeline state. |
src/include/sof/audio/pcm_converter.h |
Documents copy converters. |
src/include/sof/audio/format_generic.h |
Documents saturation helpers. |
src/include/sof/audio/component.h |
Regroups and changes component tracing/state. |
src/include/sof/audio/component_ext.h |
Regroups component helpers. |
src/include/sof/audio/channel_map.h |
Documents channel-map helpers. |
src/include/sof/audio/buffer.h |
Adds metadata and changes trace storage. |
src/include/sof/audio/audio_stream.h |
Regroups and changes stream helpers. |
src/include/sof/audio/audio_buffer.h |
Adds buffer API metadata. |
src/include/module/module/system_service.h |
Documents module system services. |
src/include/module/module/llext.h |
Documents LLEXT declarations. |
src/include/module/module/interface.h |
Documents module interfaces. |
src/include/module/module/base.h |
Documents base module definitions. |
src/include/module/audio/source_api.h |
Documents and changes source API. |
src/include/module/audio/sink_api.h |
Documents and changes sink API. |
src/include/module/audio/format.h |
Documents module format helpers. |
src/include/kernel/mailbox.h |
Regroups mailbox registers. |
src/include/ipc4/pipeline.h |
Adds IPC4 grouping metadata. |
src/include/ipc4/notification.h |
Documents and changes notifications. |
src/include/ipc4/module.h |
Adds IPC4 module metadata. |
src/include/ipc4/logging.h |
Documents logging control. |
src/include/ipc4/header.h |
Documents headers and adjusts constants. |
src/include/ipc4/handler.h |
Documents and changes handler declarations. |
src/include/ipc4/gateway.h |
Corrects gateway metadata. |
src/include/ipc4/fw_reg.h |
Updates firmware-register metadata. |
src/include/ipc4/error_status.h |
Updates error-status metadata. |
src/include/ipc4/base_fw.h |
Documents base firmware APIs. |
src/include/ipc4/alh.h |
Documents ALH helpers. |
src/include/ipc/header.h |
Migrates IPC3 taxonomy. |
src/include/ipc/control.h |
Migrates IPC3 controls taxonomy. |
src/audio/volume/volume.h |
Groups the volume component. |
src/audio/volume/peak_volume.h |
Documents peak-volume definitions. |
src/audio/up_down_mixer/up_down_mixer.h |
Documents channel-map helpers. |
src/audio/template/template.h |
Overhauls template documentation. |
src/audio/template/template-generic.c |
Removes duplicate Doxygen output. |
src/audio/stft_process/stft_process.h |
Overhauls STFT API documentation. |
src/audio/stft_process/stft_process_common.c |
Updates STFT implementation docs. |
src/audio/src/src_common.h |
Adds SRC component metadata. |
src/audio/sound_dose/sound_dose.h |
Overhauls sound-dose documentation. |
src/audio/sound_dose/sound_dose-generic.c |
Removes duplicate Doxygen output. |
src/audio/phase_vocoder/phase_vocoder.h |
Updates phase-vocoder documentation. |
src/audio/phase_vocoder/phase_vocoder_common.c |
Removes duplicate Doxygen output. |
src/audio/mixer/mixer.h |
Adds mixer component metadata. |
src/audio/level_multiplier/level_multiplier.h |
Overhauls multiplier documentation. |
src/audio/eq_iir/eq_iir.h |
Adds IIR component metadata. |
src/audio/eq_fir/eq_fir.h |
Adds FIR component metadata. |
src/audio/drc/drc.h |
Documents DRC interfaces. |
src/audio/dcblock/dcblock.h |
Documents DC-block configuration. |
src/audio/aria/aria.h |
Expands Aria API documentation. |
posix/include/sof/lib/pm_runtime.h |
Regroups POSIX PM runtime. |
posix/include/sof/lib/dma.h |
Regroups and documents POSIX DMA. |
posix/include/rtos/alloc.h |
Regroups POSIX allocation. |
doc/sof.doxygen.in |
Expands and configures Doxygen generation. |
doc/mainpage.dox |
Adds the API landing page. |
doc/groups.dox |
Defines the nine-subsystem taxonomy. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
lgirdwood
force-pushed
the
topic/doxygen-c-api-architecture
branch
2 times, most recently
from
October 11, 2026 20:11
1c07340 to
f80e77e
Compare
…an paths Configure Doxygen build parameters to properly index modern SOF headers and generate clean documentation: - Set STRIP_FROM_PATH and STRIP_FROM_INC_PATH with @top_srcdir@ so that file names and include paths are stripped of host-absolute paths. - Expand INPUT directories to include IPC4, LLEXT module interface, user headers, and mainpage/groups definitions. - Expand common file-scope macros in PREDEFINED (LOG_MODULE_*, SOF_DEFINE_REG_UUID, DECLARE_TR_CTX, DECLARE_MODULE_ADAPTER, SOF_MODULE_INIT, EXPORT_SYMBOL, STATIC_ASSERT, BUILD_ASSERT, SYS_INIT, CONFIG_IPC_MAJOR_4, CONFIG_IPC_MAJOR_3) so Doxygen parses declarations cleanly without generating spurious macro-derived functions. - Enable GENERATE_TREEVIEW and set DOT_GRAPH_MAX_NODES to 250 for clean navigation and call/include graph rendering. - Remove obsolete HTML_TIMESTAMP configuration. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…legacy uapi misnomer Define the 9 unified architectural topic groups for Sound Open Firmware in doc/groups.dox (IPC4 Host-DSP Protocol, IPC3 Host-DSP Protocol, Loadable Module & LLEXT Interface, Pipeline & Buffer Infrastructure, Audio Processing Components, RTOS Abstraction Layer, DSP Math & Filter Libraries, Telemetry, Logging & Probes, and Platform & Hardware Drivers). Eliminate the historical "uAPI" misnomer in src/include/ipc/header.h and src/include/ipc/control.h by migrating sof_uapi and sof_uapi_control to ipc3_api. IPC is a host-to-DSP firmware protocol, not a userspace API. Reassign legacy and driver groups (fw_regs_api, uuid_api, platform_api, pm_runtime, sof_dma_drivers, component_api, audio_stream_api) directly into their respective parent architectural topics, and replace the redundant sof_dma_copy_func group with inline function documentation. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…system index Add doc/mainpage.dox to define the primary landing page for the Doxygen C API reference documentation. Document the core architecture, provide a subsystem mapping table with direct links to groups and key headers, and provide quick navigation links to the architectural topics and data structure indices. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add comprehensive Doxygen documentation (@file, @brief, @PARAM, @return, @InGroup) for core SOF RTOS abstractions, audio pipeline infrastructure, platform drivers, DSP math algorithms, and IPC4 protocol interfaces: - RTOS abstraction (@InGroup rtos_api): Document memory heaps and allocation (alloc.h), cache writeback and invalidation (cache.h), clocks (clk.h), mutexes (mutex.h), spinlocks (spinlock.h), timers (timer.h), userspace privilege helpers (kernel.h, userspace_helper.h), and core SOF runtime context (sof.h). - Audio Pipeline & Buffers (@InGroup audio_pipeline_api, module_api): Document pipeline execution and graph links (pipeline.h), audio stream buffers (audio_buffer.h, buffer.h), format conversions (format_generic.h, pcm_converter.h, format.h, sink_api.h, source_api.h), channel maps (channel_map.h), smart amplifier (smart_amp.h), LLEXT module infrastructure (base.h, interface.h, llext.h, system_service.h), and schedulers (schedule.h, ll_schedule.h, dp_schedule.h, edf_schedule.h). - DSP math libraries (@InGroup dsp_math_api): Document FFT plan creation and execution (fft.h), IIR Direct Form 1 & 2 Transposed filters (iir_df1.h, iir_df1_generic.h, iir_df2t.h, iir_df2t_generic.h), decibel/linear conversions (decibels.h), psychoacoustic mel filterbank (auditory.h), DCT plan generation (dct.h), trigonometric lookup tables (lut_trig.h, trig.h), matrix operations (matrix.h), window functions (window.h), and fixed-point numbers (numbers.h). - Host-DSP IPC4 Protocol (@InGroup ipc4_api): Document base firmware initialization (base_fw.h, base_fw_vendor.h), gateway descriptors (gateway.h, alh.h), error statuses (error_status.h), logging rings (logging.h), pipeline messages (pipeline.h), notifications (notification.h), message headers (header.h), and IPC dispatch handlers (handler.h). - Platform Drivers & Telemetry (@InGroup platform_drivers_api, probe_api): Document DAI interfaces (dai-zephyr.h), SSP driver registers (ssp.h), system agent scheduling (agent.h), performance counters (telemetry.h), and trace ticks (trace.h). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
lgirdwood
force-pushed
the
topic/doxygen-c-api-architecture
branch
from
October 11, 2026 20:33
f80e77e to
17cd1e1
Compare
PR 11294: test resultsRun date: 2026-10-12 11:35 UTC Tested commit: 17cd1e14c1616c6bfe95ec27f8bfc1ae6633e05f
|
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 modernizes and overhauls Sound Open Firmware's Doxygen C API architecture and reference documentation, introducing a structured landing portal, establishing a unified 9-subsystem architectural taxonomy, eliminating legacy terminology, and comprehensively documenting public header functions.
Key Changes
Doxygen Build & Toolchain Configuration:
STRIP_FROM_PATHandSTRIP_FROM_INC_PATHwith@top_srcdir@so file names, graphs, and links display clean relative paths.INPUTto include IPC4, LLEXT modules, audio processing components, math libraries, and debug probes.PREDEFINED(LOG_MODULE_*,SOF_DEFINE_REG_UUID,DECLARE_TR_CTX,DECLARE_MODULE_ADAPTER,SOF_MODULE_INIT,EXPORT_SYMBOL,BUILD_ASSERT,STATIC_ASSERT,SYS_INIT) to prevent Doxygen from generating spurious macro-derived function declarations.GENERATE_TREEVIEW = YESand setsDOT_GRAPH_MAX_NODES = 100for responsive graph rendering.Unified 9-Subsystem Architecture Taxonomy & uAPI Cleanup:
doc/groups.dox:ipc4_api)ipc3_api)module_api)audio_pipeline_api)audio_components_api)rtos_api)dsp_math_api)probe_api)platform_drivers_api)sof_uapiandsof_uapi_controlinsrc/include/ipc/header.handcontrol.h), migrating them toipc3_api. IPC is a host-to-DSP firmware protocol, not a userspace API.platform_api,sof_dai_drivers,sof_dma_drivers,pm_runtime,schedule_api,alloc_api,uuid_api,fw_regs_api) directly into their parent architecture topics.sof_dma_copy_funcgroup with inline function documentation.Doxygen Landing Page:
doc/mainpage.doxproviding an architectural overview, platform compatibility matrix, subsystem mapping table with direct links to groups and key headers, and quick reference navigation links.Audio Components & DSP Math Documentation:
@file,@brief,@param,@return, and@ingroupdocumentation across audio processing components (Aria, DC Block, DRC, EQ FIR/IIR, Level Multiplier, Mixer, Phase Vocoder, Sound Dose, STFT, Template, Up/Down Mixer, Volume, Peak Volume).Core RTOS, Pipeline, Drivers & IPC4 Interfaces:
zephyr/include/rtos/.Patch Series Breakdown (5 Commits)
doc: configure Doxygen for extended headers, macro expansion, and clean pathsdoc: establish core C API architectural group taxonomy and eliminate legacy uapi misnomerdoc: add Doxygen landing mainpage with architectural overview and subsystem indexdoc: audio: fix component and math library documentation syntax and add missing docstringsdoc: core: document RTOS, pipeline, drivers, and IPC4 interfacesVerification
ninja -C build_doxygen doc).make htmlinsof-docs).topics.htmlrenders exactly 9 flat, top-level architectural groups with no wrapper splitting or orphan rows.rules-woke.yaml).Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>.