docs: developer guides reorg, API simplification, releases, and FAQ updates

Makefile

@@ -9,7 +9,13 @@ else
   Q = @
 endif
 
-SOF_DOC_BUILD = ../sof/build_doxygen/
+# Locate SOF firmware repository: check SOF_ROOT, or candidate directories
+ifeq ($(SOF_ROOT),)
+  SOF_ROOT := $(firstword $(wildcard ../sof-dox-work ../sof ../sof-tgl/sof /home/lrg/work/sof-dox-work))
+endif
+SOF_DOC_BUILD ?= $(if $(SOF_ROOT),$(SOF_ROOT)/build_doxygen,_build_doxygen)
+SOF_HAS_DOC := $(wildcard $(SOF_ROOT)/doc/CMakeLists.txt)
+
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = "SOF Project"
 SOURCEDIR     = .
@@ -34,21 +40,19 @@ help:
 .PHONY: help apidocs html clean
 
 
-# Generate the doxygen xml (for Sphinx) and copy the doxygen html to the
-# api folder for publishing along with the Sphinx-generated API docs.
-# Keep doxygen optional not to burden "drive-by" .rst contributors with
-# extra dependencies.
-
-APIS_CMAKE := ${SOF_DOC_BUILD}/build.ninja
+# Generate the doxygen xml (for Sphinx Breathe) and copy the doxygen html
+# for publishing along with the Sphinx-generated API docs.
 apidocs:
-ifeq (${APIS_CMAKE},$(wildcard ${APIS_CMAKE}))
-	ninja -C ${SOF_DOC_BUILD} $${VERBOSE:+-v} doc
+ifneq ($(SOF_HAS_DOC),)
+	@if [ ! -f "$(SOF_DOC_BUILD)/build.ninja" ]; then \
+		echo "Configuring Doxygen build with CMake in $(SOF_DOC_BUILD)..."; \
+		cmake -GNinja -S "$(SOF_ROOT)/doc" -B "$(SOF_DOC_BUILD)"; \
+	fi
+	@echo "Building Doxygen documentation in $(SOF_DOC_BUILD)..."
+	ninja -C "$(SOF_DOC_BUILD)" $${VERBOSE:+-v} doc
 else
-	# To include doxygen APIs run this first:
-	#   cmake -GNinja -S ../sof/doc -B ${SOF_DOC_BUILD}
-	# Note this will make the build CONSIDERABLY LONGER!
-	# Conversely, you can have _instant builds from scratch_
-	# by disabling UML diagrams in the conf.py file.
+	@echo "Note: SOF firmware source tree (doc/CMakeLists.txt) not found."
+	@echo "      Specify SOF_ROOT=/path/to/sof to generate live C API documentation."
 endif
 
 PYTHON ?= python3
@@ -58,18 +62,25 @@ generate_data:
 
 html: generate_data apidocs
 	$(SPHINXBUILD) -j auto -t $(DOC_TAG) -b html               \
--d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS)    \
--D breathe_projects.'SOF Project'="${SOF_DOC_BUILD}"/doxygen/xml \
-$(ERROROPTS) $(O)
+		-d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS)    \
+		$(if $(wildcard $(SOF_DOC_BUILD)/doxygen/xml),-D breathe_projects.'SOF Project'="$(abspath $(SOF_DOC_BUILD)/doxygen/xml)",) \
+		$(ERROROPTS) $(O)
+	@if [ -d "$(SOF_DOC_BUILD)/doxygen/html" ]; then \
+		echo "Copying raw Doxygen HTML to $(BUILDDIR)/html/doxygen..."; \
+		mkdir -p $(BUILDDIR)/html/doxygen; \
+		cp -r $(SOF_DOC_BUILD)/doxygen/html/* $(BUILDDIR)/html/doxygen/; \
+	fi
 	# Reminder: to see _all_ warnings you must "make clean" first.
 
 
 # Remove generated content (Sphinx and doxygen)
 
 clean:
 	rm -fr $(BUILDDIR)
-ifeq (${APIS_CMAKE},$(wildcard ${APIS_CMAKE}))
-	ninja -C ${SOF_DOC_BUILD} $${VERBOSE:+-v} doc-clean clean
+ifneq ($(SOF_HAS_DOC),)
+	@if [ -f "$(SOF_DOC_BUILD)/build.ninja" ]; then \
+		ninja -C "$(SOF_DOC_BUILD)" $${VERBOSE:+-v} doc-clean clean; \
+	fi
 endif
 
 # Copy material over to the GitHub pages staging repo

README.md

@@ -5,4 +5,4 @@ SOF Project documentation web site published to
 https://thesofproject.github.io
 
 Learn how to setup and generate documentation by reading
-https://thesofproject.github.io/latest/contribute/process/docbuild.html
+https://thesofproject.github.io/latest/contribute/index.html#building-publishing-documentation

algos/index.rst

@@ -6,9 +6,14 @@ Algorithms
 Supplied Processing Algorithms
 ******************************
 
-SOF contains several permissively-licensed and royalty-free audio processing
-algorithms that can be used alongside proprietary processing components to
-build pipelines.
+SOF provides an extensive ecosystem of permissively-licensed and royalty-free audio processing
+algorithms that can be used alongside proprietary processing components to build production audio pipelines.
+
+In addition to upstream native algorithms, license-compatible open-source algorithms from external projects
+(such as FFmpeg, WebRTC, Valve Steam Audio, CMSIS-DSP, and vendor DSP libraries) can be compiled as dynamically
+loadable modules (e.g. Zephyr LLEXT / ELF modules) and linked at runtime into active audio pipelines. This
+modular architecture allows open-source, vendor, and proprietary intellectual property (IP) components to be safely
+integrated into the same pipeline graph without license contamination or monolithic recompilation.
 
 .. include:: _generated_modules_table.rst
 

api/index.rst

@@ -1,18 +1,62 @@
 .. _api:
+.. _uuid-api:
 
 API Documentation
 #################
 
-.. toctree::
-   :maxdepth: 1
-
-   uuid-api
-   dma-drivers-api
-   dai-drivers-api
-   pm-runtime-api
-   platform-api
-   memory-alloc-api
-   audio-stream-api
-   component-api
-   component-ext-api
-   uapi
+The Sound Open Firmware (SOF) C application programming interface (API) documentation
+is generated directly from the firmware source code comments and header files using
+Doxygen. This ensures that the documentation is always synchronized with the actual
+implementation across all supported audio components, pipeline infrastructure,
+hardware abstraction layers, and IPC protocols.
+
+.. raw:: html
+
+   <div style="border-left: 4px solid var(--pst-color-primary, #0a7d91); padding: 1.5rem; margin: 1.5rem 0; border-radius: 8px; background-color: var(--pst-color-surface, #f8f9fa); border: 1px solid var(--pst-color-border, #e5e7eb); border-left-width: 4px;">
+     <h3 style="margin-top: 0; color: var(--pst-color-primary, #0a7d91); font-size: 1.3rem;">Sound Open Firmware Doxygen API Documentation</h3>
+     <p style="margin-bottom: 1.25rem; font-size: 1rem; line-height: 1.5;">
+       Browse the complete, interactive C API reference generated directly from the SOF firmware codebase, including data structures, function declarations, macros, enumerations, file hierarchies, and dependency call graphs.
+     </p>
+     <a href="../doxygen/index.html" style="font-weight: 600; padding: 0.65rem 1.4rem; border-radius: 5px; display: inline-block; text-decoration: none; background-color: #0a7d91; color: #ffffff;">
+       Open Doxygen API Reference &rarr;
+     </a>
+   </div>
+
+Overview of Documented Modules
+******************************
+
+The Doxygen documentation covers the entire public firmware and host-shared interface:
+
+* **Audio Components & Pipelines**:
+  Core component driver lifecycle (``component.h``), component extensions and buffer helpers (``component_ext.h``), and PCM stream buffer utilities (``audio_stream.h``).
+
+* **Hardware Drivers & Interfaces**:
+  Direct Memory Access (``dma.h``), Digital Audio Interfaces for I2S/SSP, SoundWire/ALH, DMIC/PDM, and HDA (``dai.h``), Power Management runtime (``pm_runtime.h``), and platform hardware timers and interrupt controllers (``platform.h``).
+
+* **Core RTOS & System Services**:
+  Real-time task scheduling (EDF, LL-Timer, LL-DMA, Zephyr DataProcessing threads in ``schedule.h``), memory allocation heaps (``alloc.h``), and component/pipeline UUID declarations (``uuid.h``).
+
+* **IPC & Host Interfaces**:
+  User/Kernel IPC ABI protocols and messaging envelopes (``ipc/header.h``, ``ipc/control.h``), and SRAM Window 0 firmware status registers and telemetry offsets (``kernel/mailbox.h``).
+
+* **Source Code Graphs & File Browsing**:
+  Full source file tree, header include dependency graphs, and function call/caller graphs.
+
+Building API Documentation Locally
+**********************************
+
+To build or refresh the Doxygen documentation alongside the Sphinx documentation:
+
+.. code-block:: bash
+
+   # From the sof-docs repository root
+   make apidocs   # Generates Doxygen XML and HTML
+   make html      # Generates Sphinx site and stages Doxygen at _build/html/doxygen/
+
+Alternatively, Doxygen can be built directly inside the SOF firmware repository:
+
+.. code-block:: bash
+
+   # From the sof firmware repository root
+   cmake -GNinja -S doc -B build_doxygen
+   ninja -C build_doxygen doc

conf.py

@@ -78,7 +78,7 @@
 templates_path = ['_templates']
 
 # Fixes "WARNING: Error when parsing function declaration."
-c_id_attributes = ["__sparse_cache", "__syscall"]
+c_id_attributes = ["__sparse_cache", "__syscall", "__packed", "__aligned", "__kernel", "__user", "__section"]
 cpp_id_attributes = c_id_attributes
 # cpp_paren_attributes = ["_ALIAS_OF", "__printf_like"]
 breathe_domain_by_extension = {"h": "c"}
@@ -294,8 +294,24 @@ def filter(self, record):
 """
 
 
+# Look for Doxygen XML path if not already provided or overridden
+_breathe_xml_candidates = [
+    os.path.join(os.environ['SOF_DOC_BUILD'], 'doxygen/xml') if os.environ.get('SOF_DOC_BUILD') else None,
+    os.path.join(os.environ['SOF_ROOT'], 'build_doxygen/doxygen/xml') if os.environ.get('SOF_ROOT') else None,
+    os.path.abspath('../sof-dox-work/build_doxygen/doxygen/xml'),
+    os.path.abspath('../sof/build_doxygen/doxygen/xml'),
+    os.path.abspath('../sof-tgl/sof/build_doxygen/doxygen/xml'),
+    os.path.abspath('../sof/doc/doxygen/xml'),
+]
+
+_breathe_xml_path = None
+for _cand in _breathe_xml_candidates:
+    if _cand and os.path.isdir(_cand):
+        _breathe_xml_path = _cand
+        break
+
 breathe_projects = {
-   "SOF Project" : "../sof/doc/doxygen/xml",
+   "SOF Project" : _breathe_xml_path or "../sof/doc/doxygen/xml",
 }
 breathe_default_project = "SOF Project"
 breathe_default_members = ('members', 'undoc-members', 'content-only')