From 9647d834e4fbae0b15847e5a9ade96c17c61a56d Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sun, 11 Oct 2026 21:32:49 +0100 Subject: [PATCH 1/4] doc: configure Doxygen for extended headers, macro expansion, and clean 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 --- doc/sof.doxygen.in | 51 ++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/doc/sof.doxygen.in b/doc/sof.doxygen.in index a54481858b31..b9a2867b4f73 100644 --- a/doc/sof.doxygen.in +++ b/doc/sof.doxygen.in @@ -5,17 +5,30 @@ GENERATE_RTF = NO GENERATE_MAN = NO GENERATE_XML = YES +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = @top_srcdir@ +STRIP_FROM_INC_PATH = @top_srcdir@ + CASE_SENSE_NAMES = NO INPUT = @top_srcdir@/src/include/ipc \ + @top_srcdir@/src/include/ipc3 \ + @top_srcdir@/src/include/ipc4 \ + @top_srcdir@/src/include/module \ @top_srcdir@/src/include/kernel \ - @top_srcdir@/src/include/user \ + @top_srcdir@/src/include/user \ @top_srcdir@/src/include/sof \ @top_srcdir@/xtos/include \ - @top_srcdir@/zephyr/include -# Exlude some 3rd party codec headers with external references + @top_srcdir@/zephyr/include \ + @top_srcdir@/doc/groups.dox \ + @top_srcdir@/doc/mainpage.dox +# Exclude some 3rd party codec headers with external references EXCLUDE = @top_srcdir@/src/include/sof/audio/MaxxEffect +EXCLUDE_PATTERNS = */test/* \ + */mock/* \ + *.mock.* \ + */build* RECURSIVE = YES -FILE_PATTERNS = *.c *.h +FILE_PATTERNS = *.c *.h *.dox EXAMPLE_PATH = @top_srcdir@/test IMAGE_PATH = QUIET = YES @@ -32,13 +45,33 @@ EXPAND_ONLY_PREDEF = YES PREDEFINED = "__attribute__(x)= " \ "CONFIG_FORMAT_S16LE=1" \ "CONFIG_FORMAT_S32LE=1" \ - "CONFIG_TRACE=1" + "CONFIG_FORMAT_S24LE=1" \ + "CONFIG_TRACE=1" \ + "CONFIG_IPC4=1" \ + "CONFIG_IPC3=1" \ + "CONFIG_IPC_MAJOR_4=1" \ + "CONFIG_IPC_MAJOR_3=1" \ + "CONFIG_COMP_VOLUME=1" \ + "__packed=" \ + "__aligned(x)=" \ + "__sparse_cache=" \ + "__kernel=" \ + "__user=" \ + "LOG_MODULE_REGISTER(x,...)= " \ + "LOG_MODULE_DECLARE(x,...)= " \ + "SOF_DEFINE_REG_UUID(x)= " \ + "DECLARE_TR_CTX(x,...)= " \ + "DECLARE_MODULE_ADAPTER(x,...)= " \ + "SOF_MODULE_INIT(x,...)= " \ + "EXPORT_SYMBOL(x)= " \ + "STATIC_ASSERT(x,...)= " \ + "BUILD_ASSERT(x,...)= " \ + "SYS_INIT(x,...)= " OPTIMIZE_OUTPUT_FOR_C = YES TYPEDEF_HIDES_STRUCT = YES -#INPUT_FILTER = inputfilter -#FILTER_SOURCE_FILES = YES - -HTML_TIMESTAMP = NO +GENERATE_TREEVIEW = YES +SEARCHENGINE = YES +DOT_GRAPH_MAX_NODES = 250 WARN_AS_ERROR = NO From 2753c187131cbcb5d1bb9939a8b44a25ac70cf6c Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sun, 11 Oct 2026 21:10:35 +0100 Subject: [PATCH 2/4] doc: establish core C API architectural group taxonomy and eliminate 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 --- doc/groups.dox | 56 +++++++++++++++++++++++++++ posix/include/rtos/alloc.h | 2 +- posix/include/sof/lib/dma.h | 14 +++---- posix/include/sof/lib/pm_runtime.h | 2 +- src/include/ipc/control.h | 4 +- src/include/ipc/header.h | 4 +- src/include/kernel/mailbox.h | 2 +- src/include/sof/audio/audio_stream.h | 2 +- src/include/sof/audio/component.h | 4 +- src/include/sof/audio/component_ext.h | 2 +- src/include/sof/lib/dai-legacy.h | 2 +- src/include/sof/lib/uuid.h | 2 +- src/include/sof/platform.h | 2 +- zephyr/include/sof/lib/dma-legacy.h | 12 +++--- zephyr/include/sof/lib/dma.h | 2 +- zephyr/include/sof/lib/pm_runtime.h | 6 ++- 16 files changed, 89 insertions(+), 29 deletions(-) create mode 100644 doc/groups.dox diff --git a/doc/groups.dox b/doc/groups.dox new file mode 100644 index 000000000000..4f30724492f7 --- /dev/null +++ b/doc/groups.dox @@ -0,0 +1,56 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright(c) 2026 Intel Corporation. All rights reserved. + * + * Author: Liam Girdwood + */ + +/** + * @file groups.dox + * @brief Sound Open Firmware C API architecture group definitions. + */ + +/** + * @defgroup ipc4_api IPC4 Host-DSP Protocol + * @brief Intel and AMD IPC4 protocol definitions, message structures, base firmware, gateways, and notifications. + */ + +/** + * @defgroup ipc3_api IPC3 Host-DSP Protocol + * @brief Legacy IPC3 protocol definitions, commands, and stream controls. + */ + +/** + * @defgroup module_api Loadable Module & LLEXT Interface + * @brief Dynamic module loading, processing component lifecycle, and buffer streaming endpoints. + */ + +/** + * @defgroup audio_pipeline_api Pipeline & Buffer Infrastructure + * @brief Audio pipeline execution graphs, stream buffer management, scheduling, and processing threads. + */ + +/** + * @defgroup audio_components_api Audio Processing Components + * @brief Built-in and dynamic audio processing modules (Volume, Mixer, EQ, DRC, SRC, ASRC, etc.). + */ + +/** + * @defgroup rtos_api RTOS Abstraction Layer + * @brief RTOS primitives, synchronization (spinlocks, mutexes), memory allocation, clocks, and cache management. + */ + +/** + * @defgroup dsp_math_api DSP Math & Filter Libraries + * @brief Fixed-point, floating-point, FFT, FIR/IIR accelerators, and vector math routines. + */ + +/** + * @defgroup probe_api Telemetry, Logging & Probes + * @brief Real-time DSP trace logging, probe extraction/injection buffers, DMA telemetry, and panic dumps. + */ + +/** + * @defgroup platform_drivers_api Platform & Hardware Drivers + * @brief Digital Audio Interfaces (DAI), Direct Memory Access (DMA), and Power Management (PM) runtime. + */ diff --git a/posix/include/rtos/alloc.h b/posix/include/rtos/alloc.h index c599afe08d82..adb3c93bf9dd 100644 --- a/posix/include/rtos/alloc.h +++ b/posix/include/rtos/alloc.h @@ -24,7 +24,7 @@ #include #include -/** \addtogroup alloc_api Memory Allocation API +/** \addtogroup rtos_api * @{ */ diff --git a/posix/include/sof/lib/dma.h b/posix/include/sof/lib/dma.h index 0d81c4cb552e..4ed6a7d26edd 100644 --- a/posix/include/sof/lib/dma.h +++ b/posix/include/sof/lib/dma.h @@ -37,7 +37,7 @@ struct comp_buffer; struct comp_dev; struct k_heap; -/** \addtogroup sof_dma_drivers DMA Drivers +/** \addtogroup platform_drivers_api * DMA Drivers API specification. * @{ */ @@ -364,18 +364,18 @@ static inline int dma_stop_delayed_legacy(struct dma_chan_data *channel) return 0; } -/** \defgroup sof_dma_copy_func static int dma_copy (struct dma_chan_data * channel, int bytes, uint32_t flags) - * - * This function is in a separate subgroup to solve a name clash with - * struct dma_copy {} - * @{ +/** + * @brief Perform a legacy DMA copy operation on a channel. + * @param channel DMA channel data. + * @param bytes Number of bytes to transfer. + * @param flags Transfer flags. + * @return 0 on success, negative error code on failure. */ static inline int dma_copy_legacy(struct dma_chan_data *channel, int bytes, uint32_t flags) { return channel->dma->ops->copy(channel, bytes, flags); } -/** @} */ static inline int dma_pause_legacy(struct dma_chan_data *channel) { diff --git a/posix/include/sof/lib/pm_runtime.h b/posix/include/sof/lib/pm_runtime.h index c0a24116e629..4e8cbfdf146f 100644 --- a/posix/include/sof/lib/pm_runtime.h +++ b/posix/include/sof/lib/pm_runtime.h @@ -22,7 +22,7 @@ #include #include -/** \addtogroup pm_runtime PM Runtime +/** \addtogroup platform_drivers_api * PM runtime specification. * @{ */ diff --git a/src/include/ipc/control.h b/src/include/ipc/control.h index 8c7be6d7a0e7..e7922c481890 100644 --- a/src/include/ipc/control.h +++ b/src/include/ipc/control.h @@ -21,8 +21,8 @@ #include #include -/** \addtogroup sof_uapi_control uAPI Control - * SOF uAPI specification - component controls. +/** \addtogroup ipc3_api + * SOF IPC3 component controls. * @{ */ diff --git a/src/include/ipc/header.h b/src/include/ipc/header.h index d8d030f17216..98352b643502 100644 --- a/src/include/ipc/header.h +++ b/src/include/ipc/header.h @@ -36,8 +36,8 @@ struct ipc_cmd_hdr; #define ipc_to_hdr(x) ((struct ipc_cmd_hdr *)x) -/** \addtogroup sof_uapi uAPI - * SOF uAPI specification +/** \addtogroup ipc3_api + * SOF IPC3 protocol specification * * **Overview** * diff --git a/src/include/kernel/mailbox.h b/src/include/kernel/mailbox.h index 1c2d0ff55881..f41be84fb3b9 100644 --- a/src/include/kernel/mailbox.h +++ b/src/include/kernel/mailbox.h @@ -18,7 +18,7 @@ #include #endif -/** \addtogroup fw_regs_api FW Regs API +/** \addtogroup probe_api * This is a common SRAM window 0 FW "registers" layout * used in the platfrom-defined SRAM window 0 region * @{ diff --git a/src/include/sof/audio/audio_stream.h b/src/include/sof/audio/audio_stream.h index ffb5f88c4594..93d42d095dc1 100644 --- a/src/include/sof/audio/audio_stream.h +++ b/src/include/sof/audio/audio_stream.h @@ -30,7 +30,7 @@ #include #include -/** \addtogroup audio_stream_api Audio Stream API +/** \addtogroup audio_pipeline_api * @{ */ diff --git a/src/include/sof/audio/component.h b/src/include/sof/audio/component.h index 7fb098f449e2..c290001107d2 100644 --- a/src/include/sof/audio/component.h +++ b/src/include/sof/audio/component.h @@ -38,7 +38,7 @@ struct dai_hw_params; struct timestamp_data; struct dai_ts_data; -/** \addtogroup component_api Component API +/** \addtogroup audio_pipeline_api * @{ */ @@ -820,7 +820,7 @@ static inline struct comp_buffer *comp_dev_get_next_data_consumer_safe(struct co * begin here. */ -/** \addtogroup component_common_int Component's Common Helpers +/** \addtogroup audio_pipeline_api * @{ */ diff --git a/src/include/sof/audio/component_ext.h b/src/include/sof/audio/component_ext.h index 63cff9759425..4bb88cce72e2 100644 --- a/src/include/sof/audio/component_ext.h +++ b/src/include/sof/audio/component_ext.h @@ -19,7 +19,7 @@ #include #include -/** \addtogroup component_api_helpers Component Mgmt API +/** \addtogroup audio_pipeline_api * @{ */ diff --git a/src/include/sof/lib/dai-legacy.h b/src/include/sof/lib/dai-legacy.h index c1b7c0a28653..4e050e6b87c8 100644 --- a/src/include/sof/lib/dai-legacy.h +++ b/src/include/sof/lib/dai-legacy.h @@ -41,7 +41,7 @@ struct dai; struct sof_ipc_stream_params; -/** \addtogroup sof_dai_drivers DAI Drivers +/** \addtogroup platform_drivers_api * DAI Drivers API specification. * @{ */ diff --git a/src/include/sof/lib/uuid.h b/src/include/sof/lib/uuid.h index d45f821613d7..2d8ca2ca82f4 100644 --- a/src/include/sof/lib/uuid.h +++ b/src/include/sof/lib/uuid.h @@ -17,7 +17,7 @@ #include -/** \addtogroup uuid_api UUID API +/** \addtogroup module_api * UUID API specification. * @{ */ diff --git a/src/include/sof/platform.h b/src/include/sof/platform.h index 80fdff077500..070809ad38b1 100644 --- a/src/include/sof/platform.h +++ b/src/include/sof/platform.h @@ -22,7 +22,7 @@ struct sof; -/** \addtogroup platform_api Platform API +/** \addtogroup platform_drivers_api * Platform API specification. * @{ */ diff --git a/zephyr/include/sof/lib/dma-legacy.h b/zephyr/include/sof/lib/dma-legacy.h index 016434e2f143..cb381ce03363 100644 --- a/zephyr/include/sof/lib/dma-legacy.h +++ b/zephyr/include/sof/lib/dma-legacy.h @@ -123,18 +123,18 @@ static inline int dma_stop_delayed_legacy(struct dma_chan_data *channel) return 0; } -/** \defgroup sof_dma_copy_func static int dma_copy (struct dma_chan_data * channel, int bytes, uint32_t flags) - * - * This function is in a separate subgroup to solve a name clash with - * struct dma_copy {} - * @{ +/** + * @brief Perform a legacy DMA copy operation on a channel. + * @param channel DMA channel data. + * @param bytes Number of bytes to transfer. + * @param flags Transfer flags. + * @return 0 on success, negative error code on failure. */ static inline int dma_copy_legacy(struct dma_chan_data *channel, int bytes, uint32_t flags) { return channel->dma->ops->copy(channel, bytes, flags); } -/** @} */ static inline int dma_pause_legacy(struct dma_chan_data *channel) { diff --git a/zephyr/include/sof/lib/dma.h b/zephyr/include/sof/lib/dma.h index 5dcc8455579b..261abe8cacea 100644 --- a/zephyr/include/sof/lib/dma.h +++ b/zephyr/include/sof/lib/dma.h @@ -36,7 +36,7 @@ struct comp_buffer; struct comp_dev; struct k_heap; -/** \addtogroup sof_dma_drivers DMA Drivers +/** \addtogroup platform_drivers_api * SOF DMA Drivers API specification (deprecated interface, to be * replaced by Zephyr zephyr/drivers/dma.h interface). * @{ diff --git a/zephyr/include/sof/lib/pm_runtime.h b/zephyr/include/sof/lib/pm_runtime.h index ee02eff51aad..96fbc1c802eb 100644 --- a/zephyr/include/sof/lib/pm_runtime.h +++ b/zephyr/include/sof/lib/pm_runtime.h @@ -9,7 +9,7 @@ #include #include -/** \addtogroup pm_runtime PM Runtime +/** \addtogroup platform_drivers_api * SOF PM runtime specification mapping for Zephyr builds. * * This interface is considered deprecated and native Zephyr @@ -92,6 +92,10 @@ void pm_runtime_disable(enum pm_runtime_context context, uint32_t index); */ bool pm_runtime_is_active(enum pm_runtime_context context, uint32_t index); +/** + * @brief Prepare platform hardware and power gating for D0ix idle entry. + * @param index Index or context identifier for the target power-managed domain. + */ static inline void platform_pm_runtime_prepare_d0ix_en(uint32_t index) { } From c91908ad7a51857e55c0e12d6ef90cdf99a42833 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sun, 11 Oct 2026 21:10:36 +0100 Subject: [PATCH 3/4] doc: add Doxygen landing mainpage with architectural overview and subsystem 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 --- doc/mainpage.dox | 187 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 doc/mainpage.dox diff --git a/doc/mainpage.dox b/doc/mainpage.dox new file mode 100644 index 000000000000..2b0c574c0411 --- /dev/null +++ b/doc/mainpage.dox @@ -0,0 +1,187 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright(c) 2026 Intel Corporation. All rights reserved. + * + * Author: Liam Girdwood + */ + +/** + * @file mainpage.dox + * @brief Sound Open Firmware C API documentation main page. + */ + +/** + * @mainpage Sound Open Firmware C API & Architecture Reference + * + * @section intro_sec Overview + * + * Sound Open Firmware (SOF) is an open-source, vendor-neutral audio Digital Signal + * Processing (DSP) firmware infrastructure, SDK, and real-time execution environment + * governed under the Linux Foundation. + * + * SOF provides transparent, deterministic, low-latency audio processing for modern computing + * architectures ranging from client PCs and servers to embedded microcontrollers and IoT devices. + * It supports diverse hardware platforms including Intel (CAVS, ACE 1.x, ACE 2.x, ACE 3.x), + * AMD, NXP (i.MX8), MediaTek, Espressif (ESP32-P4), and PJRC (Teensy 4.1 / i.MX RT1062). + * + * The firmware runs atop real-time operating systems (primarily **Zephyr RTOS**, with XTOS support + * on legacy platforms) and interfaces with host operating systems (Linux, ChromeOS, Android, Windows) + * via high-throughput Mailbox IPC protocols (IPC4 and IPC3) and DMA streaming windows. + * + * --- + * + * @section subsystem_sec Subsystem Architecture & API Modules + * + * The firmware codebase is organized into modular functional subsystems. Each subsystem exposes + * structured C APIs, data structures, and lifecycle interfaces: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
SubsystemAPI GroupKey Headers & InterfacesDescription
Host-DSP IPC4 Protocol@ref ipc4_api + * - @ref src/include/ipc4/base_fw.h "ipc4/base_fw.h"
+ * - @ref src/include/ipc4/header.h "ipc4/header.h"
+ * - @ref src/include/ipc4/gateway.h "ipc4/gateway.h"
+ * - @ref src/include/ipc4/pipeline.h "ipc4/pipeline.h"
+ * - @ref src/include/ipc4/notification.h "ipc4/notification.h" + * 		+ * Modern Intel/AMD IPC4 messaging protocol: base firmware configuration, gateway management, + * pipeline creation and state transitions, large parameter get/set, and asynchronous notifications. + *
Host-DSP IPC3 Protocol@ref ipc3_api + * - @ref src/include/ipc/header.h "ipc/header.h"
+ * - @ref src/include/ipc/stream.h "ipc/stream.h"
+ * - @ref src/include/ipc/control.h "ipc/control.h"
+ * - @ref src/include/ipc/topology.h "ipc/topology.h" + * 		+ * Legacy IPC3 protocol structures, stream control envelopes, DAI/buffer tokens, and mixer controls. + *
Loadable Modules & LLEXT@ref module_api + * - @ref src/include/module/module/interface.h "module/interface.h"
+ * - @ref src/include/module/module/api_ver.h "module/api_ver.h"
+ * - @ref src/include/module/module/base.h "module/base.h" + * 		+ * Dynamic ELF module loading infrastructure via Zephyr LLEXT: dynamic symbol linking, module + * interface adapters, processing state machine, parameter configuration, and multi-core routing. + *
Audio Pipeline & Buffers@ref audio_pipeline_api + * - @ref src/include/sof/audio/pipeline.h "sof/audio/pipeline.h"
+ * - @ref src/include/sof/audio/component.h "sof/audio/component.h"
+ * - @ref src/include/sof/audio/buffer.h "sof/audio/buffer.h"
+ * - @ref src/include/sof/audio/audio_buffer.h "sof/audio/audio_buffer.h"
+ * - @ref src/include/sof/schedule/schedule.h "sof/schedule/schedule.h" + * 		+ * Audio pipeline Directed Acyclic Graph (DAG) construction, task scheduling domains (LL-Timer, + * LL-DMA, DP threads), lockless ring buffers, audio format negotiation, and multi-channel interleaved/planar routing. + *
Audio Processing Components@ref audio_components_api + * - @ref src/include/sof/audio/component.h "sof/audio/component.h"
+ * - @ref src/include/sof/audio/component_ext.h "sof/audio/component_ext.h"
+ * - @ref src/include/sof/audio/smart_amp/smart_amp.h "smart_amp/smart_amp.h"
+ * - Modules: Volume, Mixer, EQ FIR/IIR, DRC, SRC, ASRC, Crossover, DC Block, Copier + * 		+ * Standard and optimized DSP audio processing modules: smooth volume ramp, mixing, FIR/IIR + * parametric equalization, dynamic range compression, polyphase sample rate conversion, + * asynchronous sample rate conversion, and DAI copier sinks/sources. + *
RTOS Abstraction Layer (RAL)@ref rtos_api + * - @ref zephyr/include/rtos/alloc.h "rtos/alloc.h"
+ * - @ref zephyr/include/rtos/spinlock.h "rtos/spinlock.h"
+ * - @ref zephyr/include/rtos/mutex.h "rtos/mutex.h"
+ * - @ref zephyr/include/rtos/wait.h "rtos/wait.h"
+ * - @ref zephyr/include/rtos/clk.h "rtos/clk.h"
+ * - @ref zephyr/include/rtos/cache.h "rtos/cache.h"
+ * - @ref zephyr/include/rtos/interrupt.h "rtos/interrupt.h" + * 		+ * Operating system abstraction bridging Zephyr RTOS and XTOS: heap management (sys, lpsram, hpsram), + * spinlocks, mutexes, condition variables, hardware timers, and multi-core Inter-Domain Communication (IDC). + *
DSP Mathematics & Filters@ref dsp_math_api + * - @ref src/include/sof/math/trig.h "sof/math/trig.h"
+ * - @ref src/include/sof/math/fft.h "sof/math/fft.h"
+ * - @ref src/include/user/fir.h "user/fir.h"
+ * - @ref src/include/sof/math/iir_df1.h "sof/math/iir_df1.h"
+ * - @ref src/include/sof/math/numbers.h "sof/math/numbers.h"
+ * - @ref src/include/sof/math/matrix.h "sof/math/matrix.h" + * 		+ * Optimized DSP mathematics routines: fixed-point arithmetic (Q1.15, Q1.31), vector operations, + * fast Fourier transforms (FFT), window functions, biquad filter solvers, and SIMD accelerators. + *
Telemetry, Logging & Probes@ref probe_api + * - @ref src/include/sof/probe/probe.h "sof/probe/probe.h"
+ * - @ref src/include/sof/trace/trace.h "sof/trace/trace.h"
+ * - @ref src/include/sof/debug/telemetry/telemetry.h "sof/debug/telemetry/telemetry.h"
+ * - @ref src/include/sof/debug/telemetry/performance_monitor.h "performance_monitor.h" + * 		+ * Real-time DSP firmware telemetry: non-blocking trace DMA logging, probe injection and extraction + * tap buffers, CPU load monitoring, MIPS benchmarking, and post-mortem crash dump mailboxes. + *
Platform & Hardware Drivers@ref platform_drivers_api + * - @ref zephyr/include/sof/lib/dai.h "sof/lib/dai.h"
+ * - @ref zephyr/include/sof/lib/dma.h "sof/lib/dma.h"
+ * - @ref zephyr/include/sof/lib/pm_runtime.h "pm_runtime.h"
+ * - @ref src/include/sof/platform.h "sof/platform.h" + * 		+ * Low-level peripheral drivers: Digital Audio Interfaces (I2S/SSP, SoundWire, DMIC/PDM, HDA), + * Direct Memory Access (DMA) controllers, interrupt controllers, and Power Management (D0ix/D3) runtime. + *
+ * + * --- + * + * @section quick_links Quick Navigation & Reference Links + * + * - Complete Sound Open Firmware C API Topics Index + * - Data Structures & API Structs + * - Header Files & Source Code Index + * - SOF Project High-Level Documentation Portal + */ From 17cd1e14c1616c6bfe95ec27f8bfc1ae6633e05f Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sun, 11 Oct 2026 21:32:49 +0100 Subject: [PATCH 4/4] doc: core: document RTOS, pipeline, drivers, math, and IPC4 interfaces 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 --- src/include/ipc4/alh.h | 10 ++++ src/include/ipc4/base_fw.h | 7 ++- src/include/ipc4/base_fw_vendor.h | 2 +- src/include/ipc4/error_status.h | 3 +- src/include/ipc4/fw_reg.h | 6 +-- src/include/ipc4/gateway.h | 5 +- src/include/ipc4/handler.h | 16 +++++++ src/include/ipc4/header.h | 51 +++++++-------------- src/include/ipc4/logging.h | 18 ++++++++ src/include/ipc4/module.h | 3 +- src/include/ipc4/notification.h | 3 +- src/include/ipc4/pipeline.h | 3 +- src/include/module/audio/format.h | 22 +++++++++ src/include/module/audio/sink_api.h | 6 +++ src/include/module/audio/source_api.h | 6 +++ src/include/module/module/base.h | 6 +++ src/include/module/module/interface.h | 6 +++ src/include/module/module/llext.h | 6 +++ src/include/module/module/system_service.h | 6 +++ src/include/sof/audio/audio_buffer.h | 6 +++ src/include/sof/audio/buffer.h | 6 +++ src/include/sof/audio/channel_map.h | 19 +++++++- src/include/sof/audio/format_generic.h | 28 ++++++++++- src/include/sof/audio/pcm_converter.h | 44 +++++++++++++++++- src/include/sof/audio/pipeline.h | 6 +++ src/include/sof/audio/smart_amp/smart_amp.h | 13 ++++++ src/include/sof/debug/telemetry/telemetry.h | 10 ++++ src/include/sof/drivers/ssp.h | 19 ++++++++ src/include/sof/ipc/topology.h | 8 +++- src/include/sof/lib/agent.h | 25 ++++++++++ src/include/sof/lib/dai-zephyr.h | 22 ++++++++- src/include/sof/math/auditory.h | 11 ++++- src/include/sof/math/dct.h | 18 +++++++- src/include/sof/math/decibels.h | 21 ++++++++- src/include/sof/math/fft.h | 34 +++++++++++++- src/include/sof/math/iir_df1.h | 26 +++++++++++ src/include/sof/math/iir_df1_generic.h | 30 ++++++++++++ src/include/sof/math/iir_df2t.h | 6 +++ src/include/sof/math/iir_df2t_generic.h | 30 ++++++++++++ src/include/sof/math/lut_trig.h | 13 +++++- src/include/sof/math/matrix.h | 6 ++- src/include/sof/math/numbers.h | 6 +++ src/include/sof/math/trig.h | 6 +++ src/include/sof/math/window.h | 6 ++- src/include/sof/schedule/dp_schedule.h | 18 ++++++++ src/include/sof/schedule/edf_schedule.h | 20 ++++++++ src/include/sof/schedule/ll_schedule.h | 44 ++++++++++++++++-- src/include/sof/schedule/schedule.h | 17 ++++++- zephyr/include/rtos/alloc.h | 37 +++++++++++++-- zephyr/include/rtos/cache.h | 39 ++++++++++++++++ zephyr/include/rtos/clk.h | 6 +++ zephyr/include/rtos/kernel.h | 11 +++++ zephyr/include/rtos/mutex.h | 6 +++ zephyr/include/rtos/sof.h | 10 ++++ zephyr/include/rtos/spinlock.h | 14 +++++- zephyr/include/rtos/timer.h | 6 +++ zephyr/include/rtos/userspace_helper.h | 6 +++ zephyr/include/sof/trace/trace.h | 5 ++ 58 files changed, 770 insertions(+), 73 deletions(-) diff --git a/src/include/ipc4/alh.h b/src/include/ipc4/alh.h index 7691b9fe0a11..d7077a7eb017 100644 --- a/src/include/ipc4/alh.h +++ b/src/include/ipc4/alh.h @@ -54,6 +54,11 @@ /* Multi-gateways addressing starts from IPC4_ALH_MULTI_GTW_BASE */ #define IPC4_ALH_MULTI_GTW_BASE 0x50 +/** + * @brief Check if an IPC4 connector node ID corresponds to an aggregated multi-gateway. + * @param node_id Gateway connector node ID. + * @return True if the node represents an aggregated multi-gateway, false otherwise. + */ static inline bool is_multi_gateway(const union ipc4_connector_node_id node_id) { return node_id.f.v_index >= IPC4_ALH_MULTI_GTW_BASE; @@ -76,6 +81,11 @@ struct sof_alh_configuration_blob { struct ipc4_alh_multi_gtw_cfg alh_cfg; } __attribute__((packed, aligned(4))); +/** + * @brief Calculate the serialized size of an ALH configuration blob. + * @param alh_blob Pointer to the ALH configuration structure. + * @return Size in bytes of the configuration blob. + */ static inline size_t get_alh_config_size(const struct sof_alh_configuration_blob *alh_blob) { diff --git a/src/include/ipc4/base_fw.h b/src/include/ipc4/base_fw.h index 2ae358010c2d..354a7001cf33 100644 --- a/src/include/ipc4/base_fw.h +++ b/src/include/ipc4/base_fw.h @@ -10,7 +10,8 @@ /** * \file include/ipc4/base_fw.h - * \brief IPC4 global definitions. + * \brief IPC4 Base Firmware parameters, memory configuration, and status definitions. + * \ingroup ipc4_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -756,6 +757,10 @@ struct schedulers_info { struct scheduler_props scheduler_info[]; } __packed __aligned(4); +/** + * @brief Get the current DSP system time information for host-DSP clock synchronization. + * @return Pointer to struct ipc4_system_time_info containing current 64-bit timestamp. + */ struct ipc4_system_time_info *basefw_get_system_time_info(void); /* Specifies I2S IPC4 version for PTL platform */ diff --git a/src/include/ipc4/base_fw_vendor.h b/src/include/ipc4/base_fw_vendor.h index 60173439b502..e54b9214e196 100644 --- a/src/include/ipc4/base_fw_vendor.h +++ b/src/include/ipc4/base_fw_vendor.h @@ -6,7 +6,7 @@ */ /** - * \file include/ipc4/base_fw_platform.h + * \file ipc4/base_fw_vendor.h * \brief Platform specific IPC4 base firmware functionality. */ diff --git a/src/include/ipc4/error_status.h b/src/include/ipc4/error_status.h index c3ad27bf2a61..4d65b5596710 100644 --- a/src/include/ipc4/error_status.h +++ b/src/include/ipc4/error_status.h @@ -13,7 +13,8 @@ /** * \file include/ipc4/error_status.h - * \brief IPC4 global definitions. + * \brief IPC4 status codes, error codes, and IXC return values. + * \ingroup ipc4_api * NOTE: This ABI uses bit fields and is non portable. */ diff --git a/src/include/ipc4/fw_reg.h b/src/include/ipc4/fw_reg.h index a0f450954050..4f55b2f3cf2f 100644 --- a/src/include/ipc4/fw_reg.h +++ b/src/include/ipc4/fw_reg.h @@ -17,10 +17,8 @@ /** * \file include/ipc4/fw_reg.h - * \brief IPC4 fw registers in mailbox for host. Fw exposes dsp / fw - * state information to the host via shared memory window 0, .e.g. fw error, - * pipeline state, dma llp counter and others. These information are included - * in ipc4_fw_registers structure defined in this file. + * \brief IPC4 firmware registers in mailbox window 0 for host telemetry and status. + * \ingroup ipc4_api * NOTE: This ABI uses bit fields and is non portable. */ diff --git a/src/include/ipc4/gateway.h b/src/include/ipc4/gateway.h index 9398bb44be0e..fb0ffca72f5b 100644 --- a/src/include/ipc4/gateway.h +++ b/src/include/ipc4/gateway.h @@ -16,8 +16,9 @@ */ /** - * \file include/ipc4/header.h - * \brief IPC4 global definitions. + * \file include/ipc4/gateway.h + * \brief IPC4 audio gateway attributes, ALH, HDA, and SoundWire gateway definitions. + * \ingroup ipc4_api * NOTE: This ABI uses bit fields and is non portable. */ diff --git a/src/include/ipc4/handler.h b/src/include/ipc4/handler.h index 8f624a3c5c70..104f12fcaacc 100644 --- a/src/include/ipc4/handler.h +++ b/src/include/ipc4/handler.h @@ -102,10 +102,26 @@ __syscall int ipc_wait_for_compound_msg(void); #include #else +/** + * @brief Compound IPC message pre-start handler (internal implementation). + * @param msg_id IPC message identifier. + */ void z_impl_ipc_compound_pre_start(int msg_id); #define ipc_compound_pre_start z_impl_ipc_compound_pre_start + +/** + * @brief Compound IPC message post-start handler (internal implementation). + * @param msg_id IPC message identifier. + * @param ret Return status of the IPC processing. + * @param delayed True if response is deferred/asynchronous. + */ void z_impl_ipc_compound_post_start(uint32_t msg_id, int ret, bool delayed); #define ipc_compound_post_start z_impl_ipc_compound_post_start + +/** + * @brief Wait for active compound IPC message completion (internal implementation). + * @return 0 on success, negative error code on timeout. + */ int z_impl_ipc_wait_for_compound_msg(void); #define ipc_wait_for_compound_msg z_impl_ipc_wait_for_compound_msg #endif diff --git a/src/include/ipc4/header.h b/src/include/ipc4/header.h index d72108e7060c..ade286f2b031 100644 --- a/src/include/ipc4/header.h +++ b/src/include/ipc4/header.h @@ -17,7 +17,8 @@ /** * \file include/ipc4/header.h - * \brief IPC4 global definitions. + * \brief IPC4 global message headers, envelope formats, and command types. + * \ingroup ipc4_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -179,48 +180,30 @@ struct ipc4_message_reply { #define SOF_IPC4_NOTIFY_MODULE_EVENTID_ALSA_MAGIC_VAL ((uint32_t)0xA15A << 16) #define SOF_IPC4_NOTIFY_MODULE_EVENTID_COMPR_MAGIC_VAL ((uint32_t)0xC0C0 << 16) -/** - * struct sof_ipc4_ctrl_value_chan: generic channel mapped value data - * @channel: Channel ID - * @value: control value - */ +/** Generic channel mapped value data. */ struct sof_ipc4_ctrl_value_chan { - uint32_t channel; - uint32_t value; + uint32_t channel; /**< Channel ID */ + uint32_t value; /**< control value */ } __attribute((packed, aligned(4))); -/** - * struct sof_ipc4_control_msg_payload - IPC payload for kcontrol parameters - * @id: unique id of the control - * @num_elems: Number of elements in the chanv array or number of bytes in data - * @reserved: reserved for future use, must be set to 0 - * @chanv: channel ID and value array - * @data: binary payload - */ +/** IPC payload for kcontrol parameters. */ struct sof_ipc4_control_msg_payload { - uint16_t id; - uint16_t num_elems; - uint32_t reserved[4]; + uint16_t id; /**< unique id of the control */ + uint16_t num_elems; /**< Number of elements in the chanv array or number of bytes in data */ + uint32_t reserved[4]; /**< reserved for future use, must be set to 0 */ union { - struct sof_ipc4_ctrl_value_chan chanv[0]; - uint8_t data[0]; + struct sof_ipc4_ctrl_value_chan chanv[0]; /**< channel ID and value array */ + uint8_t data[0]; /**< binary payload */ }; } __attribute((packed, aligned(4))); -/** - * struct sof_ipc4_notify_module_data - payload for module notification - * @instance_id: instance ID of the originator module of the notification - * @module_id: module ID of the originator of the notification - * @event_id: module specific event id - * @event_data_size: Size of the @event_data (if any) in bytes - * @event_data: Optional notification data, module and notification dependent - */ +/** Payload for module notification. */ struct sof_ipc4_notify_module_data { - uint16_t instance_id; - uint16_t module_id; - uint32_t event_id; - uint32_t event_data_size; - uint8_t event_data[]; + uint16_t instance_id; /**< instance ID of the originator module of the notification */ + uint16_t module_id; /**< module ID of the originator of the notification */ + uint32_t event_id; /**< module specific event id */ + uint32_t event_data_size; /**< Size of the event_data (if any) in bytes */ + uint8_t event_data[]; /**< Optional notification data, module and notification dependent */ } __attribute((packed, aligned(4))); #endif diff --git a/src/include/ipc4/logging.h b/src/include/ipc4/logging.h index 55f4a5edbffc..3fda5201267b 100644 --- a/src/include/ipc4/logging.h +++ b/src/include/ipc4/logging.h @@ -3,16 +3,34 @@ * Copyright(c) 2022 Intel Corporation. All rights reserved. */ +/** + * @file ipc4/logging.h + * @brief IPC4 host logging control and configuration interface. + * @ingroup ipc4_api + */ + #ifndef __SOF_IPC4_LOGGING_H__ #define __SOF_IPC4_LOGGING_H__ #define SOF_IPC4_LOGGING_MTRACE_PAGE_SIZE 0x1000 +/** + * @brief Configure and enable firmware logging requested by the host via IPC4. + * @param first_block True if this buffer is the first chunk of logging configuration. + * @param last_block True if this buffer is the final chunk of logging configuration. + * @param data_offset_or_size Byte offset or payload size of the configuration block. + * @param data Pointer to configuration payload buffer. + * @return 0 on success, negative error code on failure. + */ int ipc4_logging_enable_logs(bool first_block, bool last_block, uint32_t data_offset_or_size, const char *data); +/** + * @brief Shutdown active IPC4 firmware logging and flush remaining trace buffers. + * @return 0 on success, negative error code on failure. + */ int ipc4_logging_shutdown(void); #endif diff --git a/src/include/ipc4/module.h b/src/include/ipc4/module.h index f026f837801a..db1a074151a5 100644 --- a/src/include/ipc4/module.h +++ b/src/include/ipc4/module.h @@ -14,7 +14,8 @@ /** * \file include/ipc4/module.h - * \brief IPC4 module definitions + * \brief IPC4 module instantiation, binding, pin configuration, and parameter definitions. + * \ingroup ipc4_api * NOTE: This ABI uses bit fields and is non portable. */ diff --git a/src/include/ipc4/notification.h b/src/include/ipc4/notification.h index 666afea15347..870cef798407 100644 --- a/src/include/ipc4/notification.h +++ b/src/include/ipc4/notification.h @@ -17,7 +17,8 @@ /** * \file include/ipc4/notification.h - * \brief IPC4 notification definitions + * \brief IPC4 asynchronous notifications, GLITCH reports, and FW ready events. + * \ingroup ipc4_api */ #ifndef __IPC4_NOTIFICATION_H__ diff --git a/src/include/ipc4/pipeline.h b/src/include/ipc4/pipeline.h index 1e85072fd15c..da756364dc6a 100644 --- a/src/include/ipc4/pipeline.h +++ b/src/include/ipc4/pipeline.h @@ -17,7 +17,8 @@ /** * \file include/ipc4/pipeline.h - * \brief IPC4 pipeline definitions + * \brief IPC4 pipeline creation, states, priorities, and management commands. + * \ingroup ipc4_api * NOTE: This ABI uses bit fields and is non portable. */ diff --git a/src/include/module/audio/format.h b/src/include/module/audio/format.h index 7fccef12f49e..b05bd7273f03 100644 --- a/src/include/module/audio/format.h +++ b/src/include/module/audio/format.h @@ -8,12 +8,23 @@ * Adrian Warecki */ +/** + * @file module/audio/format.h + * @brief Audio sample format conversion and size calculation helpers for modules. + * @ingroup module_api + */ + #ifndef __MODULE_AUDIO_FORMAT_H__ #define __MODULE_AUDIO_FORMAT_H__ #include #include "../ipc/stream.h" +/** + * @brief Get the byte size of a single audio sample for a given frame format. + * @param fmt Audio frame format enum (enum sof_ipc_frame). + * @return Number of bytes per sample (1, 2, 3, or 4). + */ static inline uint32_t get_sample_bytes(enum sof_ipc_frame fmt) { switch (fmt) { @@ -30,6 +41,11 @@ static inline uint32_t get_sample_bytes(enum sof_ipc_frame fmt) } } +/** + * @brief Get the bit depth of a single audio sample for a given frame format. + * @param fmt Audio frame format enum (enum sof_ipc_frame). + * @return Number of active audio bits per sample (8, 16, 24, or 32). + */ static inline uint32_t get_sample_bitdepth(enum sof_ipc_frame fmt) { switch (fmt) { @@ -47,6 +63,12 @@ static inline uint32_t get_sample_bitdepth(enum sof_ipc_frame fmt) } } +/** + * @brief Get the byte size of an entire multi-channel audio frame. + * @param fmt Audio frame format enum (enum sof_ipc_frame). + * @param channels Number of audio channels. + * @return Total frame size in bytes (sample_bytes * channels). + */ static inline uint32_t get_frame_bytes(enum sof_ipc_frame fmt, uint32_t channels) { return get_sample_bytes(fmt) * channels; diff --git a/src/include/module/audio/sink_api.h b/src/include/module/audio/sink_api.h index 3101c960c803..a58d7936baa8 100644 --- a/src/include/module/audio/sink_api.h +++ b/src/include/module/audio/sink_api.h @@ -4,6 +4,12 @@ * */ +/** + * @file module/audio/sink_api.h + * @brief Sink audio endpoint API for module output buffers. + * @ingroup module_api + */ + #ifndef __MODULE_AUDIO_SINK_API_H__ #define __MODULE_AUDIO_SINK_API_H__ diff --git a/src/include/module/audio/source_api.h b/src/include/module/audio/source_api.h index 33497ba136fc..624032b9d4d7 100644 --- a/src/include/module/audio/source_api.h +++ b/src/include/module/audio/source_api.h @@ -4,6 +4,12 @@ * */ +/** + * @file module/audio/source_api.h + * @brief Source audio endpoint API for module input buffers. + * @ingroup module_api + */ + #ifndef __MODULE_AUDIO_SOURCE_API_H__ #define __MODULE_AUDIO_SOURCE_API_H__ diff --git a/src/include/module/module/base.h b/src/include/module/module/base.h index 5d41d2d8a6b4..a1ef09337249 100644 --- a/src/include/module/module/base.h +++ b/src/include/module/module/base.h @@ -6,6 +6,12 @@ * Adrian Warecki */ +/** + * @file module/base.h + * @brief Base definitions and structures for loadable audio modules. + * @ingroup module_api + */ + #ifndef __MODULE_MODULE_BASE__ #define __MODULE_MODULE_BASE__ diff --git a/src/include/module/module/interface.h b/src/include/module/module/interface.h index 8e31117f9469..53d58f150c87 100644 --- a/src/include/module/module/interface.h +++ b/src/include/module/module/interface.h @@ -6,6 +6,12 @@ * Adrian Warecki */ +/** + * @file module/interface.h + * @brief Dynamic module interface, lifecycle callbacks, and buffer contracts. + * @ingroup module_api + */ + #ifndef __MODULE_MODULE_INTERFACE__ #define __MODULE_MODULE_INTERFACE__ diff --git a/src/include/module/module/llext.h b/src/include/module/module/llext.h index 2ef0d47d77cc..4f1208f33d5e 100644 --- a/src/include/module/module/llext.h +++ b/src/include/module/module/llext.h @@ -3,6 +3,12 @@ * Copyright(c) 2024 Intel Corporation. All rights reserved. */ +/** + * @file module/llext.h + * @brief LLEXT manifest macros and declarations for loadable ELF extensions. + * @ingroup module_api + */ + #ifndef MODULE_LLEXT_H #define MODULE_LLEXT_H diff --git a/src/include/module/module/system_service.h b/src/include/module/module/system_service.h index 0fb60834fc6d..56f9712a67d5 100644 --- a/src/include/module/module/system_service.h +++ b/src/include/module/module/system_service.h @@ -5,6 +5,12 @@ * Author: Adrian Warecki */ +/** + * @file module/system_service.h + * @brief System services provided by the base firmware to loadable modules. + * @ingroup module_api + */ + #ifndef MODULE_MODULE_SYSTEM_SERVICE_H #define MODULE_MODULE_SYSTEM_SERVICE_H diff --git a/src/include/sof/audio/audio_buffer.h b/src/include/sof/audio/audio_buffer.h index 95317e5dc964..14ee20c23bf1 100644 --- a/src/include/sof/audio/audio_buffer.h +++ b/src/include/sof/audio/audio_buffer.h @@ -3,6 +3,12 @@ * Copyright(c) 2023 Intel Corporation. All rights reserved. * */ +/** + * @file sof/audio/audio_buffer.h + * @brief Audio buffer operations, descriptors, and unified audio buffer interfaces. + * @ingroup audio_pipeline_api + */ + #ifndef __SOF_AUDIO_BUFFER__ #define __SOF_AUDIO_BUFFER__ diff --git a/src/include/sof/audio/buffer.h b/src/include/sof/audio/buffer.h index 07dcf651d15b..6744bbf1b5ef 100644 --- a/src/include/sof/audio/buffer.h +++ b/src/include/sof/audio/buffer.h @@ -5,6 +5,12 @@ * Author: Liam Girdwood */ +/** + * @file sof/audio/buffer.h + * @brief Component interconnect buffer allocation and stream handling. + * @ingroup audio_pipeline_api + */ + #ifndef __SOF_AUDIO_BUFFER_H__ #define __SOF_AUDIO_BUFFER_H__ diff --git a/src/include/sof/audio/channel_map.h b/src/include/sof/audio/channel_map.h index 99675f09739d..a0ec75baca48 100644 --- a/src/include/sof/audio/channel_map.h +++ b/src/include/sof/audio/channel_map.h @@ -5,6 +5,12 @@ * Author: Slawomir Blauciak */ +/** + * @file sof/audio/channel_map.h + * @brief Audio stream channel map lookup and sizing helpers. + * @ingroup audio_pipeline_api + */ + #ifndef __SOF_AUDIO_CHANNEL_MAP_H__ #define __SOF_AUDIO_CHANNEL_MAP_H__ @@ -12,14 +18,23 @@ #include #include -/* Returns the size of a channel map in bytes */ +/** + * @brief Returns the size of an IPC channel map structure in bytes. + * @param chmap Pointer to the channel map structure. + * @return Total size in bytes including dynamic channel coefficients. + */ static inline uint32_t chmap_get_size(struct sof_ipc_channel_map *chmap) { return sizeof(*chmap) + (popcount(chmap->ch_mask) * sizeof(*chmap->ch_coeffs)); } -/* Returns a channel map valid for a given index in a given stream map */ +/** + * @brief Returns a channel map for a given channel index in a stream map. + * @param smap Pointer to the stream map structure. + * @param index Channel index. + * @return Pointer to matching channel map structure, or NULL if not found. + */ struct sof_ipc_channel_map *chmap_get(struct sof_ipc_stream_map *smap, int index); diff --git a/src/include/sof/audio/format_generic.h b/src/include/sof/audio/format_generic.h index b63284cb872e..f5f2179ecee0 100644 --- a/src/include/sof/audio/format_generic.h +++ b/src/include/sof/audio/format_generic.h @@ -3,13 +3,22 @@ * Copyright(c) 2021 Intel Corporation. All rights reserved. */ +/** + * @file sof/audio/format_generic.h + * @brief Generic audio sample saturation helpers. + * @ingroup audio_pipeline_api + */ + #ifndef __SOF_AUDIO_FORMAT_GENERIC_H__ #define __SOF_AUDIO_FORMAT_GENERIC_H__ #include -/* Saturation inline functions */ - +/** + * @brief Saturate a 64-bit integer to signed 32-bit integer range. + * @param x Input 64-bit integer. + * @return Saturated 32-bit integer clamped between INT32_MIN and INT32_MAX. + */ static inline int32_t sat_int32(int64_t x) { if (x > INT32_MAX) @@ -20,6 +29,11 @@ static inline int32_t sat_int32(int64_t x) return (int32_t)x; } +/** + * @brief Saturate a 32-bit integer to signed 24-bit integer range. + * @param x Input 32-bit integer. + * @return Saturated 24-bit integer clamped between INT24_MINVALUE and INT24_MAXVALUE. + */ static inline int32_t sat_int24(int32_t x) { if (x > INT24_MAXVALUE) @@ -30,6 +44,11 @@ static inline int32_t sat_int24(int32_t x) return x; } +/** + * @brief Saturate a 32-bit integer to signed 16-bit integer range. + * @param x Input 32-bit integer. + * @return Saturated 16-bit integer clamped between INT16_MIN and INT16_MAX. + */ static inline int16_t sat_int16(int32_t x) { if (x > INT16_MAX) @@ -40,6 +59,11 @@ static inline int16_t sat_int16(int32_t x) return (int16_t)x; } +/** + * @brief Saturate a 32-bit integer to signed 8-bit integer range. + * @param x Input 32-bit integer. + * @return Saturated 8-bit integer clamped between INT8_MIN and INT8_MAX. + */ static inline int8_t sat_int8(int32_t x) { if (x > INT8_MAX) diff --git a/src/include/sof/audio/pcm_converter.h b/src/include/sof/audio/pcm_converter.h index 1b165c4b926d..fd2565c7a6cc 100644 --- a/src/include/sof/audio/pcm_converter.h +++ b/src/include/sof/audio/pcm_converter.h @@ -198,16 +198,58 @@ int pcm_convert_as_linear(const struct cir_buf_source *source, size_t s_size_in, struct cir_buf_sink *sink, size_t s_size_out, size_t samples, pcm_converter_lin_func converter); -/* Copy stream without conversion, typed by sample size in bytes. chmap is ignored. */ +/** + * @brief Copy 1-byte PCM stream without conversion (8-bit samples). + * @param source Circular buffer source. + * @param src_channels Number of source channels. + * @param sink Circular buffer sink. + * @param sink_channels Number of sink channels. + * @param samples Number of samples to copy. + * @param chmap Channel mapping (unused). + * @return Number of samples copied or negative error code. + */ int just_copy_1b(const struct cir_buf_source *source, uint32_t src_channels, struct cir_buf_sink *sink, uint32_t sink_channels, size_t samples, uint32_t chmap); + +/** + * @brief Copy 2-byte PCM stream without conversion (16-bit samples). + * @param source Circular buffer source. + * @param src_channels Number of source channels. + * @param sink Circular buffer sink. + * @param sink_channels Number of sink channels. + * @param samples Number of samples to copy. + * @param chmap Channel mapping (unused). + * @return Number of samples copied or negative error code. + */ int just_copy_2b(const struct cir_buf_source *source, uint32_t src_channels, struct cir_buf_sink *sink, uint32_t sink_channels, size_t samples, uint32_t chmap); + +/** + * @brief Copy 3-byte PCM stream without conversion (24-bit samples in 3 bytes). + * @param source Circular buffer source. + * @param src_channels Number of source channels. + * @param sink Circular buffer sink. + * @param sink_channels Number of sink channels. + * @param samples Number of samples to copy. + * @param chmap Channel mapping (unused). + * @return Number of samples copied or negative error code. + */ int just_copy_3b(const struct cir_buf_source *source, uint32_t src_channels, struct cir_buf_sink *sink, uint32_t sink_channels, size_t samples, uint32_t chmap); + +/** + * @brief Copy 4-byte PCM stream without conversion (32-bit samples or 24-bit in 4 bytes). + * @param source Circular buffer source. + * @param src_channels Number of source channels. + * @param sink Circular buffer sink. + * @param sink_channels Number of sink channels. + * @param samples Number of samples to copy. + * @param chmap Channel mapping (unused). + * @return Number of samples copied or negative error code. + */ int just_copy_4b(const struct cir_buf_source *source, uint32_t src_channels, struct cir_buf_sink *sink, uint32_t sink_channels, size_t samples, uint32_t chmap); diff --git a/src/include/sof/audio/pipeline.h b/src/include/sof/audio/pipeline.h index 9e21da9bfad0..5fa2f860021f 100644 --- a/src/include/sof/audio/pipeline.h +++ b/src/include/sof/audio/pipeline.h @@ -5,6 +5,12 @@ * Author: Liam Girdwood */ +/** + * @file sof/audio/pipeline.h + * @brief Audio pipeline management, graph scheduling, and execution control. + * @ingroup audio_pipeline_api + */ + #ifndef __SOF_AUDIO_PIPELINE_H__ #define __SOF_AUDIO_PIPELINE_H__ diff --git a/src/include/sof/audio/smart_amp/smart_amp.h b/src/include/sof/audio/smart_amp/smart_amp.h index e6007bf28729..c7441a6f6805 100644 --- a/src/include/sof/audio/smart_amp/smart_amp.h +++ b/src/include/sof/audio/smart_amp/smart_amp.h @@ -155,7 +155,20 @@ struct smart_amp_func_map { extern const struct smart_amp_func_map src_sink_func_map[]; +/** + * @brief Retrieve source processing callback matching component and module PCM formats. + * @param comp_fmt Component stream frame format. + * @param mod_fmt Processing module internal frame format. + * @return Source processing function pointer, or NULL if no match found. + */ smart_amp_src_func smart_amp_get_src_func(uint16_t comp_fmt, uint16_t mod_fmt); + +/** + * @brief Retrieve sink processing callback matching component and module PCM formats. + * @param comp_fmt Component stream frame format. + * @param mod_fmt Processing module internal frame format. + * @return Sink processing function pointer, or NULL if no match found. + */ smart_amp_sink_func smart_amp_get_sink_func(uint16_t comp_fmt, uint16_t mod_fmt); /****************************************************************************** diff --git a/src/include/sof/debug/telemetry/telemetry.h b/src/include/sof/debug/telemetry/telemetry.h index 6c2d5fdf8cb7..ce1aef588f2d 100644 --- a/src/include/sof/debug/telemetry/telemetry.h +++ b/src/include/sof/debug/telemetry/telemetry.h @@ -89,8 +89,18 @@ struct telemetry_perf_queue { size_t sum; }; +/** + * @brief Update periodic telemetry metrics with elapsed core clock cycles. + * @param begin_ccount Cycle count at start of measurement window. + * @param current_ccount Cycle count at current measurement point. + */ void telemetry_update(uint32_t begin_ccount, uint32_t current_ccount); + #ifdef CONFIG_INTEL_ADSP_DEBUG_SLOT_MANAGER +/** + * @brief Get pointer to system tick telemetry information structure. + * @return Pointer to struct system_tick_info. + */ struct system_tick_info *telemetry_get_systick_info_ptr(void); #endif diff --git a/src/include/sof/drivers/ssp.h b/src/include/sof/drivers/ssp.h index f057e7147747..548f06d59995 100644 --- a/src/include/sof/drivers/ssp.h +++ b/src/include/sof/drivers/ssp.h @@ -225,16 +225,35 @@ struct ssp_pdata { struct sof_ipc_dai_ssp_params params; }; +/** + * @brief Write a 32-bit register on the specified Synchronous Serial Port (SSP) DAI. + * @param dai Pointer to DAI device descriptor. + * @param reg Register offset. + * @param value 32-bit value to write. + */ static inline void ssp_write(struct dai *dai, uint32_t reg, uint32_t value) { dai_write(dai, reg, value); } +/** + * @brief Read a 32-bit register from the specified Synchronous Serial Port (SSP) DAI. + * @param dai Pointer to DAI device descriptor. + * @param reg Register offset. + * @return 32-bit register value. + */ static inline uint32_t ssp_read(struct dai *dai, uint32_t reg) { return dai_read(dai, reg); } +/** + * @brief Read-modify-write bit fields of an SSP DAI register. + * @param dai Pointer to DAI device descriptor. + * @param reg Register offset. + * @param mask Bitmask of fields to modify. + * @param value New bit values to set within mask. + */ static inline void ssp_update_bits(struct dai *dai, uint32_t reg, uint32_t mask, uint32_t value) { diff --git a/src/include/sof/ipc/topology.h b/src/include/sof/ipc/topology.h index 422563185a90..e04ac5364d4b 100644 --- a/src/include/sof/ipc/topology.h +++ b/src/include/sof/ipc/topology.h @@ -224,8 +224,12 @@ int32_t ipc_comp_pipe_id(const struct ipc_comp_dev *icd); int ipc_comp_dai_config(struct ipc *ipc, struct ipc_config_dai *common_config, void *spec_config); -/* - * Warning: duplicate declaration in component.h +/** + * @brief Verify stream parameters against component capabilities. + * @param dev Pointer to component device descriptor. + * @param flag Verification flags (e.g. SOF_IPC_STREAM_PARAMS_...). + * @param params Stream parameters to validate. + * @return 0 on success, negative error code on invalid parameters. */ int comp_verify_params(struct comp_dev *dev, uint32_t flag, struct sof_ipc_stream_params *params); diff --git a/src/include/sof/lib/agent.h b/src/include/sof/lib/agent.h index 6e70a4ce997d..6aaa740761f2 100644 --- a/src/include/sof/lib/agent.h +++ b/src/include/sof/lib/agent.h @@ -52,13 +52,38 @@ static inline void sa_set_panic_on_delay(bool enabled) } +/** + * @brief Initialize the System Agent watchdog monitoring service. + * @param sof Pointer to global SOF runtime context. + * @param timeout Watchdog panic threshold in CPU cycles. + */ void sa_init(struct sof *sof, uint64_t timeout); + +/** + * @brief Teardown the System Agent watchdog monitoring service. + * @param sof Pointer to global SOF runtime context. + */ void sa_exit(struct sof *sof); #else +/** + * @brief Initialize the System Agent (no-op stub when CONFIG_HAVE_AGENT is disabled). + * @param sof Pointer to global SOF runtime context. + * @param timeout Watchdog panic threshold. + */ static inline void sa_init(struct sof *sof, uint64_t timeout) { } + +/** + * @brief Teardown the System Agent (no-op stub when CONFIG_HAVE_AGENT is disabled). + * @param sof Pointer to global SOF runtime context. + */ static inline void sa_exit(struct sof *sof) { } + +/** + * @brief Configure delay panic behavior (no-op stub when CONFIG_HAVE_AGENT is disabled). + * @param enabled True to enable panic on delay. + */ static inline void sa_set_panic_on_delay(bool enabled) { } #endif diff --git a/src/include/sof/lib/dai-zephyr.h b/src/include/sof/lib/dai-zephyr.h index a0c42bff351e..0c3febaed73f 100644 --- a/src/include/sof/lib/dai-zephyr.h +++ b/src/include/sof/lib/dai-zephyr.h @@ -38,7 +38,7 @@ #include -/** \addtogroup sof_dai_drivers DAI Drivers +/** \addtogroup platform_drivers_api * DAI Drivers API specification. * @{ */ @@ -173,16 +173,34 @@ struct dai_data { struct mod_alloc_ctx alloc_ctx; }; -/* these 3 are here to satisfy clk.c and ssp.h interconnection, will be removed leter */ +/** + * @brief Write a 32-bit register on the specified DAI controller. + * @param dai Pointer to DAI device descriptor. + * @param reg Register offset. + * @param value 32-bit value to write. + */ static inline void dai_write(struct dai *dai, uint32_t reg, uint32_t value) { } +/** + * @brief Read a 32-bit register from the specified DAI controller. + * @param dai Pointer to DAI device descriptor. + * @param reg Register offset. + * @return 32-bit register value. + */ static inline uint32_t dai_read(struct dai *dai, uint32_t reg) { return 0; } +/** + * @brief Read-modify-write bit fields of a DAI register. + * @param dai Pointer to DAI device descriptor. + * @param reg Register offset. + * @param mask Bitmask of fields to modify. + * @param value New bit values to set within mask. + */ static inline void dai_update_bits(struct dai *dai, uint32_t reg, uint32_t mask, uint32_t value) { diff --git a/src/include/sof/math/auditory.h b/src/include/sof/math/auditory.h index a68f0468d591..4a612372ea3b 100644 --- a/src/include/sof/math/auditory.h +++ b/src/include/sof/math/auditory.h @@ -69,16 +69,25 @@ int16_t psy_hz_to_mel(int16_t hz); */ int16_t psy_mel_to_hz(int16_t mel); +struct processing_module; + /** * \brief Get a Mel frequency filterbank * See Wikipedia https://en.wikipedia.org/wiki/Mel_scale * + * \param[in] mod Pointer to calling processing module. * \param[in, out] mel_fb Struct with filterbank input parameters, in return the band * filter coefficients. * \return Zero when success, otherwise error code. */ -struct processing_module; int mod_psy_get_mel_filterbank(struct processing_module *mod, struct psy_mel_filterbank *mel_fb); + +/** + * \brief Free memory allocated for a Mel frequency filterbank + * \param[in] mod Pointer to calling processing module. + * \param[in, out] mel_fb Struct with filterbank parameters to release. + * \return Zero when success, otherwise error code. + */ int mod_psy_free_mel_filterbank(struct processing_module *mod, struct psy_mel_filterbank *mel_fb); /** diff --git a/src/include/sof/math/dct.h b/src/include/sof/math/dct.h index 7c754f448c21..0e5cc3300c41 100644 --- a/src/include/sof/math/dct.h +++ b/src/include/sof/math/dct.h @@ -5,7 +5,11 @@ * Author: Seppo Ingalsuo */ -/* Matrix calculation related functions */ +/** + * @file sof/math/dct.h + * @brief Discrete Cosine Transform (DCT) matrix generation and planning. + * @ingroup dsp_math_api + */ #ifndef __SOF_MATH_DCT_H__ #define __SOF_MATH_DCT_H__ @@ -29,8 +33,20 @@ struct dct_plan_16 { bool ortho; }; +/** + * @brief Initialize a 16-bit Discrete Cosine Transform plan and compute transform matrix. + * @param mod Processing module requesting the plan (for memory allocation). + * @param dct Pointer to DCT plan configuration structure. + * @return 0 on success, negative error code on failure. + */ int mod_dct_initialize_16(struct processing_module *mod, struct dct_plan_16 *dct); +/** + * @brief Free memory allocated for a 16-bit DCT plan matrix. + * @param mod Processing module owning the plan. + * @param dct Pointer to DCT plan structure to free. + * @return 0 on success, negative error code on failure. + */ int mod_dct_free_16(struct processing_module *mod, struct dct_plan_16 *dct); #endif /* __SOF_MATH_DCT_H__ */ diff --git a/src/include/sof/math/decibels.h b/src/include/sof/math/decibels.h index a0336e9be9b9..71f01c08a906 100644 --- a/src/include/sof/math/decibels.h +++ b/src/include/sof/math/decibels.h @@ -6,6 +6,12 @@ * Author: Seppo Ingalsuo */ +/** + * @file sof/math/decibels.h + * @brief Fixed-point exponential and decibel-to-linear conversion functions. + * @ingroup dsp_math_api + */ + #ifndef __SOF_MATH_DECIBELS_H__ #define __SOF_MATH_DECIBELS_H__ @@ -16,7 +22,18 @@ #define DB2LIN_FIXED_INPUT_QY 24 #define DB2LIN_FIXED_OUTPUT_QY 20 -int32_t exp_fixed(int32_t x); /* Input is Q5.27, output is Q12.20 */ -int32_t db2lin_fixed(int32_t x); /* Input is Q8.24, output is Q12.20 */ +/** + * @brief Compute fixed-point exponential e^x. + * @param x Input argument in Q5.27 format. + * @return Result e^x in Q12.20 format. + */ +int32_t exp_fixed(int32_t x); + +/** + * @brief Convert decibels to linear amplitude scale 10^(x/20). + * @param x Input decibel value in Q8.24 format. + * @return Linear gain factor in Q12.20 format. + */ +int32_t db2lin_fixed(int32_t x); #endif /* __SOF_MATH_DECIBELS_H__ */ diff --git a/src/include/sof/math/fft.h b/src/include/sof/math/fft.h index df06baf47c81..d8e00b633301 100644 --- a/src/include/sof/math/fft.h +++ b/src/include/sof/math/fft.h @@ -6,6 +6,12 @@ * Keyon Jie */ +/** + * @file sof/math/fft.h + * @brief Fast Fourier Transform (FFT) and Inverse FFT (IFFT) interfaces. + * @ingroup dsp_math_api + */ + #ifndef __SOF_FFT_H__ #define __SOF_FFT_H__ @@ -53,11 +59,37 @@ struct fft_multi_plan { int num_ffts; }; -/* interfaces of the library */ +/** + * @brief Allocate and initialize an FFT execution plan. + * @param mod Processing module requesting the plan (for memory allocation). + * @param inb Pointer to input buffer for complex data. + * @param outb Pointer to output buffer for complex results. + * @param size FFT transform size in number of complex bins. + * @param bits Sample word length in bits (16 or 32). + * @return Pointer to allocated struct fft_plan, or NULL on failure. + */ struct fft_plan *mod_fft_plan_new(struct processing_module *mod, void *inb, void *outb, uint32_t size, int bits); + +/** + * @brief Execute a 16-bit complex FFT or IFFT according to an initialized plan. + * @param plan Pointer to the initialized 16-bit FFT plan. + * @param ifft True for Inverse Fast Fourier Transform, false for forward FFT. + */ void fft_execute_16(struct fft_plan *plan, bool ifft); + +/** + * @brief Execute a 32-bit complex FFT or IFFT according to an initialized plan. + * @param plan Pointer to the initialized 32-bit FFT plan. + * @param ifft True for Inverse Fast Fourier Transform, false for forward FFT. + */ void fft_execute_32(struct fft_plan *plan, bool ifft); + +/** + * @brief Free an allocated FFT execution plan and its internal buffers. + * @param mod Processing module that owns the plan. + * @param plan Pointer to the FFT plan to free. + */ void mod_fft_plan_free(struct processing_module *mod, struct fft_plan *plan); /** diff --git a/src/include/sof/math/iir_df1.h b/src/include/sof/math/iir_df1.h index 24653f690ea3..12a71535bcf8 100644 --- a/src/include/sof/math/iir_df1.h +++ b/src/include/sof/math/iir_df1.h @@ -5,6 +5,12 @@ * Author: Andrula Song */ +/** + * @file sof/math/iir_df1.h + * @brief Infinite Impulse Response Direct Form I (DF1) filter definitions. + * @ingroup dsp_math_api + */ + #ifndef __SOF_MATH_IIR_DF1_H__ #define __SOF_MATH_IIR_DF1_H__ @@ -26,13 +32,33 @@ struct iir_state_df1 { struct sof_eq_iir_header; +/** + * @brief Initialize IIR Direct Form 1 coefficients from configuration header. + * @param iir Pointer to DF1 filter state structure. + * @param config Pointer to IIR equalizer configuration header. + * @return 0 on success, negative error code on failure. + */ int iir_init_coef_df1(struct iir_state_df1 *iir, struct sof_eq_iir_header *config); +/** + * @brief Calculate required delay line buffer size in bytes for a DF1 configuration. + * @param config Pointer to IIR equalizer configuration header. + * @return Required delay buffer size in bytes. + */ int iir_delay_size_df1(struct sof_eq_iir_header *config); +/** + * @brief Assign and initialize delay line state memory for DF1 filter. + * @param iir Pointer to DF1 filter state structure. + * @param state Double pointer to delay state buffer (updated with new buffer offset). + */ void iir_init_delay_df1(struct iir_state_df1 *iir, int32_t **state); +/** + * @brief Clear delay history of a Direct Form 1 IIR filter. + * @param iir Pointer to DF1 filter state structure. + */ void iir_reset_df1(struct iir_state_df1 *iir); /** diff --git a/src/include/sof/math/iir_df1_generic.h b/src/include/sof/math/iir_df1_generic.h index aaf38286537a..7786697dad51 100644 --- a/src/include/sof/math/iir_df1_generic.h +++ b/src/include/sof/math/iir_df1_generic.h @@ -5,26 +5,56 @@ * Author: Andrula Song */ +/** + * @file sof/math/iir_df1_generic.h + * @brief Generic C implementation of Direct Form I IIR filtering for various bit depths. + * @ingroup dsp_math_api + */ + #ifndef __IIR_DF1_GENERIC_H__ #define __IIR_DF1_GENERIC_H__ #include +/** + * @brief Filter a 16-bit PCM sample using Direct Form 1 IIR filter. + * @param iir Pointer to DF1 filter state. + * @param x Input 16-bit sample (Q1.15). + * @return Filtered 16-bit sample (Q1.15). + */ static inline int16_t iir_df1_s16(struct iir_state_df1 *iir, int16_t x) { return sat_int16(Q_SHIFT_RND(iir_df1(iir, ((int32_t)x) << 16), 31, 15)); } +/** + * @brief Filter a 24-bit PCM sample using Direct Form 1 IIR filter. + * @param iir Pointer to DF1 filter state. + * @param x Input 24-bit sample (Q1.23 in 32-bit container). + * @return Filtered 24-bit sample (Q1.23). + */ static inline int32_t iir_df1_s24(struct iir_state_df1 *iir, int32_t x) { return sat_int24(Q_SHIFT_RND(iir_df1(iir, x << 8), 31, 23)); } +/** + * @brief Filter a 32-bit PCM input sample producing a 16-bit output sample. + * @param iir Pointer to DF1 filter state. + * @param x Input 32-bit sample (Q1.31). + * @return Filtered 16-bit sample (Q1.15). + */ static inline int16_t iir_df1_s32_s16(struct iir_state_df1 *iir, int32_t x) { return sat_int16(Q_SHIFT_RND(iir_df1(iir, x), 31, 15)); } +/** + * @brief Filter a 32-bit PCM input sample producing a 24-bit output sample. + * @param iir Pointer to DF1 filter state. + * @param x Input 32-bit sample (Q1.31). + * @return Filtered 24-bit sample (Q1.23). + */ static inline int32_t iir_df1_s32_s24(struct iir_state_df1 *iir, int32_t x) { return sat_int24(Q_SHIFT_RND(iir_df1(iir, x), 31, 23)); diff --git a/src/include/sof/math/iir_df2t.h b/src/include/sof/math/iir_df2t.h index bf342520cb03..a6b6c3d1802f 100644 --- a/src/include/sof/math/iir_df2t.h +++ b/src/include/sof/math/iir_df2t.h @@ -7,6 +7,12 @@ * Keyon Jie */ +/** + * @file sof/math/iir_df2t.h + * @brief Infinite Impulse Response Direct Form II Transposed (DF2T) filter definitions. + * @ingroup dsp_math_api + */ + #ifndef __SOF_MATH_IIR_DF2T_H__ #define __SOF_MATH_IIR_DF2T_H__ diff --git a/src/include/sof/math/iir_df2t_generic.h b/src/include/sof/math/iir_df2t_generic.h index 579e937edeb9..386a9f81bcf9 100644 --- a/src/include/sof/math/iir_df2t_generic.h +++ b/src/include/sof/math/iir_df2t_generic.h @@ -5,26 +5,56 @@ * Author: Seppo Ingalsuo */ +/** + * @file sof/math/iir_df2t_generic.h + * @brief Generic C implementation of Direct Form II Transposed IIR filtering. + * @ingroup dsp_math_api + */ + #ifndef __IIR_DF2T_GENERIC_H__ #define __IIR_DF2T_GENERIC_H__ #include +/** + * @brief Filter a 16-bit PCM sample using Direct Form 2 Transposed IIR filter. + * @param iir Pointer to DF2T filter state. + * @param x Input 16-bit sample (Q1.15). + * @return Filtered 16-bit sample (Q1.15). + */ static inline int16_t iir_df2t_s16(struct iir_state_df2t *iir, int16_t x) { return sat_int16(Q_SHIFT_RND(iir_df2t(iir, ((int32_t)x) << 16), 31, 15)); } +/** + * @brief Filter a 24-bit PCM sample using Direct Form 2 Transposed IIR filter. + * @param iir Pointer to DF2T filter state. + * @param x Input 24-bit sample (Q1.23 in 32-bit container). + * @return Filtered 24-bit sample (Q1.23). + */ static inline int32_t iir_df2t_s24(struct iir_state_df2t *iir, int32_t x) { return sat_int24(Q_SHIFT_RND(iir_df2t(iir, x << 8), 31, 23)); } +/** + * @brief Filter a 32-bit PCM input sample producing a 16-bit output sample using DF2T. + * @param iir Pointer to DF2T filter state. + * @param x Input 32-bit sample (Q1.31). + * @return Filtered 16-bit sample (Q1.15). + */ static inline int16_t iir_df2t_s32_s16(struct iir_state_df2t *iir, int32_t x) { return sat_int16(Q_SHIFT_RND(iir_df2t(iir, x), 31, 15)); } +/** + * @brief Filter a 32-bit PCM input sample producing a 24-bit output sample using DF2T. + * @param iir Pointer to DF2T filter state. + * @param x Input 32-bit sample (Q1.31). + * @return Filtered 24-bit sample (Q1.23). + */ static inline int32_t iir_df2t_s32_s24(struct iir_state_df2t *iir, int32_t x) { return sat_int24(Q_SHIFT_RND(iir_df2t(iir, x), 31, 23)); diff --git a/src/include/sof/math/lut_trig.h b/src/include/sof/math/lut_trig.h index 7cf8f48ab602..0aeda1ff6a16 100644 --- a/src/include/sof/math/lut_trig.h +++ b/src/include/sof/math/lut_trig.h @@ -5,11 +5,22 @@ * Author: Seppo Ingalsuo */ +/** + * @file sof/math/lut_trig.h + * @brief Fast lookup-table trigonometric sine approximation routines. + * @ingroup dsp_math_api + */ + #ifndef __SOF_MATH_LUT_TRIG_H__ #define __SOF_MATH_LUT_TRIG_H__ #include -int16_t sofm_lut_sin_fixed_16b(int32_t w); /* Input is Q4.28, output is Q1.15 */ +/** + * @brief Fast lookup-table 16-bit fixed-point sine approximation. + * @param w Input phase angle in radians formatted as Q4.28. + * @return Sine approximation in Q1.15 format. + */ +int16_t sofm_lut_sin_fixed_16b(int32_t w); #endif /* __SOF_MATH_LUT_TRIG_H__ */ diff --git a/src/include/sof/math/matrix.h b/src/include/sof/math/matrix.h index f48f1ca4960d..d91738cca46d 100644 --- a/src/include/sof/math/matrix.h +++ b/src/include/sof/math/matrix.h @@ -5,7 +5,11 @@ * Author: Seppo Ingalsuo */ -/* Matrix calculation related functions */ +/** + * @file sof/math/matrix.h + * @brief Matrix math routines, allocation, multiplication, and transposition. + * @ingroup dsp_math_api + */ #ifndef __SOF_MATH_MATRIX_H__ #define __SOF_MATH_MATRIX_H__ diff --git a/src/include/sof/math/numbers.h b/src/include/sof/math/numbers.h index d531b84a81fa..a73bff4c7934 100644 --- a/src/include/sof/math/numbers.h +++ b/src/include/sof/math/numbers.h @@ -7,6 +7,12 @@ * Keyon Jie */ +/** + * @file sof/math/numbers.h + * @brief Fixed-point arithmetic, saturation, rounding, and number format conversions. + * @ingroup dsp_math_api + */ + #ifndef __SOF_MATH_NUMBERS_H__ #define __SOF_MATH_NUMBERS_H__ diff --git a/src/include/sof/math/trig.h b/src/include/sof/math/trig.h index 67428cac494a..a556643c9315 100644 --- a/src/include/sof/math/trig.h +++ b/src/include/sof/math/trig.h @@ -8,6 +8,12 @@ * Shriram Shastry */ +/** + * @file sof/math/trig.h + * @brief Trigonometric, CORDIC, and polynomial approximation functions. + * @ingroup dsp_math_api + */ + #ifndef __SOF_MATH_TRIG_H__ #define __SOF_MATH_TRIG_H__ diff --git a/src/include/sof/math/window.h b/src/include/sof/math/window.h index d72d00b3bd87..e3cd20816872 100644 --- a/src/include/sof/math/window.h +++ b/src/include/sof/math/window.h @@ -5,7 +5,11 @@ * Author: Seppo Ingalsuo */ -/* Window functions related functions */ +/** + * @file sof/math/window.h + * @brief Windowing functions (Blackman, Hamming, Hann, Bartlett, rectangular). + * @ingroup dsp_math_api + */ #ifndef __SOF_MATH_WINDOW_H__ #define __SOF_MATH_WINDOW_H__ diff --git a/src/include/sof/schedule/dp_schedule.h b/src/include/sof/schedule/dp_schedule.h index a2260febb2fc..1d6a3066e07f 100644 --- a/src/include/sof/schedule/dp_schedule.h +++ b/src/include/sof/schedule/dp_schedule.h @@ -5,6 +5,12 @@ * Author: Marcin Szkudlinski */ +/** + * @file sof/schedule/dp_schedule.h + * @brief Data Processing (DP) preemptible worker thread scheduler. + * @ingroup audio_pipeline_api + */ + #ifndef __SOF_SCHEDULE_DP_SCHEDULE_H__ #define __SOF_SCHEDULE_DP_SCHEDULE_H__ @@ -83,6 +89,11 @@ int scheduler_dp_task_init(struct task **task, #if defined(__ZEPHYR__) && CONFIG_SOF_FULL_ZEPHYR_APPLICATION __syscall void scheduler_dp_internal_free(struct task *task); +/** + * @brief Tick notification from the Low-Latency (LL) timer domain to the DP scheduler. + * + * Checks if queued DP tasks require execution or synchronization following an LL period. + */ __syscall void scheduler_dp_ll_tick(void); #include #endif @@ -145,6 +156,13 @@ union scheduler_dp_thread_ipc_param { } get_config; }; +/** + * @brief Dispatch an IPC command to a Data Processing (DP) worker thread. + * @param pmod Pointer to the processing module descriptor. + * @param cmd IPC command identifier to execute. + * @param param Parameters payload for the IPC command. + * @return 0 on success, negative error code on failure. + */ #if CONFIG_ZEPHYR_DP_SCHEDULER int scheduler_dp_thread_ipc(struct processing_module *pmod, unsigned int cmd, union scheduler_dp_thread_ipc_param *param); diff --git a/src/include/sof/schedule/edf_schedule.h b/src/include/sof/schedule/edf_schedule.h index aeb10d5b57c3..1cc14f54d8d8 100644 --- a/src/include/sof/schedule/edf_schedule.h +++ b/src/include/sof/schedule/edf_schedule.h @@ -5,6 +5,12 @@ * Author: Liam Girdwood */ +/** + * @file sof/schedule/edf_schedule.h + * @brief Earliest Deadline First (EDF) scheduler interface. + * @ingroup audio_pipeline_api + */ + #ifndef __SOF_SCHEDULE_EDF_SCHEDULE_H__ #define __SOF_SCHEDULE_EDF_SCHEDULE_H__ @@ -22,8 +28,22 @@ struct edf_task_pdata { void *ctx; }; +/** + * @brief Initialize the Earliest Deadline First (EDF) scheduler. + * @return 0 on success, negative error code on failure. + */ int scheduler_init_edf(void); +/** + * @brief Initialize a task for Earliest Deadline First execution. + * @param task Pointer to task structure. + * @param uid UUID identifying the task. + * @param ops Task operations callbacks. + * @param data Context pointer. + * @param core Target DSP core ID. + * @param flags Scheduling flags. + * @return 0 on success, negative error code on failure. + */ int schedule_task_init_edf(struct task *task, const struct sof_uuid_entry *uid, const struct task_ops *ops, void *data, uint16_t core, uint32_t flags); diff --git a/src/include/sof/schedule/ll_schedule.h b/src/include/sof/schedule/ll_schedule.h index b5baccfe3ab7..5252b46267c8 100644 --- a/src/include/sof/schedule/ll_schedule.h +++ b/src/include/sof/schedule/ll_schedule.h @@ -5,9 +5,13 @@ * Author: Liam Girdwood */ -/* - * Delayed or scheduled work. Work runs in the same context as it's timer - * interrupt source. It should execute quickly and must not sleep or wait. +/** + * @file sof/schedule/ll_schedule.h + * @brief Low-Latency (LL) timer-driven scheduler interface. + * @ingroup audio_pipeline_api + * + * Delayed or scheduled work. Work runs in the same context as its timer + * or DMA interrupt source. It executes deterministically and must not sleep or wait. */ #ifndef __SOF_SCHEDULE_LL_SCHEDULE_H__ @@ -35,16 +39,50 @@ struct ll_task_pdata { uint16_t skip_cnt; /**< how many times the task was skipped for execution */ }; +/** + * @brief Initialize a Low-Latency scheduler for the specified domain. + * @param domain Pointer to the Low-Latency schedule domain (timer or DMA). + * @return 0 on success, negative error code on failure. + */ #if !defined(__ZEPHYR__) int scheduler_init_ll(struct ll_schedule_domain *domain); +/** + * @brief Initialize a Low-Latency real-time task. + * @param task Pointer to task structure to initialize. + * @param uid UUID identifying the task/component. + * @param type Task type identifier. + * @param priority Task scheduling priority. + * @param run Callback function executing the task work. + * @param data Private context pointer passed to run callback. + * @param core Core affinity for the task. + * @param flags Scheduling flags (e.g. dynamic/static). + * @return 0 on success, negative error code on failure. + */ int schedule_task_init_ll(struct task *task, const struct sof_uuid_entry *uid, uint16_t type, int16_t priority, enum task_state (*run)(void *data), void *data, uint16_t core, uint32_t flags); #else +/** + * @brief Initialize the Zephyr Low-Latency scheduler domain. + * @param domain Pointer to the Low-Latency schedule domain. + * @return 0 on success, negative error code on failure. + */ int zephyr_ll_scheduler_init(struct ll_schedule_domain *domain); +/** + * @brief Initialize a Zephyr Low-Latency task. + * @param task Pointer to task structure. + * @param uid UUID identifying the task. + * @param type Task type identifier. + * @param priority Task priority. + * @param run Work callback function. + * @param data Context pointer. + * @param core Target DSP core ID. + * @param flags Scheduling flags. + * @return 0 on success, negative error code on failure. + */ int zephyr_ll_task_init(struct task *task, const struct sof_uuid_entry *uid, uint16_t type, int16_t priority, enum task_state (*run)(void *data), diff --git a/src/include/sof/schedule/schedule.h b/src/include/sof/schedule/schedule.h index f28f472b121f..56dbbdc83a94 100644 --- a/src/include/sof/schedule/schedule.h +++ b/src/include/sof/schedule/schedule.h @@ -19,7 +19,7 @@ #include #include -/** \addtogroup schedule_api Schedule API +/** \addtogroup audio_pipeline_api * @{ */ @@ -182,10 +182,25 @@ struct schedulers { */ struct schedulers **arch_schedulers_get(void); +/** + * @brief Retrieves registered schedulers for user-space threads on the current core. + * @return Pointer to array of registered scheduler pointers. + */ struct schedulers **arch_user_schedulers_get(void); +/** + * @brief Retrieves registered schedulers for user-space threads on a specific core. + * @param core Target DSP core ID. + * @return Pointer to array of registered scheduler pointers for the specified core. + */ struct schedulers **arch_user_schedulers_get_for_core(int core); +/** + * @brief Lookup scheduler private context data by scheduler type. + * @param schedulers Schedulers list container. + * @param type Scheduler type identifier (SOF_SCHEDULE_LL, SOF_SCHEDULE_EDF, etc.). + * @return Pointer to scheduler-specific private data, or NULL if not found. + */ static inline void *scheduler_list_get_data(struct schedulers *schedulers, uint16_t type) { struct schedule_data *sch; diff --git a/zephyr/include/rtos/alloc.h b/zephyr/include/rtos/alloc.h index b727d1e700fb..a146aa0ead92 100644 --- a/zephyr/include/rtos/alloc.h +++ b/zephyr/include/rtos/alloc.h @@ -3,6 +3,12 @@ * Copyright(c) 2022 Intel Corporation. All rights reserved. */ +/** + * @file rtos/alloc.h + * @brief Memory allocation API, zones, heaps, and alignment utilities. + * @ingroup rtos_api + */ + #ifndef __ZEPHYR_RTOS_ALLOC_H__ #define __ZEPHYR_RTOS_ALLOC_H__ @@ -15,7 +21,7 @@ #include #include -/** \addtogroup alloc_api Memory Allocation API +/** \addtogroup rtos_api * @{ */ @@ -99,21 +105,39 @@ void rfree(void *ptr); */ void l3_heap_save(void); -/* - * This is ugly to define the signatures twice, but this - * is required to support userspace builds that do not export alloc. +/** + * @brief Allocate memory from a specified Zephyr heap or default system heap. + * @param heap Target Zephyr k_heap (or NULL to let implementation choose). + * @param flags Memory allocation flags (SOF_MEM_FLAG_...). + * @param bytes Size in bytes to allocate. + * @param alignment Required memory alignment in bytes. + * @return Pointer to allocated buffer, or NULL on allocation failure. */ #ifdef CONFIG_SOF_USERSPACE_INTERFACE_ALLOC __syscall void *sof_heap_alloc(struct k_heap *heap, uint32_t flags, size_t bytes, size_t alignment); +/** + * @brief Free memory allocated via sof_heap_alloc(). + * @param heap Target Zephyr k_heap. + * @param addr Address of allocated buffer to free. + */ __syscall void sof_heap_free(struct k_heap *heap, void *addr); #include #else void *sof_heap_alloc(struct k_heap *heap, uint32_t flags, size_t bytes, size_t alignment); +/** + * @brief Free memory allocated via sof_heap_alloc(). + * @param heap Target Zephyr k_heap. + * @param addr Address of allocated buffer to free. + */ void sof_heap_free(struct k_heap *heap, void *addr); #endif +/** + * @brief Get the system kernel heap descriptor. + * @return Pointer to the global system k_heap structure. + */ #if CONFIG_SOF_FULL_ZEPHYR_APPLICATION struct k_heap *sof_sys_heap_get(void); #else @@ -140,7 +164,10 @@ static inline struct k_heap *sof_sys_heap_get(void) */ struct k_heap *sof_sys_user_heap_get(void); -/* TODO: remove - debug only - only needed for linking */ +/** + * @brief Trace and log memory allocation statistics across all active heaps. + * @param force Force dumping heap trace even if logging threshold is not met. + */ static inline void heap_trace_all(int force) {} /** @}*/ diff --git a/zephyr/include/rtos/cache.h b/zephyr/include/rtos/cache.h index 576e1c5bea3d..e7ddbcb2e2be 100644 --- a/zephyr/include/rtos/cache.h +++ b/zephyr/include/rtos/cache.h @@ -3,6 +3,12 @@ * Copyright(c) 2022 Intel Corporation. All rights reserved. */ +/** + * @file rtos/cache.h + * @brief RTOS data and instruction cache invalidation and writeback helpers. + * @ingroup rtos_api + */ + #ifndef __ZEPHYR_RTOS_CACHE_H__ #define __ZEPHYR_RTOS_CACHE_H__ @@ -35,24 +41,57 @@ #endif /* defined(CONFIG_LIBRARY) || defined(CONFIG_ZEPHYR_POSIX) */ #endif /* !defined(CONFIG_DCACHE_LINE_SIZE_DETECT) && (CONFIG_DCACHE_LINE_SIZE > 0) */ +/** + * @brief Write back (flush) modified data cache lines to memory. + * @param addr Starting address of the memory region to flush. + * @param size Size in bytes of the region to flush. + * + * Flushes dirty lines in the data cache covering the specified address range + * back to physical memory or SRAM. Mandatory before handing buffers over to + * hardware DMA or notifying peer cores / host. + */ static inline void dcache_writeback_region(void __sparse_cache *addr, size_t size) { /* TODO: return value should probably be checked here */ sys_cache_data_flush_range((__sparse_force void *)addr, size); } +/** + * @brief Invalidate data cache lines in the specified memory region. + * @param addr Starting address of the memory region to invalidate. + * @param size Size in bytes of the region to invalidate. + * + * Discards cached data lines covering the address range so subsequent reads + * fetch fresh data directly from physical SRAM or DMA-updated memory. + */ static inline void dcache_invalidate_region(void __sparse_cache *addr, size_t size) { /* TODO: return value should probably be checked here */ sys_cache_data_invd_range((__sparse_force void *)addr, size); } +/** + * @brief Invalidate instruction cache lines in the specified memory region. + * @param addr Starting address of the code memory region to invalidate. + * @param size Size in bytes of the code region. + * + * Used after dynamically loading or relocating executable code (e.g. LLEXT + * modules) to ensure the instruction pipeline does not execute stale instructions. + */ static inline void icache_invalidate_region(void __sparse_cache *addr, size_t size) { /* TODO: return value should probably be checked here */ sys_cache_instr_invd_range((__sparse_force void *)addr, size); } +/** + * @brief Write back and invalidate data cache lines in the specified memory region. + * @param addr Starting address of the memory region. + * @param size Size in bytes of the region. + * + * Flushes modified cache lines back to memory and then invalidates them. + * Typically used for bidirectional DMA buffers or when reallocating SRAM pools. + */ static inline void dcache_writeback_invalidate_region(void __sparse_cache *addr, size_t size) { /* TODO: return value should probably be checked here */ diff --git a/zephyr/include/rtos/clk.h b/zephyr/include/rtos/clk.h index 6db452bdab88..20cd6a1ac87c 100644 --- a/zephyr/include/rtos/clk.h +++ b/zephyr/include/rtos/clk.h @@ -3,6 +3,12 @@ * Copyright(c) 2022 Intel Corporation. All rights reserved. */ +/** + * @file rtos/clk.h + * @brief RTOS DSP clock frequency management and notification interfaces. + * @ingroup rtos_api + */ + #ifndef __ZEPHYR_RTOS_CLK_H__ #define __ZEPHYR_RTOS_CLK_H__ diff --git a/zephyr/include/rtos/kernel.h b/zephyr/include/rtos/kernel.h index 328fc96d2eaa..47cb436128aa 100644 --- a/zephyr/include/rtos/kernel.h +++ b/zephyr/include/rtos/kernel.h @@ -3,6 +3,12 @@ // Copyright(c) 2020 Intel Corporation. All rights reserved. // +/** + * @file rtos/kernel.h + * @brief RTOS kernel threading and privilege helpers. + * @ingroup rtos_api + */ + #ifndef __ZEPHYR_RTOS_KERNEL_H__ #define __ZEPHYR_RTOS_KERNEL_H__ @@ -10,6 +16,11 @@ #include +/** + * @brief Test if a thread is running with user-space (unprivileged) options. + * @param thread Pointer to the Zephyr thread control structure. + * @return True if the thread has K_USER option set, false otherwise. + */ static inline bool thread_is_userspace(struct k_thread *thread) { return !!(thread->base.user_options & K_USER); diff --git a/zephyr/include/rtos/mutex.h b/zephyr/include/rtos/mutex.h index a8886f768d1e..631bdaf9c838 100644 --- a/zephyr/include/rtos/mutex.h +++ b/zephyr/include/rtos/mutex.h @@ -3,6 +3,12 @@ // Copyright(c) 2024 Intel Corporation. // +/** + * @file rtos/mutex.h + * @brief RTOS mutex primitives and synchronization wrappers. + * @ingroup rtos_api + */ + #ifndef __ZEPHYR_RTOS_MUTEX_H__ #define __ZEPHYR_RTOS_MUTEX_H__ diff --git a/zephyr/include/rtos/sof.h b/zephyr/include/rtos/sof.h index efe0c1e6acab..8ac4834f1e78 100644 --- a/zephyr/include/rtos/sof.h +++ b/zephyr/include/rtos/sof.h @@ -5,6 +5,12 @@ * Author: Liam Girdwood */ +/** + * @file rtos/sof.h + * @brief Sound Open Firmware global runtime context. + * @ingroup rtos_api + */ + #ifndef __ZEPHYR_RTOS_SOF_H__ #define __ZEPHYR_RTOS_SOF_H__ @@ -116,6 +122,10 @@ struct sof { __aligned(PLATFORM_DCACHE_ALIGN) int alignment[0]; } __aligned(PLATFORM_DCACHE_ALIGN); +/** + * @brief Get the global Sound Open Firmware runtime instance pointer. + * @return Pointer to the global struct sof runtime descriptor. + */ struct sof *sof_get(void); #endif /* __ZEPHYR_RTOS_SOF_H__ */ diff --git a/zephyr/include/rtos/spinlock.h b/zephyr/include/rtos/spinlock.h index 24b0ee9dc579..766edb6f87d7 100644 --- a/zephyr/include/rtos/spinlock.h +++ b/zephyr/include/rtos/spinlock.h @@ -3,13 +3,25 @@ // Copyright(c) 2020 Intel Corporation. All rights reserved. // +/** + * @file rtos/spinlock.h + * @brief RTOS spinlock primitives and initialization. + * @ingroup rtos_api + */ + #ifndef __ZEPHYR_RTOS_SPINLOCK_H__ #define __ZEPHYR_RTOS_SPINLOCK_H__ #include #include -/* not implemented on Zephyr, but used within SOF */ +/** + * @brief Initialize a spinlock structure to the unlocked state. + * @param lock Pointer to the Zephyr k_spinlock structure. + * + * Clears the locked atomic flag on SMP systems. Not provided by upstream + * Zephyr core, but required by SOF multi-core synchronization primitives. + */ static inline void k_spinlock_init(struct k_spinlock *lock) { #ifdef CONFIG_SMP diff --git a/zephyr/include/rtos/timer.h b/zephyr/include/rtos/timer.h index 412ceeda0038..fef53389faac 100644 --- a/zephyr/include/rtos/timer.h +++ b/zephyr/include/rtos/timer.h @@ -3,6 +3,12 @@ * Copyright(c) 2022 Intel Corporation. All rights reserved. */ +/** + * @file rtos/timer.h + * @brief RTOS cycle counter, hardware timer, and timestamp utilities. + * @ingroup rtos_api + */ + #ifndef __ZEPHYR_RTOS_TIMER_H__ #define __ZEPHYR_RTOS_TIMER_H__ diff --git a/zephyr/include/rtos/userspace_helper.h b/zephyr/include/rtos/userspace_helper.h index b29d2daa57c0..b3b122accf9a 100644 --- a/zephyr/include/rtos/userspace_helper.h +++ b/zephyr/include/rtos/userspace_helper.h @@ -140,6 +140,12 @@ void user_grant_dma_access_all(struct k_thread *thread); #else +/** + * @brief Add access to mailbox.h interface to a user-space thread (no-op stub when CONFIG_USERSPACE is disabled). + * @param domain Memory domain. + * @param thread_id User-space thread identifier. + * @return 0 on success. + */ static inline int user_access_to_mailbox(struct k_mem_domain *domain, k_tid_t thread_id) { return 0; diff --git a/zephyr/include/sof/trace/trace.h b/zephyr/include/sof/trace/trace.h index 656b859fb514..3032a7147783 100644 --- a/zephyr/include/sof/trace/trace.h +++ b/zephyr/include/sof/trace/trace.h @@ -22,6 +22,11 @@ #include "../../../../src/include/sof/trace/trace.h" struct timer; +/** + * @brief Get high-resolution 64-bit hardware timer value for trace timestamping. + * @param timer Pointer to hardware timer descriptor. + * @return 64-bit current timer count. + */ uint64_t platform_timer_get(struct timer *timer); /*