Repository navigation
doc: ipc4: comprehensive audit and upgrade of IPC4 protocol Doxygen documentation - #11302
Merged
lgirdwood merged 9 commits intoOct 14, 2026
Merged
Conversation
…d handlers Establish 8 structured IPC4 architectural subgroups under ipc4_api in doc/groups.dox (envelope, base firmware, pipeline, module, audio format, gateways, notifications, telemetry/probes) and link them from mainpage.dox. Document the 64-bit message envelope formats, primary/extension DWORD bitfields, global and module command opcodes, processing status codes, ALSA control payloads, userspace handler bridges, and compound message synchronization barriers. Pure Doxygen documentation changes with zero C code syntax alterations. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…n descriptors Assign audio format specifications to the ipc4_format_api subgroup. Document PCM and encoded sampling frequency enumerations, bit depth containers, channel mapping nibbles and topologies, interleaved styles, sample representation types, stream formats, base and extended module pin configurations, runtime pin properties, instance telemetry, and stream parameter conversion bridge routines. Pure Doxygen documentation changes with zero C code syntax alterations. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Assign module structures and operations to the ipc4_module_api subgroup. Document module opcodes, compound parameter IDs, memory requirements for Data Processing (DP) threads, GNA coprocessor cycles, instance creation and deletion commands, pin binding and unbinding envelopes, small parameter register packs, and the Large Config multi-block chunking protocol. Also document specialized module parameter structures for Key Phrase Buffer (KPB), Acoustic Echo Cancellation (AEC), and Keyword Detector (KD) test under ipc4_telemetry_probe_api. Pure Doxygen documentation changes with zero C code syntax alterations. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…ions Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…rformance metrics Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…P configuration Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…ging Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
lgirdwood
requested review from
dbaluta,
kv2019i,
lbetlej,
mmaka1,
pblaszko,
plbossart and
tmleman
as code owners
October 13, 2026 15:16
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Several new comments misstate IPC4 opcode, sample alignment, core-range, probe, and notification contracts.
6 open findings
What changed in this PR
This PR reorganizes and expands IPC4 protocol Doxygen documentation without changing code or ABI definitions.
Changes:
- Adds eight IPC4 documentation subgroups.
- Expands documentation for protocol structures, commands, formats, gateways, and telemetry.
- Updates the Doxygen main page and group index.
| File | Description |
|---|---|
doc/groups.dox |
Defines IPC4 subgroups. |
doc/mainpage.dox |
Updates IPC4 navigation. |
src/include/module/ipc4/base-config.h |
Documents common formats and configurations. |
src/include/ipc4/aec.h |
Documents AEC configuration. |
src/include/ipc4/alh.h |
Documents ALH gateways. |
src/include/ipc4/ams_helpers.h |
Documents AMS helpers. |
src/include/ipc4/base-config.h |
Documents format conversion APIs. |
src/include/ipc4/base_fw.h |
Expands Base FW documentation. |
src/include/ipc4/base_fw_vendor.h |
Documents vendor Base FW APIs. |
src/include/ipc4/detect_test.h |
Documents keyword detector parameters. |
src/include/ipc4/dmic.h |
Documents DMIC configuration. |
src/include/ipc4/error_status.h |
Documents IPC4 status codes. |
src/include/ipc4/fw_reg.h |
Documents firmware telemetry registers. |
src/include/ipc4/gateway.h |
Documents gateway addressing and attributes. |
src/include/ipc4/handler.h |
Documents IPC4 handlers. |
src/include/ipc4/header.h |
Documents message envelopes. |
src/include/ipc4/kpb.h |
Documents KPB configuration. |
src/include/ipc4/logging.h |
Documents logging APIs. |
src/include/ipc4/module.h |
Documents module lifecycle commands. |
src/include/ipc4/notification.h |
Documents notifications and events. |
src/include/ipc4/pipeline.h |
Documents pipeline lifecycle commands. |
src/include/ipc4/probe.h |
Documents probe interfaces. |
src/include/ipc4/ssp.h |
Documents SSP/I2S configuration. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…mbers In Doxygen syntax, '/**< ... */' documents the preceding (prior) code element, while '/** ... */' documents the subsequent (following) element. Several enums and bitfield structs used '/**<' on lines placed *before* their target identifier, causing Doxygen to shift all docstrings by one element (e.g. SOF_IPC4_GLB_CREATE_PIPELINE received the description of SOF_IPC4_GLB_DELETE_PIPELINE). Convert all preceding comments to standard '/**' blocks across IPC4 headers, and standardize bitfield comments to trailing '/**<' where appropriate. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
PR 11302: test resultsRun date: 2026-10-13 19:45 UTC Tested commit: 5f6a4953d579294af0002cfea20252f4c32e28eb
|
… sample types Address Copilot review feedback on PR thesofproject#11302: 1. Clarify core_id range is platform-dependent (0..CONFIG_CORE_COUNT - 1). 2. Correct SOF_IPC4_GLB_NOTIFICATION opcode comment to 27 (was 23). 3. Update notification function return contracts to reflect that true indicates dispatched or suppressed by notification mask, and false indicates notification pool exhaustion requiring caller retry. 4. Clarify probe_point stream_tag contract for extraction vs injection. 5. Fix repeated "Serial Serial" typos in ipc4_ssp_config to Synchronous Serial Port with standard register mnemonics (SSCR0, etc.). 6. Clarify sample_type MSB_INTEGER and LSB_INTEGER describe bit alignment within container, not byte endianness. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
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.
Summary
Comprehensive audit and upgrade of Doxygen documentation across the IPC4 host-DSP protocol subsystem headers. This PR structures IPC4 documentation into 8 dedicated subgroups under
ipc4_api, resolves all documentation gaps, and documents message envelopes, data formats, module lifecycle, pipelines, base firmware, hardware gateways, asynchronous notifications, and telemetry.Key Changes
Subgroup Taxonomy:
ipc4_envelope_api: 64-bit message envelope, Primary & Extension DWORD bitfields, opcodes, status codes, handler routing.ipc4_format_api: Audio formats, sample depths, channel configurations, dynamic pin descriptors, small/large parameters.ipc4_module_api: Module lifecycle, dynamic binding, small/large parameter configuration handshake.ipc4_pipeline_api: Pipeline priorities, creation/deletion, state transitions, reverse order drain, context size queries, DMA chaining.ipc4_base_fw_api: Core 0 Base FW parameters, ADSP properties, hardware configs, memory state, power manager A-states, system time.ipc4_gateway_api: Gateway addressing (connector node IDs), HDA, ALH/SoundWire multi-gateway aggregation, DMIC, SSP/I2S.ipc4_notification_api: Unsolicited DSP-to-host events, underrun/overrun alarms, voice detection, Mailbox Window 0 firmware status registers.ipc4_telemetry_probe_api: Host DMA trace logging, audio probe injection/extraction points, module-specific telemetry configs.Strict Verification:
/** ... */,/**< ... */) and documentation tags. No struct definitions, bitfield widths, types, or function signatures were altered.ninja -C build_doxygen docbuilds cleanly with 0 warnings and 0 errors.