Skip to content

docs: developer_guides: enrich technical context across all steps in module integration guide - #534

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

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

Conversation

@lgirdwood

Copy link
Copy Markdown
Member

Description

Enrich every step and subsection in the Audio Module Integration Guide (developer_guides/firmware/module_integration_guide.rst) with comprehensive technical context, architectural rationale, and practical engineering directives:

  • Step 1 (Directory Structure & File Taxonomy): Explain architectural separation of concerns (adapter vs reference math vs SIMD acceleration vs IPC serialization) and third-party library placement.
  • Step 2 (Core Headers & Lifecycle): Detail header subsystem domains, Zephyr logging levels, and provide in-depth operational rules for all lifecycle callbacks (init, prepare, process, set_configuration, get_configuration, reset, and free) along with static linking vs dynamic LLEXT export.
  • Step 3 (UUID Generation & Endianness): Explain RFC 4122 v4 UUID semantics, global collision detection via scripts/gen-uuid-reg.py, and little-endian word swapping in ALSA Topology 2.0 / IPC4.
  • Step 4 (Memory Tiering & Cold-Code Placement): Detail DSP memory tiering, .text.cold/.data.cold linker sections, assert_can_be_cold() validation, and module adapter allocators.
  • Step 5 (Vector Data Alignment & SIMD Optimization): Detail SIMD hardware vector unit mechanics, LoadStoreAlignmentCause exceptions, member alignment (__aligned(16)) vs cache line alignment (__aligned(PLATFORM_DCACHE_ALIGN)), and runtime buffer allocation.
  • Step 6 (CMake & Kconfig Build Integration): Detail Kconfig tristate (y/m/n) semantics, architecture dependency gating, CMake target delegation (llext vs static), IPC versioning dispatch, parent tree discovery, and multi-toolchain CI requirements across Cadence XCC, Zephyr SDK GCC, and LLVM/Clang (IAS).
  • Step 7 (ALSA Topology 2.0 Integration): Explain ALSA Topology 2.0 object-oriented class syntax, mixer control volsw semantics, pipeline routing, and alsatplg validation.
  • Step 8 (Verification with Host Testbench): Detail Host Testbench emulation architecture, offline WAV-to-WAV simulation flags, dynamic parameter injection timing, and Valgrind memory integrity verification.
  • Step 9 (Cadence xt-run Simulation): Detail Cadence xt-run cycle-accurate simulation, cross-compilation with XtDevTools, MCPS mathematical formula, cache miss/stall analysis, and xt-gprof call-graph bottleneck diagnosis.
  • Step 10 (Building Firmware & Device Deployment): Detail deployable firmware building with rimage signing, staged artifact hierarchy (.ri, .ldc, .llext), target deployment patterns (local filesystem vs PXE NFS rootfs), driver unbind/bind reload, dmesg milestones, and live trace logging.

Verification

  • Sphinx build (sphinx-build -b html -W --keep-going . _build/html) completed with 0 errors and 0 warnings.
  • Woke check verified 0 occurrences of prohibited inclusive language terms.
  • Visual inspection via headless Chrome screenshots confirmed flawless layout, formatting, diagrams, and tables.

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

…module integration guide

Enrich every step and subsection in the Audio Module Integration Guide
(module_integration_guide.rst) with comprehensive technical context,
architectural principles, and practical developer directives:

- Step 1: Explain architectural separation of concerns (adapter vs math
  reference vs SIMD acceleration vs IPC serialization) and third-party
  library placement rules.
- Step 2: Detail header subsystem domains, Zephyr logging levels, and
  provide in-depth operational rules for all lifecycle callbacks
  (init, prepare, process, set_configuration, get_configuration, reset,
  and free) along with static linking vs dynamic LLEXT export.
- Step 3: Explain RFC 4122 v4 UUID semantics, global collision detection
  via scripts/gen-uuid-reg.py, and little-endian word swapping in ALSA
  Topology 2.0 / IPC4.
- Step 4: Detail DSP memory tiering, .text.cold/.data.cold linker sections,
  assert_can_be_cold() validation, and module adapter allocators.
- Step 5: Detail SIMD hardware vector unit mechanics, LoadStoreAlignmentCause
  exceptions, member alignment (__aligned(16)) vs cache line alignment
  (__aligned(PLATFORM_DCACHE_ALIGN)), and runtime buffer allocation.
- Step 6: Detail Kconfig tristate (y/m/n) semantics, architecture
  dependency gating, CMake target delegation (llext vs static),
  IPC versioning dispatch, parent tree discovery, and multi-toolchain
  CI requirements across Cadence XCC, Zephyr SDK GCC, and LLVM/Clang (IAS).
- Step 7: Explain ALSA Topology 2.0 object-oriented class syntax, mixer
  control volsw semantics, pipeline routing, and alsatplg validation.
- Step 8: Detail Host Testbench emulation architecture, offline WAV-to-WAV
  simulation flags, dynamic parameter injection timing, and Valgrind
  memory integrity verification.
- Step 9: Detail Cadence xt-run cycle-accurate simulation, cross-compilation
  with XtDevTools, MCPS mathematical formula, cache miss/stall analysis,
  and xt-gprof call-graph bottleneck diagnosis.
- Step 10: Detail deployable firmware building with rimage signing, staged
  artifact hierarchy (.ri, .ldc, .llext), target deployment patterns
  (local filesystem vs PXE NFS rootfs), driver unbind/bind reload, dmesg
  milestones, and live trace logging.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
@lgirdwood
lgirdwood merged commit c1e513c into thesofproject:master Sep 20, 2026
5 checks passed
@lgirdwood
lgirdwood deleted the topic/module-guide-enrich-context branch September 20, 2026 18:29
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