Skip to content

docs: developer_guides: add how-to guide on creating and integrating audio modules - #530

Merged
lgirdwood merged 1 commit into
thesofproject:masterfrom
lgirdwood:topic/howto-module-guide
Sep 20, 2026
Merged

lgirdwood merged 1 commit into
thesofproject:masterfrom
lgirdwood:topic/howto-module-guide

Conversation

@lgirdwood

Copy link
Copy Markdown
Member

Description

This PR adds a comprehensive, step-by-step developer How-To guide under Section 1 (Firmware Development) detailing the full lifecycle for creating a new audio processing module or integrating third-party algorithms into Sound Open Firmware.

Key Coverage & Topics:

  • Directory Structure & Taxonomy: File roles (<module>.h, <module>.c, <module>-generic.c, <module>-ipc4.c, <module>.toml, CMakeLists.txt, Kconfig, and llext/).
  • Core Interface & State Machine: Implementation of struct module_interface callbacks (init, prepare, process, set_configuration, get_configuration, reset, free).
  • UUID & Endianness (Watch Out!): RFC 4122 generation, registration in uuid-registry.txt, and critical little-endian word-swapping rules for ALSA Topology 2.0 / IPC4 wire protocol.
  • Memory Tiering & Cold Code: Using __cold on initialization and teardown routines, assert_can_be_cold(), and strict zero-allocation rules in real-time audio paths.
  • SIMD Vector Alignment: Alignment requirements across Tensilica HiFi 3 (8B), HiFi 4 (16B), HiFi 5 (32B), ARM Helium/Neon, and RISC-V; dynamic allocation with mod_balloc_align(), avoiding alignment exceptions.
  • Build Integration (CMake & Kconfig): In-tree vs dynamic LLEXT loadable extension packaging, and multi-toolchain build verification across Cadence Xtensa Tools, Zephyr SDK, and experimental LLVM/Clang with mandatory Integrated Assembler.
  • ALSA Topology 2.0 Integration: Authoring widget definitions, binding mixer switch controls and coefficient byte blobs, and compiling with alsatplg.
  • Host Testbench Simulation: Fast offline WAV-to-WAV pipeline testing, dynamic parameter control scripts (-s controls.sh), and Valgrind memory leak verification.
  • Cycle-Accurate DSP Simulation with Cadence xt-run: Running cycle-accurate simulation, calculating MCPS budgets, and call-graph profiling with xt-gprof.
  • Target Deployment: Target firmware builds with --deployable-build, filesystem staging, driver reload, and live ALSA verification.
  • Visual Architecture: Includes high-resolution SVG diagrams for the engineering lifecycle and runtime module state machine.

Verification:

  • woke -c rules-woke.yaml: 0 findings
  • sphinx-build -b html -W --keep-going: 0 warnings, 0 errors
  • Visual verification of rendered layout via headless browser screenshots

Signed-off-by: Liam Girdwood liam.r.girdwood@linux.intel.com

…audio modules

Add a comprehensive, step-by-step developer how-to guide under Section 1
(Firmware Development) detailing the complete lifecycle for creating a new
audio processing module or integrating third-party algorithms into Sound Open
Firmware:
- Directory structure, file taxonomy, and standard module file roles.
- struct module_interface lifecycle callbacks (init, prepare, process,
  set_configuration, get_configuration, reset, free) and state machine.
- RFC 4122 UUID generation, uuid-registry.txt integration, and critical
  little-endian word-swapping rules required for ALSA Topology 2.0 / IPC4.
- DSP memory tiering, __cold attribute placement, assert_can_be_cold(),
  and strict zero-allocation rules in real-time audio paths.
- Hardware SIMD vector alignment across Tensilica HiFi3/4/5, ARM Helium/Neon,
  and RISC-V, mod_balloc_align(), and alignment exception prevention.
- Kconfig definitions, CMakeLists.txt dispatch (in-tree vs dynamic LLEXT),
  and 3-toolchain compatibility (Cadence, Zephyr SDK, LLVM with IAS).
- ALSA Topology 2.0 component widget definitions and mixer/byte controls.
- Offline pipeline simulation with Host Testbench, dynamic control scripts,
  and memory leak validation with Valgrind.
- Cycle-accurate DSP simulation with Cadence xt-run and call-graph profiling
  with xt-gprof for MCPS budget calculations.
- Target firmware compilation, deployable staging, filesystem transfer,
  and Linux kernel driver reloading.
- Includes high-resolution SVG diagrams for the engineering lifecycle and
  runtime module lifecycle state machine.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
@lgirdwood
lgirdwood merged commit 0c434e1 into thesofproject:master Sep 20, 2026
5 checks passed
@lgirdwood
lgirdwood deleted the topic/howto-module-guide branch September 20, 2026 15:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants