doc: ipc4: comprehensive audit and upgrade of IPC4 protocol Doxygen documentation

doc/groups.dox

@@ -15,6 +15,54 @@
  * @brief Intel and AMD IPC4 protocol definitions, message structures, base firmware, gateways, and notifications.
  */
 
+/**
+ * @defgroup ipc4_envelope_api IPC4 Message Envelope & Dispatch
+ * @ingroup ipc4_api
+ * @brief 64-bit mailbox message envelope formats, primary/extension registers, command target routing, reply status, and compound message barriers.
+ */
+
+/**
+ * @defgroup ipc4_base_fw_api IPC4 Base Firmware & Global Configuration
+ * @ingroup ipc4_api
+ * @brief Core 0 Base Firmware management, ADSP global properties, hardware capabilities, memory pools, power budget tables, and crash dump telemetry.
+ */
+
+/**
+ * @defgroup ipc4_pipeline_api IPC4 Pipeline Lifecycle & State Machine
+ * @ingroup ipc4_api
+ * @brief Pipeline creation, priority assignments, state machine transitions (RESET, PAUSED, RUNNING, EOS), multi-pipeline synchronization, and save/restore.
+ */
+
+/**
+ * @defgroup ipc4_module_api IPC4 Module Architecture & Dynamic Binding
+ * @ingroup ipc4_api
+ * @brief Module instantiation, dynamic queue/pin binding, small/large parameter configuration handshake, and module power transitions.
+ */
+
+/**
+ * @defgroup ipc4_format_api IPC4 Audio Formats & Pin Contracts
+ * @ingroup ipc4_api
+ * @brief Audio format specification bitfields, sampling rates, bit depths, channel configurations, and pin format descriptors.
+ */
+
+/**
+ * @defgroup ipc4_gateway_api IPC4 Hardware Audio Gateways
+ * @ingroup ipc4_api
+ * @brief Audio gateway addressing (HD-Audio host/link, SoundWire ALH aggregation, DMIC link, SSP/I2S), gateway attributes, and NHLT configuration blobs.
+ */
+
+/**
+ * @defgroup ipc4_notification_api IPC4 Asynchronous Notifications & Telemetry Registers
+ * @ingroup ipc4_api
+ * @brief Unsolicited DSP-to-host notifications, resource event reports, keyword detection events, watchdog alerts, and Mailbox Window 0 status registers.
+ */
+
+/**
+ * @defgroup ipc4_telemetry_probe_api IPC4 Telemetry, Logging & Audio Probes
+ * @ingroup ipc4_api
+ * @brief Host DMA trace logging control, audio probe injection and extraction data streams, and module-specific configuration payloads.
+ */
+
 /**
  * @defgroup ipc3_api IPC3 Host-DSP Protocol
  * @brief Legacy IPC3 protocol definitions, commands, and stream controls.

doc/mainpage.dox

@@ -44,17 +44,22 @@
  * </tr>
  * <tr>
  *   <td><b>Host-DSP IPC4 Protocol</b></td>
- *   <td>@ref ipc4_api</td>
  *   <td>
- *     - @ref src/include/ipc4/base_fw.h "ipc4/base_fw.h"<br/>
+ *     @ref ipc4_api<br/>
+ *     <small>(@ref ipc4_envelope_api, @ref ipc4_pipeline_api, @ref ipc4_module_api, @ref ipc4_format_api, @ref ipc4_gateway_api, @ref ipc4_base_fw_api, @ref ipc4_notification_api, @ref ipc4_telemetry_probe_api)</small>
+ *   </td>
+ *   <td>
  *     - @ref src/include/ipc4/header.h "ipc4/header.h"<br/>
- *     - @ref src/include/ipc4/gateway.h "ipc4/gateway.h"<br/>
  *     - @ref src/include/ipc4/pipeline.h "ipc4/pipeline.h"<br/>
+ *     - @ref src/include/ipc4/module.h "ipc4/module.h"<br/>
+ *     - @ref src/include/ipc4/gateway.h "ipc4/gateway.h"<br/>
+ *     - @ref src/include/ipc4/base_fw.h "ipc4/base_fw.h"<br/>
  *     - @ref src/include/ipc4/notification.h "ipc4/notification.h"
  *   </td>
  *   <td>
- *     Modern Intel/AMD IPC4 messaging protocol: base firmware configuration, gateway management,
- *     pipeline creation and state transitions, large parameter get/set, and asynchronous notifications.
+ *     Modern Intel/AMD IPC4 messaging protocol: 64-bit mailbox envelope, base firmware configuration,
+ *     dynamic module instantiation & binding, pipeline lifecycle state machines, hardware audio gateways,
+ *     large parameter get/set fragmentation handshake, and asynchronous event notifications.
  *   </td>
  * </tr>
  * <tr>

src/include/ipc4/aec.h

@@ -17,7 +17,8 @@
 
 /**
  * \file include/ipc4/aec.h
- * \brief IPC4 global aec definitions.
+ * \brief Acoustic Echo Cancellation (AEC) module configuration and parameter definitions.
+ * \ingroup ipc4_telemetry_probe_api
  * NOTE: This ABI uses bit fields and is non portable.
  */
 
@@ -27,15 +28,23 @@
 #include <stdint.h>
 #include <ipc4/base-config.h>
 
+/**
+ * \brief AEC module configuration payload.
+ * \ingroup ipc4_telemetry_probe_api
+ */
 struct sof_ipc4_aec_config {
-	struct ipc4_base_module_cfg base_cfg;
-	struct ipc4_audio_format reference_fmt;
-	struct ipc4_audio_format output_fmt;
-	uint32_t cpc_low_power_mode;
+	struct ipc4_base_module_cfg base_cfg;       /**< Standard base module configuration. */
+	struct ipc4_audio_format reference_fmt;    /**< Echo reference audio format. */
+	struct ipc4_audio_format output_fmt;       /**< Echo-cancelled microphone output format. */
+	uint32_t cpc_low_power_mode;                /**< Low-power mode Cycles Per Chunk compute budget. */
 };
 
+/**
+ * \brief Parameter IDs for AEC module LargeConfigSet/Get.
+ * \ingroup ipc4_telemetry_probe_api
+ */
 enum sof_ipc4_aec_config_params {
-	IPC4_AEC_SET_EXT_FMT,
+	IPC4_AEC_SET_EXT_FMT, /**< Configure extended reference and output formats. */
 };
 
 #endif

src/include/ipc4/alh.h

@@ -17,7 +17,8 @@
 
 /**
  * \file include/ipc4/alh.h
- * \brief IPC4 global definitions.
+ * \brief IPC4 Audio Hub Link (ALH) and SoundWire multi-gateway definitions.
+ * \ingroup ipc4_gateway_api
  * NOTE: This ABI uses bit fields and is non portable.
  */
 
@@ -29,62 +30,79 @@
 #include <stddef.h>
 #include <ipc4/gateway.h>
 
+/** \brief Maximum number of single ALH channels supported in multi-gateway aggregation. */
 #define IPC4_ALH_MAX_NUMBER_OF_GTW 16
 #ifdef CONFIG_DMA_INTEL_ADSP_GPDMA
+/** \brief DAI index offset for GPDMA platforms. */
 #define IPC4_ALH_DAI_INDEX_OFFSET 7
 #else
+/** \brief DAI index offset for non-GPDMA platforms. */
 #define IPC4_ALH_DAI_INDEX_OFFSET 0
 #endif
 
 #if defined(CONFIG_SOC_SERIES_INTEL_ADSP_CAVS) || \
 	defined(CONFIG_SOC_ACE15_MTPM)
+/** \brief Number of bidirectional ALH links on CAVS/ACE1.5. */
 #define IPC4_DAI_NUM_ALH_BI_DIR_LINKS	16
+/** \brief Number of bidirectional ALH link groups. */
 #define IPC4_DAI_NUM_ALH_BI_DIR_LINKS_GROUP	4
 #else
+/** \brief Number of bidirectional ALH links on non-CAVS platforms. */
 #define IPC4_DAI_NUM_ALH_BI_DIR_LINKS	0
+/** \brief Number of bidirectional ALH link groups on non-CAVS platforms. */
 #define IPC4_DAI_NUM_ALH_BI_DIR_LINKS_GROUP	0
 #endif
 
-/* copier id = (group id << 4) + codec id + IPC4_ALH_DAI_INDEX_OFFSET
+/**
+ * \brief Compute ALH DAI index from group and codec identifiers.
+ *
+ * copier id = (group id << 4) + codec id + IPC4_ALH_DAI_INDEX_OFFSET
  * dai_index = (group id << 8) + codec id;
  */
 #define IPC4_ALH_DAI_INDEX(x) ((((x) & 0xF0) << IPC4_DAI_NUM_ALH_BI_DIR_LINKS_GROUP) + \
 				(((x) & 0xF) - IPC4_ALH_DAI_INDEX_OFFSET))
 
-/* Multi-gateways addressing starts from IPC4_ALH_MULTI_GTW_BASE */
+/** \brief Base virtual index marking the beginning of aggregated multi-gateway addressing. */
 #define IPC4_ALH_MULTI_GTW_BASE 0x50
 
 /**
- * @brief Check if an IPC4 connector node ID corresponds to an aggregated multi-gateway.
- * @param node_id Gateway connector node ID.
- * @return True if the node represents an aggregated multi-gateway, false otherwise.
+ * \brief Check if an IPC4 connector node ID corresponds to an aggregated multi-gateway.
+ * \ingroup ipc4_gateway_api
+ * \param node_id Gateway connector node ID.
+ * \return True if the node represents an aggregated multi-gateway, false otherwise.
  */
 static inline bool is_multi_gateway(const union ipc4_connector_node_id node_id)
 {
 	return node_id.f.v_index >= IPC4_ALH_MULTI_GTW_BASE;
 }
 
+/**
+ * \brief Multi-gateway channel aggregation configuration.
+ * \ingroup ipc4_gateway_api
+ */
 struct ipc4_alh_multi_gtw_cfg {
-	/* Number of single channels (valid items in mapping array). */
-	uint32_t count;
-	/* Single to multi aggregation mapping item. */
+	uint32_t count; /**< Number of single channels in mapping array. */
+	/** Single-to-multi aggregation mapping table. */
 	struct {
-		/* Vindex of a single ALH channel aggregated. */
-		uint32_t alh_id;
-		/* Channel mask */
-		uint32_t channel_mask;
-	} mapping[IPC4_ALH_MAX_NUMBER_OF_GTW]; /* < Mapping items */
+		uint32_t alh_id;       /**< Virtual index (v_index) of single ALH channel. */
+		uint32_t channel_mask; /**< Bitmask of audio channels mapped to this ALH endpoint. */
+	} mapping[IPC4_ALH_MAX_NUMBER_OF_GTW]; /**< Array of mapping items. */
 } __attribute__((packed, aligned(4)));
 
+/**
+ * \brief Full configuration blob for Audio Hub Link (ALH) gateways.
+ * \ingroup ipc4_gateway_api
+ */
 struct sof_alh_configuration_blob {
-	union ipc4_gateway_attributes gtw_attributes;
-	struct ipc4_alh_multi_gtw_cfg alh_cfg;
+	union ipc4_gateway_attributes gtw_attributes; /**< Gateway memory placement attributes. */
+	struct ipc4_alh_multi_gtw_cfg alh_cfg;        /**< Multi-gateway channel aggregation mappings. */
 } __attribute__((packed, aligned(4)));
 
 /**
- * @brief Calculate the serialized size of an ALH configuration blob.
- * @param alh_blob Pointer to the ALH configuration structure.
- * @return Size in bytes of the configuration blob.
+ * \brief Calculate the serialized size of an ALH configuration blob.
+ * \ingroup ipc4_gateway_api
+ * \param alh_blob Pointer to the ALH configuration structure.
+ * \return Size in bytes of the configuration blob.
  */
 static inline size_t
 get_alh_config_size(const struct sof_alh_configuration_blob *alh_blob)

src/include/ipc4/ams_helpers.h

@@ -5,6 +5,12 @@
  * Author: Ievgen Ganakov <ievgen.ganakov@intel.com>
  */
 
+/**
+ * \file include/ipc4/ams_helpers.h
+ * \brief Audio Management System (AMS) message producer and consumer helpers.
+ * \ingroup ipc4_envelope_api
+ */
+
 #ifndef __SOF_LIB_AMS_HELPERS_H__
 #define __SOF_LIB_AMS_HELPERS_H__
 
@@ -14,22 +20,63 @@
 
 #if CONFIG_AMS
 
+/**
+ * \brief Register a component device as an AMS message producer.
+ * \ingroup ipc4_envelope_api
+ * @param[in] dev Pointer to the component device.
+ * @param[out] ams_uuid_id Receives the allocated AMS UUID registration identifier.
+ * @param[in] msg_uuid 16-byte UUID of the message type.
+ * @return 0 on success, or negative error code on registration failure.
+ */
 int ams_helper_register_producer(const struct comp_dev *dev,
 				 uint32_t *ams_uuid_id,
 				 const uint8_t *msg_uuid);
 
+/**
+ * \brief Unregister a component device as an AMS message producer.
+ * \ingroup ipc4_envelope_api
+ * @param[in] dev Pointer to the component device.
+ * @param[in] ams_uuid_id AMS UUID identifier previously allocated by registration.
+ * @return 0 on success, or negative error code on failure.
+ */
 int ams_helper_unregister_producer(const struct comp_dev *dev,
 				   uint32_t ams_uuid_id);
 
+/**
+ * \brief Register a component device as an AMS message consumer with a receive callback.
+ * \ingroup ipc4_envelope_api
+ * @param[in] dev Pointer to the component device.
+ * @param[out] ams_uuid_id Receives the allocated AMS UUID registration identifier.
+ * @param[in] msg_uuid 16-byte UUID of the message type to subscribe to.
+ * @param[in] callback Function pointer invoked when a matching AMS message arrives.
+ * @return 0 on success, or negative error code on registration failure.
+ */
 int ams_helper_register_consumer(struct comp_dev *dev,
 				 uint32_t *ams_uuid_id,
 				 const uint8_t *msg_uuid,
 				 ams_msg_callback_fn callback);
 
+/**
+ * \brief Unregister a component device as an AMS message consumer.
+ * \ingroup ipc4_envelope_api
+ * @param[in] dev Pointer to the component device.
+ * @param[in] ams_uuid_id AMS UUID registration identifier.
+ * @param[in] callback Callback function pointer to remove.
+ * @return 0 on success, or negative error code on failure.
+ */
 int ams_helper_unregister_consumer(struct comp_dev *dev,
 				   uint32_t ams_uuid_id,
 				   ams_msg_callback_fn callback);
 
+/**
+ * \brief Format and prepare an AMS message payload for transmission.
+ * \ingroup ipc4_envelope_api
+ * @param[in] dev Pointer to the originator component device.
+ * @param[out] payload Pointer to the AMS message payload structure to initialize.
+ * @param[in] ams_uuid_id Originator AMS UUID registration identifier.
+ * @param[in] message Raw message buffer pointer.
+ * @param[in] message_size Size of the message buffer in bytes.
+ */
 void ams_helper_prepare_payload(const struct comp_dev *dev,
 				struct ams_message_payload *payload,
 				uint32_t ams_uuid_id,

src/include/ipc4/base-config.h

@@ -17,7 +17,8 @@
 
 /**
  * \file include/ipc4/base-config.h
- * \brief IPC4 global definitions.
+ * \brief Firmware internal stream parameter and buffer format bridge routines for IPC4.
+ * \ingroup ipc4_format_api
  * NOTE: This ABI uses bit fields and is non portable.
  */
 
@@ -28,17 +29,55 @@
 #include <module/ipc4/base-config.h>
 
 struct sof_ipc_stream_params;
+
+/**
+ * \brief Convert an IPC4 base module configuration structure to internal SOF stream parameters.
+ * \ingroup ipc4_format_api
+ * @param[in] base_cfg Pointer to the IPC4 base module configuration.
+ * @param[out] params Destination SOF stream parameters structure to populate.
+ */
 void ipc4_base_module_cfg_to_stream_params(const struct ipc4_base_module_cfg *base_cfg,
 					   struct sof_ipc_stream_params *params);
+
+/**
+ * \brief Convert an IPC4 audio format descriptor to internal SOF stream parameters.
+ * \ingroup ipc4_format_api
+ * @param[in] audio_fmt Pointer to the IPC4 audio format structure.
+ * @param[out] params Destination SOF stream parameters structure to populate.
+ */
 void ipc4_audio_format_to_stream_params(const struct ipc4_audio_format *audio_fmt,
 					struct sof_ipc_stream_params *params);
+
 struct comp_buffer;
+
+/**
+ * \brief Apply an IPC4 audio format configuration to an intermediate component buffer.
+ * \ingroup ipc4_format_api
+ * @param[in,out] buf_c Component buffer whose stream format will be updated.
+ * @param[in] fmt IPC4 audio format specification to apply.
+ */
 void ipc4_update_buffer_format(struct comp_buffer *buf_c,
 			       const struct ipc4_audio_format *fmt);
+
 struct sof_source;
+
+/**
+ * \brief Apply an IPC4 audio format configuration to an audio streaming source endpoint.
+ * \ingroup ipc4_format_api
+ * @param[in,out] source Audio source interface to configure.
+ * @param[in] fmt IPC4 audio format specification to apply.
+ */
 void ipc4_update_source_format(struct sof_source *source,
 			       const struct ipc4_audio_format *fmt);
+
 struct sof_sink;
+
+/**
+ * \brief Apply an IPC4 audio format configuration to an audio streaming sink endpoint.
+ * \ingroup ipc4_format_api
+ * @param[in,out] sink Audio sink interface to configure.
+ * @param[in] fmt IPC4 audio format specification to apply.
+ */
 void ipc4_update_sink_format(struct sof_sink *sink,
 			     const struct ipc4_audio_format *fmt);