Repository navigation
doc: align core C APIs with Doxygen taxonomy, scheduling, memory, pipeline, and module documentation - #11296
Open
lgirdwood wants to merge 6 commits into
Open
doc: align core C APIs with Doxygen taxonomy, scheduling, memory, pipeline, and module documentation#11296lgirdwood wants to merge 6 commits into
lgirdwood wants to merge 6 commits into
Conversation
lgirdwood
requested review from
LaurentiuM1234,
abonislawski,
dbaluta,
iuliana-prodan,
kv2019i,
lbetlej,
lyakh,
marcinszkudlinski,
mmaka1,
pblaszko and
plbossart
as code owners
October 12, 2026 18:09
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Several headers lose licensing metadata, and multiple rewritten API contracts contain incorrect or omitted behavioral constraints.
19 open findings
What changed in this PR
This PR reorganizes SOF’s core C API documentation into architectural Doxygen groups and expands scheduling, memory, pipeline, buffer, component, and module documentation.
Changes:
- Adds Doxygen taxonomy and main-page navigation.
- Documents core APIs, structures, callbacks, and parameters.
- Expands Doxygen preprocessing for conditional Zephyr APIs.
| File | Description |
|---|---|
zephyr/include/sof/lib/vpage.h |
Documents virtual-page allocation. |
zephyr/include/sof/lib/regions_mm.h |
Documents VMH region allocation. |
zephyr/include/sof/lib/mm_heap.h |
Marks the compatibility shim deprecated. |
zephyr/include/sof/lib/memory.h |
Documents memory attributes and debug helpers. |
zephyr/include/rtos/task.h |
Documents Zephyr task APIs. |
zephyr/include/rtos/alloc.h |
Expands allocator documentation. |
src/schedule/zephyr_dp_schedule.h |
Documents internal DP scheduler state. |
src/platform/library/include/platform/lib/ll_schedule.h |
Documents testbench LL scheduling. |
src/include/sof/schedule/twb_schedule.h |
Documents TWB scheduling. |
src/include/sof/schedule/schedule.h |
Documents generic scheduler contracts. |
src/include/sof/schedule/ll_schedule.h |
Documents LL task scheduling. |
src/include/sof/schedule/ll_schedule_domain.h |
Documents LL domains and operations. |
src/include/sof/schedule/edf_schedule.h |
Documents legacy EDF scheduling. |
src/include/sof/schedule/dp_schedule.h |
Documents DP scheduling. |
src/include/sof/lib/vregion.h |
Documents virtual-region allocation. |
src/include/sof/lib/fast-get.h |
Documents SRAM staging. |
src/include/sof/ipc/schedule.h |
Documents IPC scheduling. |
src/include/sof/coherent.h |
Documents cache-coherency APIs. |
src/include/sof/audio/source_api.h |
Documents source helpers. |
src/include/sof/audio/sink_api.h |
Documents sink helpers. |
src/include/sof/audio/ring_buffer.h |
Documents lockless ring buffers. |
src/include/sof/audio/pipeline.h |
Expands pipeline API documentation. |
src/include/sof/audio/module_adapter/module/generic.h |
Documents module allocation helpers. |
src/include/sof/audio/format_generic.h |
Reclassifies format helpers. |
src/include/sof/audio/component.h |
Expands component infrastructure documentation. |
src/include/sof/audio/component_ext.h |
Documents component wrappers. |
src/include/sof/audio/channel_map.h |
Reclassifies channel-map APIs. |
src/include/sof/audio/buffer.h |
Documents component buffers. |
src/include/sof/audio/audio_stream.h |
Reclassifies stream APIs. |
src/include/sof/audio/audio_buffer.h |
Documents abstract audio buffers. |
src/include/module/audio/audio_stream.h |
Groups module stream utilities. |
posix/include/rtos/task.h |
Documents POSIX task APIs. |
doc/sof.doxygen.in |
Exposes conditional APIs to Doxygen. |
doc/mainpage.dox |
Expands API navigation. |
doc/groups.dox |
Defines the new taxonomy. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Add configuration flags and compiler attributes to Doxygen PREDEFINED macro expansion: - CONFIG_SOF_VREGIONS, CONFIG_INCOHERENT, __ZEPHYR__, CONFIG_LLEXT, CONFIG_LLEXT_TYPE_ELF_RELOCATABLE, CONFIG_SOF_USERSPACE_INTERFACE_ALLOC, CONFIG_SOF_FULL_ZEPHYR_APPLICATION, and CONFIG_SOF_USERSPACE_USE_SHARED_HEAP. - __DOXYGEN__, __coherent, __syscall, and __must_check attributes. This ensures Doxygen correctly parses and documents conditional API declarations across memory, RTOS, and scheduling interfaces without requiring conditional compilation guards in C source files. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Update doc/groups.dox to define group hierarchy and taxonomy across core SOF C APIs: - Add scheduling_api group for real-time task scheduling. - Add memory_api group for multi-tier memory management. - Partition pipeline APIs into audio_pipeline_api, component_infra_api, audio_buffer_api, and audio_format_api. - Update module_api description to unify audio processing components and dynamic LLEXT modules. Update doc/mainpage.dox navigation matrix to link to the new architectural groups and key subsystem headers. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
lgirdwood
force-pushed
the
topic/doxygen-core-c-api-alignment
branch
from
October 12, 2026 18:50
2f435bf to
555c64c
Compare
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Several updated API contracts contain incorrect units, parameter semantics, and runtime behavior.
13 open findings
19 resolved since last review
🧠 Review effort: Balanced
Add comprehensive Doxygen documentation across the Sound Open Firmware scheduling subsystem: - Low-Latency (LL) timer and DMA schedule domains, ratio/skip-counter rate alignment, and task initialization interfaces. - Data Processing (DP) preemptible worker threads, dynamic deadline calculation, and synchronous IPC parameter dispatching. - Thread With Budget (TWB) cycle accounting and priority management. - Deprecation notices for legacy Earliest Deadline First (EDF) workqueue interfaces, scoped to host IPC and legacy KPB draining tasks until migration to DP threads. - Core task state machines, operations callbacks, and POSIX/Zephyr RTOS task abstractions. All changes are strictly documentation comments; no C code syntax, types, macros, or prototypes are modified. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add comprehensive Doxygen documentation for the Sound Open Firmware multi-tier DSP memory management architecture: - Core RTOS heap allocators (rmalloc, rmalloc_align, rfree, rzalloc), zone flags (SOF_MEM_FLAG_*), and Zephyr heap wrappers (sof_heap_alloc). - Virtual Memory Heap (VMH) and multi-block allocators (regions_mm.h). - Virtual regions (vregion.h), distinguishing lifetime topology/module allocations from interim dynamic parameter allocations. - Dynamic DRAM staging interfaces (fast_get, fast_put). - Multi-core cache coherency primitives (coherent_acquire, coherent_release, coherent_init, coherent_free). - Virtual page allocators (vpage.h) and memory attributes (memory.h). All changes are strictly documentation comments; no C code syntax, types, macros, or prototypes are modified. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…APIs Add comprehensive Doxygen documentation across the Sound Open Firmware audio pipeline infrastructure: - Pipeline DAG construction, component graph iteration, scheduling task binding, and pipeline lifecycle state transitions (pipeline.h). - Unified audio component driver model (comp_ops), trigger state machines, IPC module bindings, and copy limits (component.h, component_ext.h). - Pipeline interconnect buffers (comp_buffer), abstract audio buffers (sof_audio_buffer), and lockless cross-core ring buffers (buffer.h, audio_buffer.h, ring_buffer.h). - Multi-channel audio channel mapping and format conversions (channel_map.h, format_generic.h). All changes are strictly documentation comments; no C code syntax, types, macros, or prototypes are modified. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add comprehensive Doxygen documentation for audio processing modules and streaming endpoints: - Circular buffer frame and sample calculation utilities (audio_stream.h). - Streaming sink and source interfaces for module data processing (sink_api.h, source_api.h). - Module memory allocators (mod_alloc, mod_balloc, mod_alloc_ext), heap diagnostics, and lifecycle resource teardown (generic.h). All changes are strictly documentation comments; no C code syntax, types, macros, or prototypes are modified. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
PR 11296: test resultsRun date: 2026-10-12 20:53 UTC Tested commit: e2d56f1284d1de1fe29c7219a61ad0fd0e8ce473
|
lgirdwood
force-pushed
the
topic/doxygen-core-c-api-alignment
branch
from
October 12, 2026 19:48
555c64c to
e2d56f1
Compare
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 establishes a comprehensive Doxygen documentation upgrade across Sound Open Firmware's core C API headers, structuring APIs into clean architectural groups and documenting subsystems that were previously undocumented or lacked proper parameter direction attributes.
Strict Doc-Only Policy: None of the patches in this series modify any C code syntax, structs, enums, macros, or prototypes. All preprocessor visibility flags and compiler attributes are handled cleanly via Doxygen's
PREDEFINEDconfiguration indoc/sof.doxygen.in.Patch Series Overview
doc: doxygen: expand PREDEFINED macros for conditional API headersPREDEFINEDmacro expansion (CONFIG_SOF_VREGIONS,CONFIG_INCOHERENT,__ZEPHYR__,CONFIG_LLEXT,CONFIG_SOF_USERSPACE_INTERFACE_ALLOC,CONFIG_SOF_FULL_ZEPHYR_APPLICATION,CONFIG_SOF_USERSPACE_USE_SHARED_HEAP,__coherent,__syscall,__must_check).#ifdef __DOXYGEN__modifications in C headers.doc: groups: establish C API group taxonomy and mainpage navigationdoc/groups.doxfor core subsystems:@defgroup scheduling_api Real-Time Scheduling Infrastructure@defgroup memory_api Memory Management Infrastructure@defgroup audio_pipeline_api Audio Pipeline Graph & Execution@defgroup component_infra_api Audio Component Driver Model & Infrastructure@defgroup audio_buffer_api Audio Buffers & Interconnect Streams@defgroup audio_format_api Audio Formats & Channel Routing@defgroup module_apito cover both built-in components and dynamic LLEXT modules.doc/mainpage.doxnavigation matrix to link to the new architectural groups and key subsystem headers.doc: schedule: document real-time scheduling infrastructuredoc: rtos: memory: document multi-tier memory management infrastructurermalloc,rmalloc_align,rfree,rzalloc), zone flags (SOF_MEM_FLAG_*), and Zephyr heap wrappers (sof_heap_alloc).regions_mm.h).vregion.h), distinguishing lifetime topology/module allocations from interim dynamic parameter allocations.fast_get,fast_put).coherent_acquire,coherent_release,coherent_init,coherent_free).vpage.h) and memory attributes (memory.h).doc: audio: pipeline: document pipeline graph, component, and buffer APIspipeline.h).comp_ops), trigger state machines, IPC module bindings, and copy limits (component.h,component_ext.h).comp_buffer), abstract audio buffers (sof_audio_buffer), and lockless cross-core ring buffers (buffer.h,audio_buffer.h,ring_buffer.h).channel_map.h,format_generic.h).doc: audio: module: document module interface and streaming endpointssize_treturn types inaudio_stream.h).sink_api.h,source_api.h).mod_alloc,mod_balloc,mod_alloc_ext), heap diagnostics, and lifecycle resource teardown (generic.h).Verification
origin/mainacross all 35 files verifies exactly 0 code changes.ninja -C build_doxygen doccompletes with 0 warnings and 0 errors.make -C sof-docs html SOF_ROOT=sofcompletes with 0 warnings and 0 errors under-W.