Repository navigation
Conversation
…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, audio processing components, math routines, and debug probes. - 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) so Doxygen parses declarations cleanly without generating spurious macro-derived functions. - Enable GENERATE_TREEVIEW and set DOT_GRAPH_MAX_NODES to 100 for clean navigation and call/include graph rendering. 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) 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>
…dd missing docstrings Add comprehensive Doxygen documentation (@file, @brief, @PARAM, @return, @InGroup) for audio processing components and DSP mathematics libraries: - Audio processing components (@InGroup audio_components_api): Document Aria gain algorithms (aria.h), DC blocking filters (dcblock.h), DRC passthrough (drc.h), up/down mixer channels (up_down_mixer.h), peak volume curves (peak_volume.h, volume.h), STFT processing routines (stft_process.h, stft_process_common.c), phase vocoder format maps (phase_vocoder.h, phase_vocoder_common.c), sound dose maps (sound_dose.h, sound_dose-generic.c), level multiplier (level_multiplier.h), and template component format maps (template.h, template-generic.c). - 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, auditory.c), DCT plan generation (dct.h, dct.c), trigonometric lookup tables (lut_trig.h, trig.h, atan2.c), matrix operations (matrix.h), window functions (window.h), fixed-point numbers (numbers.h), and companding (mu_law.c). 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, 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, audio_stream.h), format conversions (format_generic.h, pcm_converter.h, format.h), channel maps (channel_map.h), and schedulers (schedule.h, ll_schedule.h, dp_schedule.h, edf_schedule.h). - Host-DSP IPC4 Protocol (@InGroup ipc4_api): Document base firmware initialization (base_fw.h), gateway descriptors (gateway.h, alh.h), error statuses (error_status.h), logging rings (logging.h), pipeline messages (pipeline.h), notifications (notification.h), and IPC dispatch handlers (handler.h). - Platform Drivers & Telemetry (@InGroup platform_drivers_api, probe_api): Document DAI interfaces (dai-zephyr.h, dai-legacy.h), SSP driver registers (ssp.h), system agent scheduling (agent.h), performance counters (telemetry.h), trace ticks (trace.h), and probe buffers (probe.c). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Commit d477607 ("doc: core: document RTOS, pipeline, drivers, and IPC4 interfaces") inadvertently reintroduced several header conflicts and regressions from older revisions: - zephyr/include/rtos/userspace_helper.h: Restore missing #else before the user_access_to_mailbox() stub when CONFIG_USERSPACE is disabled, resolving conflicting static vs non-static declaration build errors. - src/include/sof/audio/audio_stream.h: Remove redundant cir_buf_bytes_without_wrap() which was relocated to module/audio/audio_stream.h returning size_t; restore uintptr_t and size_t types in pointer arithmetic and boundary checks. - src/include/sof/audio/buffer.h: Keep tctx conditionally guarded by !CONFIG_ZEPHYR_LOG and keep trace_buf_get_tr_ctx definition in the non-Zephyr branch. - src/include/sof/audio/component.h: Restore SOF_DRV_UID_NAME macro, CONFIG_ZEPHYR_LOG guards for tctx, expect_eos in comp_dev, and !CONFIG_ZEPHYR_LOG check in comp_init(). - src/include/sof/audio/pipeline.h: Restore mod_alloc_ctx *alloc, pipeline_set_eos(), and remove expect_eos (which lives in comp_dev). - src/include/module/audio/sink_api.h: Restore get_state ops callback and sink_get_state() helper. - src/include/module/audio/source_api.h: Restore get_state ops callback and source_get_comp_state() helper. - src/include/ipc4/handler.h: Restore ipc4_user_module_load() and remove non-static declaration of static ipc4_process_large_config_get(). - src/include/ipc4/notification.h: Restore send_resource_notif() syscall declarations. - src/probe/probe.c: Keep dma_get_status() return code check intact. Fixes: thesofproject#11294 Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
lgirdwood
force-pushed
the
topic/doxygen-c-api-architecture
branch
3 times, most recently
from
October 11, 2026 20:33
f80e77e to
17cd1e1
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
2 participants
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
Fixes the Zephyr build failures on PR thesofproject#11294 across all platforms (PTL, LNL, TGL, MTL, i.MX8, etc.).
Commit d477607 ("doc: core: document RTOS, pipeline, drivers, and IPC4 interfaces") inadvertently reintroduced header conflicts and regressions from older revisions prior to recent upstream changes:
zephyr/include/rtos/userspace_helper.h:#elsebefore theuser_access_to_mailbox()no-op stub whenCONFIG_USERSPACEis disabled. This resolves the compiler error:src/include/sof/audio/audio_stream.h:cir_buf_bytes_without_wrap()which was already moved tomodule/audio/audio_stream.hreturningsize_t. This resolves:uintptr_tandsize_ttypes in pointer arithmetic and boundary checks.src/include/sof/audio/buffer.h:#if !CONFIG_ZEPHYR_LOGguards aroundstruct tr_ctx tctxand kepttrace_buf_get_tr_ctxin the non-Zephyr branch.src/include/sof/audio/component.h:SOF_DRV_UID_NAMEmacro,!CONFIG_ZEPHYR_LOGguards fortctx, andexpect_eosinstruct comp_dev.src/include/sof/audio/pipeline.h:struct mod_alloc_ctx *allocandpipeline_set_eos(); removedexpect_eos(which belongs incomp_dev).src/include/module/audio/sink_api.h&src/include/module/audio/source_api.h:get_stateops callbacks,sink_get_state(), andsource_get_comp_state().src/include/ipc4/handler.h:ipc4_user_module_load()and removed invalid non-static declaration ofipc4_process_large_config_get().src/include/ipc4/notification.h:send_resource_notif()syscall declarations.src/probe/probe.c:dma_get_status()return code check.Fixes thesofproject#11294