docs: developer_guides: enrich technical context across all steps in module integration guide - #534
Merged
lgirdwood merged 1 commit intoSep 20, 2026
Conversation
…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
requested review from
deb-intel,
intelkevinputnam,
mmaka1 and
mwasko
as code owners
September 20, 2026 18:27
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:init,prepare,process,set_configuration,get_configuration,reset, andfree) along with static linking vs dynamic LLEXT export.scripts/gen-uuid-reg.py, and little-endian word swapping in ALSA Topology 2.0 / IPC4..text.cold/.data.coldlinker sections,assert_can_be_cold()validation, and module adapter allocators.LoadStoreAlignmentCauseexceptions, member alignment (__aligned(16)) vs cache line alignment (__aligned(PLATFORM_DCACHE_ALIGN)), and runtime buffer allocation.alsatplgvalidation.xt-runcycle-accurate simulation, cross-compilation with XtDevTools, MCPS mathematical formula, cache miss/stall analysis, andxt-gprofcall-graph bottleneck diagnosis.rimagesigning, staged artifact hierarchy (.ri,.ldc,.llext), target deployment patterns (local filesystem vs PXE NFS rootfs), driver unbind/bind reload,dmesgmilestones, and live trace logging.Verification
sphinx-build -b html -W --keep-going . _build/html) completed with 0 errors and 0 warnings.Signed-off-by: Liam Girdwood liam.r.girdwood@linux.intel.com