From a2ce3ea12d96900b3d35ecb1c16f64b5db4888e6 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 13 Oct 2026 16:03:11 +0100 Subject: [PATCH 1/9] doc: ipc4: define protocol subgroups and document message envelope and 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 --- doc/groups.dox | 48 +++++++++ doc/mainpage.dox | 15 ++- src/include/ipc4/ams_helpers.h | 47 +++++++++ src/include/ipc4/error_status.h | 11 ++- src/include/ipc4/handler.h | 91 ++++++++++------- src/include/ipc4/header.h | 170 +++++++++++++++++++------------- 6 files changed, 274 insertions(+), 108 deletions(-) diff --git a/doc/groups.dox b/doc/groups.dox index 0a19d0abdbf8..509bfba5bafc 100644 --- a/doc/groups.dox +++ b/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. diff --git a/doc/mainpage.dox b/doc/mainpage.dox index e3cec54263aa..7352ec16ae61 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -44,17 +44,22 @@ * * * Host-DSP IPC4 Protocol - * @ref ipc4_api * - * - @ref src/include/ipc4/base_fw.h "ipc4/base_fw.h"
+ * @ref ipc4_api
+ * (@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) + * + * * - @ref src/include/ipc4/header.h "ipc4/header.h"
- * - @ref src/include/ipc4/gateway.h "ipc4/gateway.h"
* - @ref src/include/ipc4/pipeline.h "ipc4/pipeline.h"
+ * - @ref src/include/ipc4/module.h "ipc4/module.h"
+ * - @ref src/include/ipc4/gateway.h "ipc4/gateway.h"
+ * - @ref src/include/ipc4/base_fw.h "ipc4/base_fw.h"
* - @ref src/include/ipc4/notification.h "ipc4/notification.h" * * - * 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. * * * diff --git a/src/include/ipc4/ams_helpers.h b/src/include/ipc4/ams_helpers.h index 35c9557a733b..e0fa3c83a76d 100644 --- a/src/include/ipc4/ams_helpers.h +++ b/src/include/ipc4/ams_helpers.h @@ -5,6 +5,12 @@ * Author: Ievgen Ganakov */ +/** + * \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, diff --git a/src/include/ipc4/error_status.h b/src/include/ipc4/error_status.h index 4d65b5596710..679d9a425196 100644 --- a/src/include/ipc4/error_status.h +++ b/src/include/ipc4/error_status.h @@ -14,15 +14,24 @@ /** * \file include/ipc4/error_status.h * \brief IPC4 status codes, error codes, and IXC return values. - * \ingroup ipc4_api + * \ingroup ipc4_envelope_api * NOTE: This ABI uses bit fields and is non portable. */ #ifndef __SOF_IPC4_ERROR_STATUS_H__ #define __SOF_IPC4_ERROR_STATUS_H__ +/**< Number of bits allocated for processing status in the Primary reply DWORD (24 bits). */ #define IPC4_IXC_STATUS_BITS 24 +/** + * \brief IPC4 host-DSP status and error codes. + * \ingroup ipc4_envelope_api + * + * Returned in the lower 24 bits of the Primary reply DWORD (ipc4_message_reply::primary::r::status). + * Standard status codes are common across global and module commands, while values >= 100 + * convey subsystem-specific failures (module management, probes, gateways, and clocking). + */ enum ipc4_status { /**< The operation was successful */ IPC4_SUCCESS = 0, diff --git a/src/include/ipc4/handler.h b/src/include/ipc4/handler.h index 104f12fcaacc..3335c108fa29 100644 --- a/src/include/ipc4/handler.h +++ b/src/include/ipc4/handler.h @@ -3,100 +3,119 @@ * Copyright(c) 2026 Intel Corporation. */ +/** + * \file include/ipc4/handler.h + * \brief IPC4 message handlers, userspace bridge, and compound message synchronization. + * \ingroup ipc4_envelope_api + */ + #ifndef __SOF_IPC4_HANDLER_H__ #define __SOF_IPC4_HANDLER_H__ struct ipc4_message_request; /** - * \brief Processes IPC4 userspace module message. - * @param[in] ipc4 IPC4 message request. - * @param[in] reply IPC message reply structure. - * @return IPC4_SUCCESS on success, error code otherwise. + * \brief Processes an IPC4 userspace module message. + * \ingroup ipc4_envelope_api + * @param[in] ipc4 IPC4 message request structure. + * @param[in,out] reply IPC message reply structure populated upon return. + * @return IPC4_SUCCESS (0) on success, or negative/IPC4 status code on failure. */ int ipc4_user_process_module_message(struct ipc4_message_request *ipc4, struct ipc_msg *reply); /** - * \brief Load a dynamically loadable module. - * @param[in] drv Component driver. - * @param[in] mi SOF_IPC4_MOD_INIT_INSTANCE data + * \brief Load a dynamically loadable module instance into userspace memory. + * \ingroup ipc4_envelope_api + * @param[in] drv Component driver operations structure. + * @param[in] mi IPC4 module initialization parameters (SOF_IPC4_MOD_INIT_INSTANCE). + * @return 0 on success, or negative error code on allocation/loading failure. */ int ipc4_user_module_load(const struct comp_driver *drv, const struct ipc4_module_init_instance *mi); /** - * @brief Process MOD_CONFIG_GET or MOD_CONFIG_SET in any execution context. - * @param[in] ipc4 IPC4 message request. - * @param[in] set true for CONFIG_SET, false for CONFIG_GET. - * @param[out] reply_ext Receives extension value for CONFIG_GET (may be NULL). - * @return IPC4 status code (0 on success). + * \brief Process MOD_CONFIG_GET or MOD_CONFIG_SET in any execution context. + * \ingroup ipc4_envelope_api + * @param[in] ipc4 IPC4 message request structure. + * @param[in] set True for MOD_CONFIG_SET, false for MOD_CONFIG_GET. + * @param[out] reply_ext Receives extension DWORD value for CONFIG_GET (may be NULL). + * @return IPC4 status code (IPC4_SUCCESS on success). */ int ipc4_process_module_config(struct ipc4_message_request *ipc4, bool set, uint32_t *reply_ext); /** - * @brief Process MOD_LARGE_CONFIG_SET in any execution context. - * @param[in] ipc4 IPC4 message request. - * @return IPC4 status code (0 on success). + * \brief Process MOD_LARGE_CONFIG_SET in any execution context. + * \ingroup ipc4_envelope_api + * @param[in] ipc4 IPC4 message request structure containing block parameters and offset. + * @return IPC4 status code (IPC4_SUCCESS on success). */ int ipc4_process_large_config_set(struct ipc4_message_request *ipc4); /** - * \brief Processes IPC4 userspace global message. - * @param[in] ipc4 IPC4 message request. - * @param[in] reply IPC message reply structure. + * \brief Processes an IPC4 userspace global firmware message. + * \ingroup ipc4_envelope_api + * @param[in] ipc4 IPC4 message request structure. + * @param[in,out] reply IPC message reply structure. * @return IPC4_SUCCESS on success, error code otherwise. */ int ipc4_user_process_glb_message(struct ipc4_message_request *ipc4, struct ipc_msg *reply); /** * \brief Process SET_PIPELINE_STATE IPC4 message (prepare + trigger phases). - * @param[in] ipc4 IPC4 message request. - * @return 0 on success, IPC4 error code otherwise. + * \ingroup ipc4_envelope_api + * @param[in] ipc4 IPC4 message request structure containing target state and pipeline ID. + * @return 0 on success, or IPC4 error code on failure. */ int ipc4_set_pipeline_state(struct ipc4_message_request *ipc4); /** - * \brief Complete the IPC compound message. - * @param[in] msg_id IPC message ID. - * @param[in] error Error code of the IPC command. + * \brief Complete an IPC compound message transaction and signal waiting threads. + * \ingroup ipc4_envelope_api + * @param[in] msg_id Compound IPC message transaction identifier. + * @param[in] error Overall error code of the compound transaction. */ void ipc_compound_msg_done(uint32_t msg_id, int error); /** - * \brief Connect components together on a pipeline. - * @param ipc The global IPC context. - * @param bu IPC4 bind-unbind data. - * @return IPC4_SUCCESS on success, error code otherwise. + * \brief Connect components together on a pipeline graph. + * \ingroup ipc4_envelope_api + * @param[in] ipc The global IPC context pointer. + * @param[in] bu IPC4 bind-unbind configuration data. + * @return IPC4_SUCCESS on success, or IPC4 error code otherwise. */ int ipc4_comp_connect(struct ipc *ipc, const struct ipc4_module_bind_unbind *bu); /** - * \brief Disconnect components in a pipeline. - * @param ipc The global IPC context. - * @param bu IPC4 bind-unbind data. - * @return IPC4_SUCCESS on success, error code otherwise. + * \brief Disconnect components in a pipeline graph. + * \ingroup ipc4_envelope_api + * @param[in] ipc The global IPC context pointer. + * @param[in] bu IPC4 bind-unbind configuration data. + * @return IPC4_SUCCESS on success, or IPC4 error code otherwise. */ int ipc4_comp_disconnect(struct ipc *ipc, const struct ipc4_module_bind_unbind *bu); #if defined(__ZEPHYR__) && defined(CONFIG_SOF_FULL_ZEPHYR_APPLICATION) /** - * \brief Increment the IPC compound message pre-start counter. + * \brief Increment the IPC compound message pre-start barrier counter. + * \ingroup ipc4_envelope_api * @param[in] msg_id IPC message ID. */ __syscall void ipc_compound_pre_start(int msg_id); /** - * \brief Decrement the IPC compound message pre-start counter on return value status. + * \brief Decrement the IPC compound message pre-start barrier counter on return. + * \ingroup ipc4_envelope_api * @param[in] msg_id IPC message ID. * @param[in] ret Return value of the IPC command. - * @param[in] delayed True if the reply is delayed. + * @param[in] delayed True if the reply is deferred/asynchronous. */ __syscall void ipc_compound_post_start(uint32_t msg_id, int ret, bool delayed); /** - * \brief Wait for the IPC compound message to complete. - * @return 0 on success, error code otherwise on timeout. + * \brief Wait for active IPC compound message operations to complete. + * \ingroup ipc4_envelope_api + * @return 0 on success, or negative error code on timeout. */ __syscall int ipc_wait_for_compound_msg(void); diff --git a/src/include/ipc4/header.h b/src/include/ipc4/header.h index ade286f2b031..23682f0d8e13 100644 --- a/src/include/ipc4/header.h +++ b/src/include/ipc4/header.h @@ -18,7 +18,7 @@ /** * \file include/ipc4/header.h * \brief IPC4 global message headers, envelope formats, and command types. - * \ingroup ipc4_api + * \ingroup ipc4_envelope_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -27,183 +27,221 @@ #include +/** Cast a generic buffer or message pointer to an IPC4 message request structure. */ #define ipc_from_hdr(x) ((struct ipc4_message_request *)x) -/**< Message target, value of msg_tgt field. */ +/** + * \brief Message target routing selector (msg_tgt bitfield in Primary DWORD). + * \ingroup ipc4_envelope_api + */ enum ipc4_message_target { - /**< Global FW message */ + /**< Global firmware message (dispatched to Base FW or global handler). */ SOF_IPC4_MESSAGE_TARGET_FW_GEN_MSG = 0, - /**< Module message */ + /**< Module-specific message (routed directly to module instance by module_id). */ SOF_IPC4_MESSAGE_TARGET_MODULE_MSG = 1 }; -/**< Message direction, value of rsp field. */ +/** + * \brief Message direction indicator (rsp bitfield in Primary DWORD). + * \ingroup ipc4_envelope_api + */ enum ipc4_message_direction { - /**< Request, Notification */ + /**< Host-to-DSP command request, or unsolicited DSP-to-host notification. */ SOF_IPC4_MESSAGE_DIR_MSG_REQUEST = 0, - /**< Reply */ + /**< Command completion response / reply. */ SOF_IPC4_MESSAGE_DIR_MSG_REPLY = 1, }; -/* - * Global IPC4 message types - must fit into 5 bits. +/** + * \brief Global IPC4 message types (5-bit opcode in Primary DWORD when msg_tgt == FW_GEN_MSG). + * \ingroup ipc4_envelope_api */ enum ipc4_message_type { - /**< Boot Config. */ + /**< Boot configuration handshake. */ SOF_IPC4_GLB_BOOT_CONFIG = 0, - /**< ROM Control (directed to ROM). */ + /**< ROM control command (directed to ADSP ROM bootloader). */ SOF_IPC4_GLB_ROM_CONTROL = 1, - /**< Execute IPC gateway command */ + /**< Execute IPC gateway command. */ SOF_IPC4_GLB_IPCGATEWAY_CMD = 2, /* GAP HERE- DO NOT USE - size 10 (3 .. 12) */ - /**< Execute performance measurements command. */ + /**< Execute performance measurement command. */ SOF_IPC4_GLB_PERF_MEASUREMENTS_CMD = 13, - /**< DMA Chain command. */ + /**< DMA chain setup and configuration command. */ SOF_IPC4_GLB_CHAIN_DMA = 14, - /**< Load multiple modules */ + /**< Load multiple module binary images. */ SOF_IPC4_GLB_LOAD_MULTIPLE_MODULES = 15, - /**< Unload multiple modules */ + /**< Unload multiple module binary images. */ SOF_IPC4_GLB_UNLOAD_MULTIPLE_MODULES = 16, - /**< Create pipeline */ + /**< Create pipeline with specified ID, priority, and memory attributes. */ SOF_IPC4_GLB_CREATE_PIPELINE = 17, - /**< Delete pipeline */ + /**< Delete pipeline and associated module graph. */ SOF_IPC4_GLB_DELETE_PIPELINE = 18, - /**< Set pipeline state */ + /**< Transition pipeline state (RESET, PAUSED, RUNNING, EOS). */ SOF_IPC4_GLB_SET_PIPELINE_STATE = 19, - /**< Get pipeline state */ + /**< Retrieve current pipeline state. */ SOF_IPC4_GLB_GET_PIPELINE_STATE = 20, - /**< Get pipeline context size */ + /**< Query pipeline context memory size. */ SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE = 21, - /**< Save pipeline */ + /**< Save pipeline context to host memory before power gating. */ SOF_IPC4_GLB_SAVE_PIPELINE = 22, - /**< Restore pipeline */ + /**< Restore pipeline context from host memory after wake. */ SOF_IPC4_GLB_RESTORE_PIPELINE = 23, - /**< Loads library */ + /**< Load dynamic library via HD-Audio DMA. */ SOF_IPC4_GLB_LOAD_LIBRARY = 24, - /**< Loads library prepare */ + /**< Prepare for dynamic library loading. */ SOF_IPC4_GLB_LOAD_LIBRARY_PREPARE = 25, - /**< Internal FW message */ + /**< Internal firmware control message. */ SOF_IPC4_GLB_INTERNAL_MESSAGE = 26, - /**< Notification (FW to SW driver) */ + /**< Asynchronous notification event from DSP to host driver. */ SOF_IPC4_GLB_NOTIFICATION = 27, /* GAP HERE- DO NOT USE - size 3 (28 .. 30) */ - /**< Enter GDB stub to wait for commands in memory window */ + /**< Enter GDB debugging stub to wait for host debugger in memory window. */ SOF_IPC4_GLB_ENTER_GDB = 31, - /**< Maximum message number */ + /**< Maximum supported global message opcode count. */ SOF_IPC4_GLB_MAX_IXC_MESSAGE_TYPE = 32 }; /** - * \brief Generic message header. IPC MAJOR 4 version. - * All IPC4 messages use this header as abstraction - * to platform specific calls. + * \brief Generic raw 64-bit IPC4 message header registers. + * \ingroup ipc4_envelope_api + * + * All IPC4 messages are passed across the mailbox as a pair of 32-bit registers + * (Primary DWORD + Extension DWORD). */ struct ipc_cmd_hdr { - uint32_t pri; - uint32_t ext; + uint32_t pri; /**< Primary 32-bit register value. */ + uint32_t ext; /**< Extension 32-bit register value. */ }; /** - * \brief IPC MAJOR 4 message header. All IPC4 messages use this header. - * When msg_tgt is SOF_IPC4_MESSAGE_TARGET_FW_GEN_MSG then type is - * enum ipc4_message_type. + * \brief Standard 64-bit IPC4 message request envelope. + * \ingroup ipc4_envelope_api + * + * Used for all host-to-DSP command requests. When msg_tgt is + * #SOF_IPC4_MESSAGE_TARGET_FW_GEN_MSG, the type field is one of #ipc4_message_type. + * When msg_tgt is #SOF_IPC4_MESSAGE_TARGET_MODULE_MSG, type is one of #sof_ipc4_module_type. */ struct ipc4_message_request { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { + /**< Command-specific payload, pipeline ID, or module/instance identifier. */ uint32_t rsvd0 : 24; - /**< One of Global::Type */ + /**< 5-bit message opcode (enum ipc4_message_type or enum sof_ipc4_module_type). */ uint32_t type : 5; - /**< Msg::MSG_REQUEST */ + /**< Direction: 0 for request/notification (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST). */ uint32_t rsp : 1; - /**< Msg::FW_GEN_MSG */ + /**< Target selector: 0 for global firmware, 1 for module instance. */ uint32_t msg_tgt : 1; + /**< Hardware reserved control bit. */ uint32_t _reserved_0 : 1; } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { + /**< Command-specific extension payload, buffer offsets, or parameter flags. */ uint32_t ext_data : 30; + /**< Hardware reserved control bits. */ uint32_t _reserved_0 : 2; } r; } extension; } __attribute__((packed, aligned(4))); +/** + * \brief Standard 64-bit IPC4 message reply envelope. + * \ingroup ipc4_envelope_api + * + * Written to the mailbox registers by the DSP firmware upon command completion. + * The primary register contains the processing status code in its lower 24 bits. + */ struct ipc4_message_reply { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< Processing status, one of IxcStatus values */ + /**< Command processing status (one of enum ipc4_status). */ uint32_t status : 24; - /**< Type, symmetric to Msg */ + /**< Message type, symmetric to the incoming request. */ uint32_t type : 5; - /**< MSG_REPLY */ + /**< Direction: 1 for reply (SOF_IPC4_MESSAGE_DIR_MSG_REPLY). */ uint32_t rsp : 1; - /**< same as request, one of FW_GEN_MSG, MODULE_MSG */ + /**< Target: symmetric to request (FW_GEN_MSG or MODULE_MSG). */ uint32_t msg_tgt : 1; - /**< Reserved field (HW ctrl bits) */ + /**< Hardware control reserved bit. */ uint32_t _reserved_0 : 1; } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< Reserved field */ + /**< Extension reply data, transfer length, or additional status information. */ uint32_t rsvd1 : 30; - /**< Reserved field (HW ctrl bits) */ + /**< Hardware control reserved bits. */ uint32_t _reserved_2 : 2; } r; } extension; } __attribute((packed, aligned(4))); +/** ALSA/kcontrol switch parameter ID for IPC4 Large Config. */ #define SOF_IPC4_SWITCH_CONTROL_PARAM_ID 200 +/** ALSA/kcontrol enum parameter ID for IPC4 Large Config. */ #define SOF_IPC4_ENUM_CONTROL_PARAM_ID 201 +/** ALSA/kcontrol binary bytes parameter ID for IPC4 Large Config. */ #define SOF_IPC4_BYTES_CONTROL_PARAM_ID 202 +/** Magic event ID prefix for ALSA kcontrol notification events (0xA15A0000). */ #define SOF_IPC4_NOTIFY_MODULE_EVENTID_ALSA_MAGIC_VAL ((uint32_t)0xA15A << 16) +/** Magic event ID prefix for compressed audio stream notifications (0xC0C00000). */ #define SOF_IPC4_NOTIFY_MODULE_EVENTID_COMPR_MAGIC_VAL ((uint32_t)0xC0C0 << 16) -/** Generic channel mapped value data. */ +/** + * \brief Generic per-channel control value mapping. + * \ingroup ipc4_envelope_api + */ struct sof_ipc4_ctrl_value_chan { - uint32_t channel; /**< Channel ID */ - uint32_t value; /**< control value */ + uint32_t channel; /**< Logical audio channel ID (0 = Left, 1 = Right, etc.). */ + uint32_t value; /**< Control integer value (gain level, mute toggle, enum index). */ } __attribute((packed, aligned(4))); -/** IPC payload for kcontrol parameters. */ +/** + * \brief IPC4 payload structure for ALSA kcontrol parameters. + * \ingroup ipc4_envelope_api + */ struct sof_ipc4_control_msg_payload { - uint16_t id; /**< unique id of the control */ - uint16_t num_elems; /**< Number of elements in the chanv array or number of bytes in data */ - uint32_t reserved[4]; /**< reserved for future use, must be set to 0 */ + uint16_t id; /**< Unique identifier of the control. */ + uint16_t num_elems; /**< Number of elements in the chanv array or number of bytes in data. */ + uint32_t reserved[4]; /**< Reserved for future expansion; must be set to 0. */ union { - struct sof_ipc4_ctrl_value_chan chanv[0]; /**< channel ID and value array */ - uint8_t data[0]; /**< binary payload */ + struct sof_ipc4_ctrl_value_chan chanv[0]; /**< Channel ID and value array. */ + uint8_t data[0]; /**< Binary byte payload for raw controls. */ }; } __attribute((packed, aligned(4))); -/** Payload for module notification. */ +/** + * \brief Asynchronous notification payload originating from a module instance. + * \ingroup ipc4_envelope_api + */ struct sof_ipc4_notify_module_data { - uint16_t instance_id; /**< instance ID of the originator module of the notification */ - uint16_t module_id; /**< module ID of the originator of the notification */ - uint32_t event_id; /**< module specific event id */ - uint32_t event_data_size; /**< Size of the event_data (if any) in bytes */ - uint8_t event_data[]; /**< Optional notification data, module and notification dependent */ + uint16_t instance_id; /**< Instance ID of the originator module of the notification. */ + uint16_t module_id; /**< Module ID of the originator of the notification. */ + uint32_t event_id; /**< Module-specific event identifier. */ + uint32_t event_data_size; /**< Size of the event_data payload (if any) in bytes. */ + uint8_t event_data[]; /**< Optional notification data, module and notification dependent. */ } __attribute((packed, aligned(4))); #endif From eeff1c5c5a52efbafb4c28df07e2552fe2286d1c Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 13 Oct 2026 16:04:12 +0100 Subject: [PATCH 2/9] doc: ipc4: document audio formats, sampling rates, bit depths, and pin 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 --- src/include/ipc4/base-config.h | 41 +++- src/include/module/ipc4/base-config.h | 338 +++++++++++++++----------- 2 files changed, 239 insertions(+), 140 deletions(-) diff --git a/src/include/ipc4/base-config.h b/src/include/ipc4/base-config.h index 0c89d534637a..c8125f690657 100644 --- a/src/include/ipc4/base-config.h +++ b/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 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); diff --git a/src/include/module/ipc4/base-config.h b/src/include/module/ipc4/base-config.h index 82a6d552306b..b006ff4dadb8 100644 --- a/src/include/module/ipc4/base-config.h +++ b/src/include/module/ipc4/base-config.h @@ -16,8 +16,9 @@ */ /** - * \file include/ipc4/base-config.h - * \brief IPC4 global definitions. + * \file include/module/ipc4/base-config.h + * \brief IPC4 audio formats, sampling frequencies, bit depths, and pin descriptors. + * \ingroup ipc4_format_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -26,218 +27,277 @@ #include +/** + * \brief Standard PCM and encoded audio sampling frequencies supported by IPC4. + * \ingroup ipc4_format_api + */ enum ipc4_sampling_frequency { - IPC4_FS_8000HZ = 8000, - IPC4_FS_11025HZ = 11025, - IPC4_FS_12000HZ = 12000, /**< Mp3, AAC, SRC only */ - IPC4_FS_16000HZ = 16000, - IPC4_FS_18900HZ = 18900, /**< SRC only for 44100 */ - IPC4_FS_22050HZ = 22050, - IPC4_FS_24000HZ = 24000, /**< Mp3, AAC, SRC only */ - IPC4_FS_32000HZ = 32000, - IPC4_FS_37800HZ = 37800, /**< SRC only for 44100 */ - IPC4_FS_44100HZ = 44100, - IPC4_FS_48000HZ = 48000, /**< Default */ - IPC4_FS_64000HZ = 64000, /**< AAC, SRC only */ - IPC4_FS_88200HZ = 88200, /**< AAC, SRC only */ - IPC4_FS_96000HZ = 96000, /**< AAC, SRC only */ - IPC4_FS_176400HZ = 176400, /**< SRC only */ - IPC4_FS_192000HZ = 192000, /**< SRC only */ - IPC4_FS_INVALID + IPC4_FS_8000HZ = 8000, /**< 8.0 kHz sampling rate. */ + IPC4_FS_11025HZ = 11025, /**< 11.025 kHz sampling rate. */ + IPC4_FS_12000HZ = 12000, /**< 12.0 kHz (MP3, AAC, SRC only). */ + IPC4_FS_16000HZ = 16000, /**< 16.0 kHz sampling rate (standard voice/telephony). */ + IPC4_FS_18900HZ = 18900, /**< 18.9 kHz (SRC only for 44.1 kHz fractional rates). */ + IPC4_FS_22050HZ = 22050, /**< 22.05 kHz sampling rate. */ + IPC4_FS_24000HZ = 24000, /**< 24.0 kHz (MP3, AAC, SRC only). */ + IPC4_FS_32000HZ = 32000, /**< 32.0 kHz sampling rate. */ + IPC4_FS_37800HZ = 37800, /**< 37.8 kHz (SRC only for 44.1 kHz fractional rates). */ + IPC4_FS_44100HZ = 44100, /**< 44.1 kHz CD audio sampling rate. */ + IPC4_FS_48000HZ = 48000, /**< 48.0 kHz standard DSP audio rate (Default). */ + IPC4_FS_64000HZ = 64000, /**< 64.0 kHz (AAC, SRC only). */ + IPC4_FS_88200HZ = 88200, /**< 88.2 kHz high-resolution audio. */ + IPC4_FS_96000HZ = 96000, /**< 96.0 kHz high-resolution audio. */ + IPC4_FS_176400HZ = 176400, /**< 176.4 kHz studio master rate. */ + IPC4_FS_192000HZ = 192000, /**< 192.0 kHz studio master rate. */ + IPC4_FS_INVALID /**< Sentinel for invalid or uninitialized sampling rate. */ }; +/** + * \brief Container bit depth for sample storage in memory. + * \ingroup ipc4_format_api + */ enum ipc4_bit_depth { - IPC4_DEPTH_8BIT = 8, /**< 8 bits depth */ - IPC4_DEPTH_16BIT = 16, /**< 16 bits depth */ - IPC4_DEPTH_24BIT = 24, /**< 24 bits depth - Default */ - IPC4_DEPTH_32BIT = 32, /**< 32 bits depth */ - IPC4_DEPTH_64BIT = 64, /**< 64 bits depth */ - IPC4_DEPTH_INVALID + IPC4_DEPTH_8BIT = 8, /**< 8-bit sample container depth. */ + IPC4_DEPTH_16BIT = 16, /**< 16-bit sample container depth. */ + IPC4_DEPTH_24BIT = 24, /**< 24-bit sample container depth (Default). */ + IPC4_DEPTH_32BIT = 32, /**< 32-bit sample container depth. */ + IPC4_DEPTH_64BIT = 64, /**< 64-bit sample container depth. */ + IPC4_DEPTH_INVALID /**< Sentinel for invalid bit depth. */ }; +/** + * \brief Audio channel configurations and speaker mappings. + * \ingroup ipc4_format_api + */ enum ipc4_channel_config { - IPC4_CHANNEL_CONFIG_MONO = 0, /**< one channel only */ - IPC4_CHANNEL_CONFIG_STEREO = 1, /**< L & R */ - IPC4_CHANNEL_CONFIG_2_POINT_1 = 2, /**< L, R & LFE; PCM only */ - IPC4_CHANNEL_CONFIG_3_POINT_0 = 3, /**< L, C & R; MP3 & AAC only */ - IPC4_CHANNEL_CONFIG_3_POINT_1 = 4, /**< L, C, R & LFE; PCM only */ - IPC4_CHANNEL_CONFIG_QUATRO = 5, /**< L, R, Ls & Rs; PCM only */ - IPC4_CHANNEL_CONFIG_4_POINT_0 = 6, /**< L, C, R & Cs; MP3 & AAC only */ - IPC4_CHANNEL_CONFIG_5_POINT_0 = 7, /**< L, C, R, Ls & Rs */ - IPC4_CHANNEL_CONFIG_5_POINT_1 = 8, /**< L, C, R, Ls, Rs & LFE */ - IPC4_CHANNEL_CONFIG_DUAL_MONO = 9, /**< one channel replicated in two */ - /**< Stereo (L,R) in 4 slots, 1st stream: [ L, R, -, - ] */ - IPC4_CHANNEL_CONFIG_I2S_DUAL_STEREO_0 = 10, - /**< Stereo (L,R) in 4 slots, 2nd stream: [ -, -, L, R ] */ - IPC4_CHANNEL_CONFIG_I2S_DUAL_STEREO_1 = 11, - IPC4_CHANNEL_CONFIG_7_POINT_1 = 12, /**< L, C, R, Ls, Rs & LFE., LS, RS */ - IPC4_CHANNEL_CONFIG_INVALID + IPC4_CHANNEL_CONFIG_MONO = 0, /**< Single mono channel. */ + IPC4_CHANNEL_CONFIG_STEREO = 1, /**< Standard stereo (Left & Right). */ + IPC4_CHANNEL_CONFIG_2_POINT_1 = 2, /**< 2.1 Audio: Left, Right & LFE (PCM only). */ + IPC4_CHANNEL_CONFIG_3_POINT_0 = 3, /**< 3.0 Audio: Left, Center & Right (MP3 & AAC only). */ + IPC4_CHANNEL_CONFIG_3_POINT_1 = 4, /**< 3.1 Audio: Left, Center, Right & LFE (PCM only). */ + IPC4_CHANNEL_CONFIG_QUATRO = 5, /**< 4.0 Surround: Left, Right, Left Surround & Right Surround. */ + IPC4_CHANNEL_CONFIG_4_POINT_0 = 6, /**< 4.0 Cinema: Left, Center, Right & Center Surround. */ + IPC4_CHANNEL_CONFIG_5_POINT_0 = 7, /**< 5.0 Surround: Left, Center, Right, Left Surround & Right Surround. */ + IPC4_CHANNEL_CONFIG_5_POINT_1 = 8, /**< 5.1 Surround: Left, Center, Right, Left Surround, Right Surround & LFE. */ + IPC4_CHANNEL_CONFIG_DUAL_MONO = 9, /**< Dual mono: single logical channel duplicated into two slots. */ + IPC4_CHANNEL_CONFIG_I2S_DUAL_STEREO_0 = 10, /**< Stereo (L,R) in 4 slots, 1st stream: [ L, R, -, - ]. */ + IPC4_CHANNEL_CONFIG_I2S_DUAL_STEREO_1 = 11, /**< Stereo (L,R) in 4 slots, 2nd stream: [ -, -, L, R ]. */ + IPC4_CHANNEL_CONFIG_7_POINT_1 = 12, /**< 7.1 Surround: L, C, R, Ls, Rs, LFE, Left Side & Right Side. */ + IPC4_CHANNEL_CONFIG_INVALID /**< Sentinel for unsupported channel configuration. */ }; +/** + * \brief Logical channel position indices used in channel maps. + * \ingroup ipc4_format_api + */ enum ipc4_channel_index { - CHANNEL_LEFT = 0, - CHANNEL_CENTER = 1, - CHANNEL_RIGHT = 2, - CHANNEL_LEFT_SURROUND = 3, - CHANNEL_CENTER_SURROUND = 3, - CHANNEL_RIGHT_SURROUND = 4, - CHANNEL_LEFT_SIDE = 5, - CHANNEL_RIGHT_SIDE = 6, - CHANNEL_LFE = 7, - CHANNEL_INVALID = 0xF, + CHANNEL_LEFT = 0, /**< Front Left channel. */ + CHANNEL_CENTER = 1, /**< Front Center channel. */ + CHANNEL_RIGHT = 2, /**< Front Right channel. */ + CHANNEL_LEFT_SURROUND = 3, /**< Left Surround channel. */ + CHANNEL_CENTER_SURROUND = 3, /**< Center Surround channel. */ + CHANNEL_RIGHT_SURROUND = 4, /**< Right Surround channel. */ + CHANNEL_LEFT_SIDE = 5, /**< Left Side Surround channel. */ + CHANNEL_RIGHT_SIDE = 6, /**< Right Side Surround channel. */ + CHANNEL_LFE = 7, /**< Low Frequency Effects (subwoofer) channel. */ + CHANNEL_INVALID = 0xF, /**< Unmapped or inactive channel slot. */ }; +/** + * \brief Sample interleaving styles. + * \ingroup ipc4_format_api + */ enum ipc4_interleaved_style { - IPC4_CHANNELS_INTERLEAVED = 0, - IPC4_CHANNELS_NONINTERLEAVED = 1, + IPC4_CHANNELS_INTERLEAVED = 0, /**< Channels interleaved sample-by-sample (L0, R0, L1, R1...). */ + IPC4_CHANNELS_NONINTERLEAVED = 1, /**< Planar non-interleaved channels (all Left samples, then all Right). */ }; +/** + * \brief Audio sample representation and arithmetic type. + * \ingroup ipc4_format_api + */ enum ipc4_sample_type { - IPC4_TYPE_MSB_INTEGER = 0, /**< integer with Most Significant Byte first */ - IPC4_TYPE_LSB_INTEGER = 1, /**< integer with Least Significant Byte first */ - IPC4_TYPE_SIGNED_INTEGER = 2, - IPC4_TYPE_UNSIGNED_INTEGER = 3, - IPC4_TYPE_FLOAT = 4, - IPC4_TYPE_A_LAW = 5, - IPC4_TYPE_MU_LAW = 6, + IPC4_TYPE_MSB_INTEGER = 0, /**< Integer with Most Significant Byte first. */ + IPC4_TYPE_LSB_INTEGER = 1, /**< Integer with Least Significant Byte first. */ + IPC4_TYPE_SIGNED_INTEGER = 2, /**< Standard 2's complement signed integer (e.g. Q1.15, Q1.23, Q1.31). */ + IPC4_TYPE_UNSIGNED_INTEGER = 3, /**< Unsigned integer PCM. */ + IPC4_TYPE_FLOAT = 4, /**< 32-bit IEEE 754 floating point. */ + IPC4_TYPE_A_LAW = 5, /**< ITU-T G.711 A-law companded audio. */ + IPC4_TYPE_MU_LAW = 6, /**< ITU-T G.711 mu-law companded audio. */ }; +/** + * \brief Stream container encoding type. + * \ingroup ipc4_format_api + */ enum ipc4_stream_type { - IPC4_STREAM_PCM = 0, /**< PCM stream */ - IPC4_STREAM_MP3 = 1, /**< MP3 encoded stream */ - IPC4_STREAM_AAC = 2, /**< AAC encoded stream */ - /* TODO: revisit max stream type count. Currently - * it aligns with windows audio driver and we will - * update all when more types are supported - */ - IPC4_STREAM_COUNT = 3, - IPC4_STREAM_INVALID = 0xFF + IPC4_STREAM_PCM = 0, /**< Linear Pulse Code Modulated (PCM) uncompressed audio. */ + IPC4_STREAM_MP3 = 1, /**< MPEG-1 Audio Layer III encoded bitstream. */ + IPC4_STREAM_AAC = 2, /**< Advanced Audio Coding encoded bitstream. */ + IPC4_STREAM_COUNT = 3, /**< Total count of defined stream types. */ + IPC4_STREAM_INVALID = 0xFF /**< Sentinel for invalid stream type. */ }; +/** + * \brief Standard audio format descriptor across all IPC4 modules and gateways. + * \ingroup ipc4_format_api + */ struct ipc4_audio_format { - uint32_t sampling_frequency; /* enum ipc4_sampling_frequency */ - uint32_t depth; /* enum ipc4_bit_depth */ - uint32_t ch_map; - uint32_t ch_cfg; /* enum ipc4_channel_config */ - uint32_t interleaving_style; - uint32_t channels_count : 8; - uint32_t valid_bit_depth : 8; - uint32_t s_type : 8; /* enum ipc4_sample_type */ - uint32_t reserved : 8; + uint32_t sampling_frequency; /**< Sampling rate in Hz (one of enum ipc4_sampling_frequency). */ + uint32_t depth; /**< Container bit depth in bits (one of enum ipc4_bit_depth). */ + uint32_t ch_map; /**< 32-bit channel map nibbles (CHANNEL_LEFT, CHANNEL_RIGHT, etc.). */ + uint32_t ch_cfg; /**< Channel topology configuration (one of enum ipc4_channel_config). */ + uint32_t interleaving_style; /**< Sample layout (one of enum ipc4_interleaved_style). */ + uint32_t channels_count : 8; /**< Active channel count (1 to 8). */ + uint32_t valid_bit_depth : 8; /**< Number of significant valid bits within container (e.g. 24). */ + uint32_t s_type : 8; /**< Sample representation type (one of enum ipc4_sample_type). */ + uint32_t reserved : 8; /**< Reserved padding bits; must be set to 0. */ } __attribute__((packed, aligned(4))); +/** + * \brief Base module configuration parameters provided upon module instantiation. + * \ingroup ipc4_format_api + */ struct ipc4_base_module_cfg { - uint32_t cpc; /**< the max count of Cycles Per Chunk processing */ - uint32_t ibs; /**< input Buffer Size (in bytes) */ - uint32_t obs; /**< output Buffer Size (in bytes) */ - uint32_t is_pages; /**< number of physical pages used */ - struct ipc4_audio_format audio_fmt; + uint32_t cpc; /**< Maximum Cycles Per Chunk (CPC) compute budget required by module. */ + uint32_t ibs; /**< Input Buffer Size (IBS) in bytes required per processing frame. */ + uint32_t obs; /**< Output Buffer Size (OBS) in bytes produced per processing frame. */ + uint32_t is_pages; /**< Number of physical 4KB memory pages allocated for module state. */ + struct ipc4_audio_format audio_fmt; /**< Primary audio stream format of the module. */ } __attribute__((packed, aligned(4))); +/** + * \brief Input pin format specification for multi-pin modules. + * \ingroup ipc4_format_api + */ struct ipc4_input_pin_format { - uint32_t pin_index; /**< index of the pin */ - uint32_t ibs; /**< specifies input frame size (in bytes) */ - struct ipc4_audio_format audio_fmt; /**< format of the input data */ + uint32_t pin_index; /**< Zero-based logical index of the input pin. */ + uint32_t ibs; /**< Required input frame buffer size in bytes for this pin. */ + struct ipc4_audio_format audio_fmt; /**< Negotiated audio data format for this input pin. */ } __attribute__((packed, aligned(4))); +/** + * \brief Output pin format specification for multi-pin modules. + * \ingroup ipc4_format_api + */ struct ipc4_output_pin_format { - uint32_t pin_index; /**< index of the pin */ - uint32_t obs; /**< specifies output frame size (in bytes) */ - struct ipc4_audio_format audio_fmt; /**< format of the output data */ + uint32_t pin_index; /**< Zero-based logical index of the output pin. */ + uint32_t obs; /**< Output frame buffer size in bytes for this pin. */ + struct ipc4_audio_format audio_fmt; /**< Negotiated audio data format for this output pin. */ } __attribute__((packed, aligned(4))); +/** + * \brief Extended module configuration header describing dynamic input and output pins. + * \ingroup ipc4_format_api + */ struct ipc4_base_module_cfg_ext { - /* specifies number of items in input_pins array. Maximum size is 8 */ + /**< Number of input pin format entries following in pin_formats[] (maximum 8). */ uint16_t nb_input_pins; - /* specifies number of items in output_pins array. Maximum size is 8 */ + /**< Number of output pin format entries following in pin_formats[] (maximum 8). */ uint16_t nb_output_pins; - uint8_t reserved[12]; - /* Specifies format of input pins followed by output pins. - * Pin format arrays may be non-continuous i.e. may contain pin #0 format - * followed by pin #2 format in case pin #1 will not be in use. - * FW assigned format of the pin based on pin_index, not on a position of - * the item in the array. Applies to both input and output pins. + uint8_t reserved[12]; /**< Reserved padding; must be set to 0. */ + /**< + * Variable-length array of input pin formats followed immediately by output pin formats. + * Formats are matched by pin_index rather than array index. */ uint8_t pin_formats[]; } __attribute__((packed, aligned(4))); +/** + * \brief Helper macro to calculate serialized byte size of struct ipc4_base_module_cfg_ext. + * \ingroup ipc4_format_api + */ #define ipc4_calc_base_module_cfg_ext_size(in_pins, out_pins) \ (sizeof(struct ipc4_base_module_cfg_ext) + \ (in_pins) * sizeof(struct ipc4_input_pin_format) + \ (out_pins) * sizeof(struct ipc4_output_pin_format)) -/* Struct to combine the base_cfg and base_cfg_ext for easier parsing */ +/** + * \brief Combined base and extended module configuration payload for easy parsing. + * \ingroup ipc4_format_api + */ struct ipc4_base_module_extended_cfg { - struct ipc4_base_module_cfg base_cfg; - struct ipc4_base_module_cfg_ext base_cfg_ext; + struct ipc4_base_module_cfg base_cfg; /**< Standard single-pin base module config. */ + struct ipc4_base_module_cfg_ext base_cfg_ext; /**< Extended multi-pin format descriptors. */ } __attribute__((packed, aligned(4))); -/* This enum defines short 16bit parameters common for all modules. - * Value of module specific parameters have to be less than 0x3000. +/** + * \brief Common 16-bit parameter IDs supported across all IPC4 module instances. + * \ingroup ipc4_format_api */ enum ipc4_base_module_params { - /* handled inside LargeConfigGet of module instance */ + /**< Retrieve module instance runtime memory and queue properties via LargeConfigGet. */ IPC4_MOD_INST_PROPS = 0xFE, - /* handled inside ConfigSet of module instance */ + /**< Enable or disable module instance processing via ConfigSet (0 = disable, 1 = enable). */ IPC4_MOD_INST_ENABLE = 0x3000 }; +/** + * \brief Runtime properties of a module pin connection. + * \ingroup ipc4_format_api + */ struct ipc4_pin_props { - /* type of the connected stream. - * Holds an "enum ipc4_stream_type" value. Fixed-size because of #9378 - */ + /**< Stream type (one of enum ipc4_stream_type). */ uint32_t stream_type; - /* audio format of the stream. The content is valid in case of ePcm stream_type. */ + /**< Active audio format of the stream (valid when stream_type == IPC4_STREAM_PCM). */ struct ipc4_audio_format format; - /* unique ID of the physical queue connected to the pin. - * If there is no queue connected, then -1 (invalid queue ID) is set - */ + /**< Physical DMA queue ID connected to this pin (-1 if unassigned). */ uint32_t phys_queue_id; } __attribute__((packed, aligned(4))); +/** + * \brief List of active pin properties for a module instance. + * \ingroup ipc4_format_api + */ struct ipc4_pin_list_info { - uint32_t pin_count; - struct ipc4_pin_props pin_info[1]; + uint32_t pin_count; /**< Number of active pin property descriptors. */ + struct ipc4_pin_props pin_info[1]; /**< Array of pin properties. */ } __attribute__((packed, aligned(4))); -/* structure describing module instance properties used in response - * to module LargeConfigGet with MOD_INST_PROPS parameter. +/** + * \brief Detailed module instance runtime state, memory consumption, and queue alignment. + * \ingroup ipc4_format_api + * + * Returned in response to LargeConfigGet with parameter ID #IPC4_MOD_INST_PROPS. */ struct ipc4_module_instance_props { - uint32_t id; - uint32_t dp_queue_type; - uint32_t queue_alignment; - uint32_t cp_usage_mask; - uint32_t stack_bytes; - uint32_t bss_total_bytes; - uint32_t bss_used_bytes; - uint32_t ibs_bytes; - uint32_t obs_bytes; - uint32_t cpc; - uint32_t cpc_peak; - struct ipc4_pin_list_info input_queues; - struct ipc4_pin_list_info output_queues; - uint32_t input_gateway; - uint32_t output_gateway; + uint32_t id; /**< Unique module instance identifier. */ + uint32_t dp_queue_type; /**< Data processing queue type. */ + uint32_t queue_alignment; /**< Buffer memory alignment in bytes required by DSP. */ + uint32_t cp_usage_mask; /**< Coprocessor / hardware accelerator usage bitmask. */ + uint32_t stack_bytes; /**< Stack memory allocated for module instance thread. */ + uint32_t bss_total_bytes; /**< Total BSS data section size in bytes. */ + uint32_t bss_used_bytes; /**< Currently utilized BSS memory in bytes. */ + uint32_t ibs_bytes; /**< Input buffer size in bytes. */ + uint32_t obs_bytes; /**< Output buffer size in bytes. */ + uint32_t cpc; /**< Nominal Cycles Per Chunk compute requirement. */ + uint32_t cpc_peak; /**< Peak measured Cycles Per Chunk compute requirement. */ + struct ipc4_pin_list_info input_queues; /**< Connected input queue descriptors. */ + struct ipc4_pin_list_info output_queues; /**< Connected output queue descriptors. */ + uint32_t input_gateway; /**< Input gateway node ID if attached directly to gateway. */ + uint32_t output_gateway; /**< Output gateway node ID if attached directly to gateway. */ } __attribute__((packed, aligned(4))); -/* Reflects the last two entries in ModuleInstanceProps sttructure */ +/** + * \brief Direct gateway attachment identifiers for a module instance. + * \ingroup ipc4_format_api + */ struct ipc4_in_out_gateway { - uint32_t input_gateway; - uint32_t output_gateway; + uint32_t input_gateway; /**< Node ID of attached input gateway (e.g. DMA stream). */ + uint32_t output_gateway; /**< Node ID of attached output gateway (e.g. DMA stream). */ } __attribute__((packed, aligned(4))); -/* this structure may be used by modules to carry - * short 16bit parameters as part of the IxC register content. +/** + * \brief 16-bit small parameter register encoding for MOD_CONFIG_SET/GET. + * \ingroup ipc4_format_api */ union ipc4_cfg_param_id_data { - uint32_t dw; + uint32_t dw; /**< Raw 32-bit register value. */ struct { - uint32_t data16 : 16; /* Input/Output small config data */ - uint32_t id : 14; /* input parameter ID */ - uint32_t _rsvd : 2; + uint32_t data16 : 16; /**< 16-bit parameter data payload. */ + uint32_t id : 14; /**< 14-bit parameter identifier. */ + uint32_t _rsvd : 2; /**< Reserved bits. */ } f; } __attribute__((packed, aligned(4))); From 3218dd6d3737b45495ca598361818b3b955cc53a Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 13 Oct 2026 16:06:02 +0100 Subject: [PATCH 3/9] doc: ipc4: document module lifecycle, dynamic binding, and large config 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 --- src/include/ipc4/aec.h | 21 +- src/include/ipc4/detect_test.h | 22 +- src/include/ipc4/kpb.h | 20 +- src/include/ipc4/module.h | 549 +++++++++++++++------------------ 4 files changed, 294 insertions(+), 318 deletions(-) diff --git a/src/include/ipc4/aec.h b/src/include/ipc4/aec.h index 9456f86bcdf8..702316078003 100644 --- a/src/include/ipc4/aec.h +++ b/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 #include +/** + * \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 diff --git a/src/include/ipc4/detect_test.h b/src/include/ipc4/detect_test.h index 603bf1741b2c..a3a46d1cf14d 100644 --- a/src/include/ipc4/detect_test.h +++ b/src/include/ipc4/detect_test.h @@ -7,29 +7,27 @@ /** * \file include/ipc4/detect_test.h - * \brief KD module definitions. + * \brief Keyword Detector (KD) test module configuration and parameter definitions. + * \ingroup ipc4_telemetry_probe_api * NOTE: This ABI uses bit fields and is non portable. */ #ifndef __SOF_IPC4_DETECT_TEST_H__ #define __SOF_IPC4_DETECT_TEST_H__ +/** + * \brief Parameter IDs for Keyword Detector test module LargeConfigSet/Get. + * \ingroup ipc4_telemetry_probe_api + */ enum ipc4_detect_test_module_config_params { - /* Use LARGE_CONFIG_SET to process model blob. Ipc mailbox must - * contain properly configured BLOB for Detect Keyword module. - */ + /**< Send neural network keyword detection model binary blob via LargeConfigSet. */ IPC4_DETECT_TEST_SET_MODEL_BLOB = 1, - /* Use LARGE_CONFIG_SET to set Detect Keyword module parameters. - * Ipc mailbox must contain properly built sof_detect_test_config - * struct. - */ + /**< Configure Keyword Detector operational thresholds and parameters via LargeConfigSet. */ IPC4_DETECT_TEST_SET_CONFIG = 2, - /* Use LARGE_CONFIG_GET to retrieve Detect Test config - * Ipc mailbox must contain properly built sof_detect_test_config - * struct. - */ + /**< Query current Keyword Detector operational configuration via LargeConfigGet. */ IPC4_DETECT_TEST_GET_CONFIG = 3 }; + #endif diff --git a/src/include/ipc4/kpb.h b/src/include/ipc4/kpb.h index 0c56942313c3..2ee8cef3e865 100644 --- a/src/include/ipc4/kpb.h +++ b/src/include/ipc4/kpb.h @@ -7,7 +7,8 @@ /** * \file include/ipc4/kpb.h - * \brief KPB module definitions. + * \brief Key Phrase Buffer (KPB) audio pre-roll module configuration and parameters. + * \ingroup ipc4_telemetry_probe_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -16,17 +17,22 @@ #include "base-config.h" +/** + * \brief KPB module instance base configuration structure. + * \ingroup ipc4_telemetry_probe_api + */ struct ipc4_kpb_module_cfg { - struct ipc4_base_module_cfg base_cfg; + struct ipc4_base_module_cfg base_cfg; /**< Standard base module configuration. */ } __packed __aligned(4); -/* For the sake of compatibility, do not change IDs, only add new ones.*/ +/** + * \brief Parameter IDs for KPB module LargeConfigSet/Get. + * \ingroup ipc4_telemetry_probe_api + */ enum ipc4_kpb_module_config_params { - /*! Configure the module ID's which would be part of the Fast mode tasks */ + /**< Configure module IDs that execute within Fast Mode (FM) draining tasks. */ KP_BUF_CFG_FM_MODULE = 1, - /* Mic selector for client - sets microphone id for real time sink mic selector - * IPC4-compatible ID - please do not change the number - */ + /**< Real-time sink microphone channel selector ID. */ KP_BUF_CLIENT_MIC_SELECT = 11, }; diff --git a/src/include/ipc4/module.h b/src/include/ipc4/module.h index db1a074151a5..691e83112aa4 100644 --- a/src/include/ipc4/module.h +++ b/src/include/ipc4/module.h @@ -15,7 +15,7 @@ /** * \file include/ipc4/module.h * \brief IPC4 module instantiation, binding, pin configuration, and parameter definitions. - * \ingroup ipc4_api + * \ingroup ipc4_module_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -26,516 +26,479 @@ #include -/* TODO: revisit it. Now it aligns with audio sdk - * and we will update this value and sdk when more - * libraries are supported - */ +/** Maximum number of dynamically loadable LLEXT library containers. */ #define IPC4_MAX_SUPPORTED_LIBRARIES 16 +/** Maximum distinct module class types registered in the FW image manifest. */ #define IPC4_MAX_MODULE_COUNT 128 +/** Number of bits allocated for destination queue/pin ID in bind commands (3 bits, supporting pins 0..7). */ #define SOF_IPC4_DST_QUEUE_ID_BITFIELD_SIZE 3 +/** Number of bits allocated for source queue/pin ID in bind commands (3 bits, supporting pins 0..7). */ #define SOF_IPC4_SRC_QUEUE_ID_BITFIELD_SIZE 3 -/* Special large_param_id values */ +/** Special parameter ID (0xFF) designating vendor-specific large configuration payloads. */ #define VENDOR_CONFIG_PARAM 0xFF +/** + * \brief Module message command opcodes (5-bit opcode in Primary DWORD when msg_tgt == MODULE_MSG). + * \ingroup ipc4_module_api + */ enum sof_ipc4_module_type { - SOF_IPC4_MOD_INIT_INSTANCE = 0, - SOF_IPC4_MOD_CONFIG_GET = 1, - SOF_IPC4_MOD_CONFIG_SET = 2, - SOF_IPC4_MOD_LARGE_CONFIG_GET = 3, - SOF_IPC4_MOD_LARGE_CONFIG_SET = 4, - SOF_IPC4_MOD_BIND = 5, - SOF_IPC4_MOD_UNBIND = 6, - SOF_IPC4_MOD_SET_DX = 7, - SOF_IPC4_MOD_SET_D0IX = 8, - SOF_IPC4_MOD_ENTER_MODULE_RESTORE = 9, - SOF_IPC4_MOD_EXIT_MODULE_RESTORE = 10, - SOF_IPC4_MOD_DELETE_INSTANCE = 11, + SOF_IPC4_MOD_INIT_INSTANCE = 0, /**< Instantiate a new module object and attach to a pipeline. */ + SOF_IPC4_MOD_CONFIG_GET = 1, /**< Retrieve a short 16-bit module parameter packed in header. */ + SOF_IPC4_MOD_CONFIG_SET = 2, /**< Set a short 16-bit module parameter packed in header. */ + SOF_IPC4_MOD_LARGE_CONFIG_GET = 3, /**< Retrieve multi-block configuration or state data from module. */ + SOF_IPC4_MOD_LARGE_CONFIG_SET = 4, /**< Send multi-block configuration or filter coefficients to module. */ + SOF_IPC4_MOD_BIND = 5, /**< Connect a source pin of this module to a destination pin. */ + SOF_IPC4_MOD_UNBIND = 6, /**< Disconnect a runtime binding between two module instances. */ + SOF_IPC4_MOD_SET_DX = 7, /**< Request core power state transition (D0/D3). */ + SOF_IPC4_MOD_SET_D0IX = 8, /**< Request Base FW or module to enter low-power D0ix state. */ + SOF_IPC4_MOD_ENTER_MODULE_RESTORE = 9, /**< Notify module to prepare for context restoration after wake. */ + SOF_IPC4_MOD_EXIT_MODULE_RESTORE = 10, /**< Signal completion of module state restoration. */ + SOF_IPC4_MOD_DELETE_INSTANCE = 11, /**< Destroy module instance and release allocated memory. */ }; -/* - * Structs for Vendor Config +/** + * \brief Compound parameter identifier encoding type and instance index. + * \ingroup ipc4_module_api */ - union ipc4_extended_param_id { - uint32_t full; - struct{ - uint32_t parameter_type : 8; - uint32_t parameter_instance : 24; + uint32_t full; /**< Full 32-bit parameter identifier. */ + struct { + uint32_t parameter_type : 8; /**< Parameter type identifier. */ + uint32_t parameter_instance : 24; /**< Parameter instance index. */ } part; } __attribute__((packed, aligned(4))); +/** + * \brief Vendor error reporting payload structure. + * \ingroup ipc4_module_api + */ struct ipc4_vendor_error { - /* Index of the failed parameter */ - uint32_t param_idx; - /* Error code */ - uint32_t err_code; + uint32_t param_idx; /**< Index of the failed parameter in vendor configuration list. */ + uint32_t err_code; /**< Vendor-specific or hardware error code. */ }; -/* IDs for all global object types in struct ipc4_module_init_ext_object */ +/** + * \brief Global object type identifiers for extended initialization payloads. + * \ingroup ipc4_module_api + */ enum ipc4_mod_init_data_glb_id { - IPC4_MOD_INIT_DATA_ID_INVALID = 0, - IPC4_MOD_INIT_DATA_ID_DP_DATA = 1, - IPC4_MOD_INIT_DATA_ID_MODULE_DATA = 2, - IPC4_MOD_INIT_DATA_ID_MAX = IPC4_MOD_INIT_DATA_ID_MODULE_DATA, + IPC4_MOD_INIT_DATA_ID_INVALID = 0, /**< Invalid initialization object identifier. */ + IPC4_MOD_INIT_DATA_ID_DP_DATA = 1, /**< Data Processing (DP) thread stack and heap requirements. */ + IPC4_MOD_INIT_DATA_ID_MODULE_DATA = 2, /**< Module-specific bespoke initialization data. */ + IPC4_MOD_INIT_DATA_ID_MAX = IPC4_MOD_INIT_DATA_ID_MODULE_DATA, /**< Maximum supported object identifier. */ }; -/* data object for vendor bespoke data with ABI growth and backwards compat */ +/** + * \brief Header for extended initialization data objects. + * \ingroup ipc4_module_api + */ struct ipc4_module_init_ext_object { - uint32_t last_object : 1; /* object is last in array if 1 else object follows. */ - uint32_t object_id : 15; /* unique ID for this object or globally */ - uint32_t object_words : 16; /* size in dwords (excluding this structure) */ + uint32_t last_object : 1; /**< Set to 1 if this is the terminating object in the array. */ + uint32_t object_id : 15; /**< Unique object identifier (one of enum ipc4_mod_init_data_glb_id). */ + uint32_t object_words : 16; /**< Payload size in 32-bit DWORDs following this header. */ } __attribute__((packed, aligned(4))); -/* the object data will be placed in memory here and will have size "object_words" */ -/* Ext init array data object for Data Processing module memory requirements */ +/** + * \brief Memory requirements for Data Processing (DP) module threads. + * \ingroup ipc4_module_api + */ struct ipc4_module_init_ext_obj_dp_data { - uint32_t domain_id; /* userspace domain ID */ - uint32_t stack_bytes; /* required stack size in bytes */ - uint32_t heap_bytes; /* required heap size in bytes */ + uint32_t domain_id; /**< Userspace domain identifier. */ + uint32_t stack_bytes; /**< Required thread stack size in bytes. */ + uint32_t heap_bytes; /**< Required thread heap allocation size in bytes. */ } __attribute__((packed, aligned(4))); -/* - * Host Driver sends this message to create a new module instance. +/** + * \brief Extended initialization flags and coprocessor requirements. + * \ingroup ipc4_module_api */ struct ipc4_module_init_ext_init { - /**< if it is set to 1, proc_domain should be ignored and processing */ - /* domain is RTOS scheduling */ + /**< If set to 1, proc_domain is ignored and processing domain is RTOS scheduling. */ uint32_t rtos_domain : 1; - /**< Indicates that GNA is used by a module and additional information */ - /* (gna_config) is passed after ExtendedData. */ + /**< Indicates that GNA coprocessor is used by module and gna_config follows. */ uint32_t gna_used : 1; - uint32_t data_obj_array : 1; /* struct ipc4_module_init_ext_object data */ - uint32_t rsvd_0 : 29; - uint32_t rsvd_1[2]; + uint32_t data_obj_array : 1; /**< 1 if followed by struct ipc4_module_init_ext_object array. */ + uint32_t rsvd_0 : 29; /**< Reserved bits. */ + uint32_t rsvd_1[2]; /**< Reserved padding words. */ } __attribute__((packed, aligned(4))); +/** + * \brief Extended module initialization container. + * \ingroup ipc4_module_api + */ struct ipc4_module_init_ext_data { - struct ipc4_module_init_ext_init extended_init; - - /**< Data (actual size set to param_block_size) */ - uint32_t param_data[]; + struct ipc4_module_init_ext_init extended_init; /**< Extended flags. */ + uint32_t param_data[]; /**< Module configuration payload words. */ } __attribute__((packed, aligned(4))); +/** + * \brief Neural network accelerator (GNA) compute cycle configuration. + * \ingroup ipc4_module_api + */ struct ipc4_module_init_gna_config { /**< Number of GNA cycles required to process one input frame. */ - /* This information is used by DP scheduler to correctly schedule - * a DP module. - */ uint32_t gna_cpc; - uint32_t rsvd; + uint32_t rsvd; /**< Reserved padding. */ } __attribute__((packed, aligned(4))); +/** + * \brief Module initialization payload buffer. + * \ingroup ipc4_module_api + */ struct ipc4_module_init_data { - /**< Data (actual size set to param_block_size) */ - uint32_t param_data[0]; + uint32_t param_data[0]; /**< Configuration payload words (sized by param_block_size). */ } __attribute__((packed, aligned(4))); -/*! - Created instance is a child element of pipeline identified by the ppl_id - specified by the driver. - - The module_id should be set to an index of the module entry in the FW Image - Manifest. - - The instance_id assigned by the driver should be in the - 0..ModuleEntry.max_instance_count range defined in the FW Image Manifest. - - Initial configuration of the module instance is provided by the driver in - the param_data array. Size of the array is specified in param_block_size - field of the message header. - - Refer to Module Configuration section of FW I/F Specification for details on - module specific initial configuration parameters. - - \remark hide_methods -*/ - -/* Reserved ppl_instance_id: module has no parent pipeline (e.g. probe). */ +/** Reserved pipeline ID (0xFF) indicating module has no parent pipeline (e.g. probe). */ #define IPC4_INVALID_PIPELINE_ID 0xFF +/** + * \brief Module instance creation command structure (SOF_IPC4_MOD_INIT_INSTANCE). + * \ingroup ipc4_module_api + */ struct ipc4_module_init_instance { - union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< module id */ + /**< Module class ID index from the FW manifest. */ uint32_t module_id : 16; - /**< instance id */ + /**< Module instance ID unique within the module class (0..max_instances-1). */ uint32_t instance_id : 8; - /**< ModuleMsg::INIT_INSTANCE */ + /**< Opcode: SOF_IPC4_MOD_INIT_INSTANCE (0). */ uint32_t type : 5; - /**< Msg::MSG_REQUEST */ + /**< Direction: 0 for request (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST). */ uint32_t rsp : 1; - /**< Msg::MODULE_MSG */ + /**< Target: 1 for module message (SOF_IPC4_MESSAGE_TARGET_MODULE_MSG). */ uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t _reserved_0 : 1; /**< Reserved hardware control bit. */ } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< Size of Data::param_data[] (in dwords) */ + /**< Size of initialization payload in 32-bit DWORDs. */ uint32_t param_block_size : 16; - /**< ID of module instance's parent pipeline */ + /**< ID of parent pipeline, or #IPC4_INVALID_PIPELINE_ID. */ uint32_t ppl_instance_id : 8; - /**< ID of core that instance will run on */ + /**< Target DSP core ID on which this instance will execute (0..3). */ uint32_t core_id : 4; - /**< Processing domain, 0-LL, 1-DP */ + /**< Processing domain (0 = Low-Latency LL, 1 = Data Processing DP). */ uint32_t proc_domain : 1; - /* reserved in cAVS */ + /**< 1 if extended initialization structures follow. */ uint32_t extended_init : 1; - uint32_t _hw_reserved_2 : 2; + uint32_t _hw_reserved_2 : 2; /**< Reserved hardware bits. */ } r; } extension; -/* - * The following objects are optional and follow this structure in this - * order provided the respective object bit is set in preceding object. - * - * struct ipc4_module_init_ext_init ext_init; - * struct ipc4_module_init_ext_data ext_data; - * struct ipc4_module_init_gna_config gna_config; - * struct ipc4_module_init_data init_data; - */ } __attribute__((packed, aligned(4))); -/*! - SW Driver sends Bind IPC message to connect two module instances together - creating data processing path between them. - - Unbind IPC message is sent to destroy a connection between two module instances - (belonging to different pipelines) previously created with Bind call. - - NOTE: when both module instances are parts of the same pipeline Unbind IPC would - be ignored by FW since FW does not support changing internal topology of pipeline - during run-time. The only way to change pipeline topology is to delete the whole - pipeline and create it in modified form. - - \remark hide_methods +/** + * \brief Module pin binding and unbinding command structure (SOF_IPC4_MOD_BIND / UNBIND). + * \ingroup ipc4_module_api + * + * Sent by host to connect two module instances across pins (queues), or sever an existing link. */ struct ipc4_module_bind_unbind { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< module id */ + /**< Source module class identifier. */ uint32_t module_id : 16; - /**< instance id */ + /**< Source module instance identifier. */ uint32_t instance_id : 8; - /**< ModuleMsg::BIND / UNBIND. */ + /**< Opcode: SOF_IPC4_MOD_BIND (5) or SOF_IPC4_MOD_UNBIND (6). */ uint32_t type : 5; - /**< Msg::MSG_REQUEST */ + /**< Direction: 0 for request (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST). */ uint32_t rsp : 1; - /**< Msg::MODULE_MSG */ + /**< Target: 1 for module message (SOF_IPC4_MESSAGE_TARGET_MODULE_MSG). */ uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t _reserved_0 : 1; /**< Reserved hardware control bit. */ } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< destination module id */ + /**< Destination module class identifier. */ uint32_t dst_module_id : 16; - /**< destination instance id */ + /**< Destination module instance identifier. */ uint32_t dst_instance_id : 8; - /**< destination queue (pin) id */ + /**< Destination input queue/pin index (0..7). */ uint32_t dst_queue : SOF_IPC4_DST_QUEUE_ID_BITFIELD_SIZE; - /**< source queue (pin) id */ + /**< Source output queue/pin index (0..7). */ uint32_t src_queue : SOF_IPC4_SRC_QUEUE_ID_BITFIELD_SIZE; - uint32_t _reserved_2 : 2; + uint32_t _reserved_2 : 2; /**< Reserved hardware control bits. */ } r; } extension; } __attribute__((packed, aligned(4))); -/* - * Using Module Config Get / Set command, host driver may send a parameter - * that fits into the header (a very short one), packed along with parameter id. - * Larger parameters require fragmentation and a series of Large Config Set - * commands. - * - * param_id_data specifies both ID of the parameter, defined by the module - * and value of the parameter. - * It is up to the module how to distribute bits to ID and value of the parameter. - * If there are more bits required than available to value, then Input Data may - * be used to pass the value - * - * NOTE: Module Config Get/Set commands are used internally by the driver - * for small parameters defined by Intel components. While all externally - * developed components communicates with host using Large Config commands - * no matter what the size of parameter is. +/** + * \brief Small parameter configuration command structure (SOF_IPC4_MOD_CONFIG_GET / SET). + * \ingroup ipc4_module_api */ struct ipc4_module_config { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - uint32_t module_id : 16; /* module id */ - uint32_t instance_id : 8; /* instance id */ - /* SOF_IPC4_MOD_CONFIG_GET / SOF_IPC4_MOD_CONFIG_SET */ - uint32_t type : 5; - uint32_t rsp : 1; /* SOF_IPC4_MESSAGE_DIR_MSG_REQUEST */ - uint32_t msg_tgt : 1; /* SOF_IPC4_MESSAGE_TARGET_MODULE_MSG */ - uint32_t _reserved_0 : 1; + uint32_t module_id : 16; /**< Target module class ID. */ + uint32_t instance_id : 8; /**< Target module instance ID. */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_MOD_CONFIG_GET or SET. */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 1 for module message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /* Param id and data */ - uint32_t param_id_data : 30; - uint32_t _reserved_2 : 2; + uint32_t param_id_data : 30; /**< Packed 16-bit parameter data and 14-bit parameter ID. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); -/* - * Sent by FW in response to Module Config Get. +/** + * \brief Reply structure for small parameter query (SOF_IPC4_MOD_CONFIG_GET). + * \ingroup ipc4_module_api */ struct ipc4_module_config_reply { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - uint32_t status : IPC4_IXC_STATUS_BITS; - uint32_t type : 5; /* SOF_IPC4_MOD_CONFIG_GET */ - uint32_t rsp : 1; /* SOF_IPC4_MESSAGE_DIR_MSG_REPLY */ - uint32_t msg_tgt : 1; /* SOF_IPC4_MESSAGE_TARGET_MODULE_MSG */ - uint32_t _reserved_0 : 1; + uint32_t status : IPC4_IXC_STATUS_BITS; /**< Command processing status (enum ipc4_status). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_MOD_CONFIG_GET. */ + uint32_t rsp : 1; /**< 1 for reply. */ + uint32_t msg_tgt : 1; /**< 1 for module message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /* - * Value of this field may be changed by the module - * if parameter value fits into the available bits, - * or stay intact if the value is copied to the Output Data. - */ - uint32_t param_id_data : 30; - uint32_t _reserved_2 : 2; + uint32_t param_id_data : 30; /**< Returned parameter value if fitting in 30 bits. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); +/** + * \brief Large configuration parameter transfer envelope (SOF_IPC4_MOD_LARGE_CONFIG_GET / SET). + * \ingroup ipc4_module_api + * + * Implements the multi-block fragmentation handshake for exchanging configuration payloads + * exceeding the mailbox window size (e.g. FIR coefficients, EQ curves, model blobs). + */ struct ipc4_module_large_config { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< module id */ - uint32_t module_id : 16; - /**< instance id */ - uint32_t instance_id : 8; - /**< ModuleMsg::LARGE_CONFIG_GET / LARGE_CONFIG_SET */ - uint32_t type : 5; - /**< Msg::MSG_REQUEST or Msg::MSG_REPLY */ - uint32_t rsp : 1; - /**< Msg::MODULE_MSG or Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; - } r; - } primary; + uint32_t module_id : 16; /**< Target module class ID. */ + uint32_t instance_id : 8; /**< Target module instance ID. */ + uint32_t type : 5; /**< LARGE_CONFIG_GET (3) or LARGE_CONFIG_SET (4). */ + uint32_t rsp : 1; /**< 0 for request, 1 for reply. */ + uint32_t msg_tgt : 1; /**< 1 for module target. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ + } r; + } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< data size for single block, offset for multiple block case */ + /**< Chunk byte size (single block) or cumulative byte offset (multi-block). */ uint32_t data_off_size : 20; - /**< param type : VENDOR_CONFIG_PARAM / GENERIC_CONFIG_PARAM */ + /**< Parameter type identifier (module-specific or #VENDOR_CONFIG_PARAM). */ uint32_t large_param_id : 8; - /**< 1 if final block */ + /**< Set to 1 on the terminating chunk of a multi-block transfer. */ uint32_t final_block : 1; - /**< 1 if init block */ + /**< Set to 1 on the initial chunk of a multi-block transfer. */ uint32_t init_block : 1; - uint32_t _reserved_2 : 2; + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); +/** + * \brief Reply structure for large configuration transfer. + * \ingroup ipc4_module_api + */ struct ipc4_module_large_config_reply { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - uint32_t status :IPC4_IXC_STATUS_BITS; - /**< ModuleMsg::LARGE_CONFIG_GET / LARGE_CONFIG_SET */ - uint32_t type : 5; - /**< Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /**< Msg::MODULE_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; - } r; - } primary; + uint32_t status : IPC4_IXC_STATUS_BITS; /**< Processing status (enum ipc4_status). */ + uint32_t type : 5; /**< Symmetric opcode. */ + uint32_t rsp : 1; /**< 1 for reply. */ + uint32_t msg_tgt : 1; /**< Symmetric target. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ + } r; + } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< data size/offset */ - uint32_t data_off_size : 20; - /**< param type : VENDOR_CONFIG_PARAM / GENERIC_CONFIG_PARAM */ - uint32_t large_param_id : 8; - /**< 1 if final block */ - uint32_t final_block : 1; - /**< 1 if first block */ - uint32_t init_block : 1; - uint32_t _reserved_2 : 2; + uint32_t data_off_size : 20; /**< Processed byte size or offset. */ + uint32_t large_param_id : 8; /**< Parameter type ID. */ + uint32_t final_block : 1; /**< 1 if final block processed. */ + uint32_t init_block : 1; /**< 1 if first block processed. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); +/** + * \brief Module instance deletion command structure (SOF_IPC4_MOD_DELETE_INSTANCE). + * \ingroup ipc4_module_api + */ struct ipc4_module_delete_instance { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - uint32_t module_id : 16; - uint32_t instance_id : 8; - /**< ModuleMsg::DELETE_INSTANCE */ - uint32_t type : 5; - /**< Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /**< Msg::MODULE_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t module_id : 16; /**< Module class ID of instance to destroy. */ + uint32_t instance_id : 8; /**< Instance ID to destroy. */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_MOD_DELETE_INSTANCE (11). */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 1 for module target. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - uint32_t rsvd : 30; - uint32_t _reserved_1 : 2; + uint32_t rsvd : 30; /**< Reserved padding. */ + uint32_t _reserved_1 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); +/** + * \brief Module D0ix low-power state entry command (SOF_IPC4_MOD_SET_D0IX). + * \ingroup ipc4_module_api + */ struct ipc4_module_set_d0ix { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /* module id (must be 0 - Base FW) */ - uint32_t module_id : 16; - /* instance id (must be 0 - core 0) */ - uint32_t instance_id : 8; - /* ModuleMsg::SET_D0IX */ - uint32_t type : 5; - /* Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /* Msg::MODULE_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t module_id : 16; /**< Module ID (must be 0 for Base FW). */ + uint32_t instance_id : 8; /**< Instance ID (must be 0 for core 0). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_MOD_SET_D0IX (8). */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 1 for module message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /* legacy wake type (see WakeType) */ - uint32_t wake : 1; - /* streaming active now */ - uint32_t streaming : 1; - /* D0/D0ix transitions allowed (PG disabled) */ - uint32_t prevent_power_gating : 1; - /* Clock gating enabled */ - uint32_t prevent_local_clock_gating : 1; - - uint32_t rsvd1 : 26; - uint32_t _reserved_2 : 2; + uint32_t wake : 1; /**< Legacy wake type flag. */ + uint32_t streaming : 1; /**< Active audio streaming indicator. */ + uint32_t prevent_power_gating : 1; /**< Set to 1 to inhibit DSP core power gating. */ + uint32_t prevent_local_clock_gating : 1; /**< Set to 1 to inhibit local clock gating. */ + uint32_t rsvd1 : 26; /**< Reserved padding. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); +/** + * \brief DSP core power state bitmask descriptor. + * \ingroup ipc4_module_api + */ struct ipc4_dx_state_info { - /* Indicates which cores are subject to change the power state */ - uint32_t core_mask; - /* Indicates core state. - * bit[core_id] = 0 -> put core_id to D3 - * bit[core_id] = 1 -> put core_id to D0 - */ + uint32_t core_mask; /**< Bitmask indicating which DSP cores are subject to state change. */ + /**< Target state bitmask: bit[core_id] = 0 -> put to D3, bit[core_id] = 1 -> put to D0. */ uint32_t dx_mask; } __attribute__((packed, aligned(4))); +/** + * \brief Core DX power state transition command structure (SOF_IPC4_MOD_SET_DX). + * \ingroup ipc4_module_api + */ struct ipc4_module_set_dx { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /* module id (must be 0 - Base FW) */ - uint32_t module_id : 16; - /* instance id (must be 0 - core 0) */ - uint32_t instance_id : 8; - /* ModuleMsg::SET_DX */ - uint32_t type : 5; - /* Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /* Msg::MODULE_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t module_id : 16; /**< Module ID (0 for Base FW). */ + uint32_t instance_id : 8; /**< Instance ID (0 for Core 0). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_MOD_SET_DX (7). */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 1 for module message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - uint32_t rsvd : 30; - uint32_t _reserved_2 : 2; + uint32_t rsvd : 30; /**< Reserved padding. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); +/** + * \brief Dynamic library loading command structure (SOF_IPC4_GLB_LOAD_LIBRARY). + * \ingroup ipc4_module_api + */ struct ipc4_module_load_library { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /* ID of HD/A HO DMA to load the code */ - uint32_t dma_id : 5; - uint32_t rsvd0 : 11; - /* ID of library */ - uint32_t lib_id : 4; - uint32_t rsvd1 : 4; - /* Global::LOAD_LIBRARY */ - uint32_t type : 5; - /* Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /* Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t dma_id : 5; /**< ID of Host Output DMA used to load code. */ + uint32_t rsvd0 : 11; /**< Reserved padding. */ + uint32_t lib_id : 4; /**< Dynamic library container ID (0..15). */ + uint32_t rsvd1 : 4; /**< Reserved padding. */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_LOAD_LIBRARY (24). */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 0 for global firmware message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } header; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - uint32_t load_offset : 30; - uint32_t _reserved_2 : 2; + uint32_t load_offset : 30; /**< Load offset into host DMA buffer. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } data; } __attribute__((packed, aligned(4))); +/** Construct a 32-bit component token from module class ID (x) and instance ID (y). */ #define IPC4_COMP_ID(x, y) ((y) << 16 | (x)) +/** Extract 16-bit module class ID from a 32-bit component token. */ #define IPC4_MOD_ID(x) (IS_ENABLED(CONFIG_IPC_MAJOR_4) ? ((x) & 0xffff) : 0) +/** Extract 16-bit instance ID from a 32-bit component token. */ #define IPC4_INST_ID(x) ((x) >> 16) +/** Extract 16-bit source queue/pin ID from a 32-bit queue token. */ #define IPC4_SRC_QUEUE_ID(x) ((x) & 0xffff) +/** Extract 16-bit sink queue/pin ID from a 32-bit queue token. */ #define IPC4_SINK_QUEUE_ID(x) (((x) >> 16) & 0xffff) #endif From 84944b573f023c81e78a44a8bd6b5a45a1d84afd Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 13 Oct 2026 16:07:10 +0100 Subject: [PATCH 4/9] doc: ipc4: document pipeline lifecycle, priorities, and state transitions Signed-off-by: Liam Girdwood --- src/include/ipc4/pipeline.h | 445 +++++++++++++++++------------------- 1 file changed, 206 insertions(+), 239 deletions(-) diff --git a/src/include/ipc4/pipeline.h b/src/include/ipc4/pipeline.h index da756364dc6a..c7452ffb03fe 100644 --- a/src/include/ipc4/pipeline.h +++ b/src/include/ipc4/pipeline.h @@ -18,7 +18,7 @@ /** * \file include/ipc4/pipeline.h * \brief IPC4 pipeline creation, states, priorities, and management commands. - * \ingroup ipc4_api + * \ingroup ipc4_pipeline_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -28,160 +28,140 @@ #include #include -/**< Pipeline priority */ +/** + * \brief Pipeline execution scheduling priority levels. + * \ingroup ipc4_pipeline_api + */ enum ipc4_pipeline_priority { - /**< Priority 0 (run first) */ - SOF_IPC4_PIPELINE_PRIORITY_0 = 0, - /**< Priority 1 */ - SOF_IPC4_PIPELINE_PRIORITY_1, - /**< Priority 2 */ - SOF_IPC4_PIPELINE_PRIORITY_2, - /**< Priority 3 */ - SOF_IPC4_PIPELINE_PRIORITY_3, - /**< Priority 4 */ - SOF_IPC4_PIPELINE_PRIORITY_4, - /**< Priority 5 */ - SOF_IPC4_PIPELINE_PRIORITY_5, - /**< Priority 6 */ - SOF_IPC4_PIPELINE_PRIORITY_6, - /**< Priority 7 */ - SOF_IPC4_PIPELINE_PRIORITY_7, - /**< Max (and lowest) priority */ - SOF_IPC4_MAX_PIPELINE_PRIORITY = SOF_IPC4_PIPELINE_PRIORITY_7 + SOF_IPC4_PIPELINE_PRIORITY_0 = 0, /**< Priority level 0 (highest priority, scheduled first). */ + SOF_IPC4_PIPELINE_PRIORITY_1, /**< Priority level 1. */ + SOF_IPC4_PIPELINE_PRIORITY_2, /**< Priority level 2. */ + SOF_IPC4_PIPELINE_PRIORITY_3, /**< Priority level 3. */ + SOF_IPC4_PIPELINE_PRIORITY_4, /**< Priority level 4. */ + SOF_IPC4_PIPELINE_PRIORITY_5, /**< Priority level 5. */ + SOF_IPC4_PIPELINE_PRIORITY_6, /**< Priority level 6. */ + SOF_IPC4_PIPELINE_PRIORITY_7, /**< Priority level 7 (lowest priority). */ + SOF_IPC4_MAX_PIPELINE_PRIORITY = SOF_IPC4_PIPELINE_PRIORITY_7 /**< Maximum valid priority level. */ }; -/**< Pipeline State */ +/** + * \brief Pipeline operational state machine values. + * \ingroup ipc4_pipeline_api + */ enum ipc4_pipeline_state { - /**< Invalid value */ - SOF_IPC4_PIPELINE_STATE_INVALID = 0, - /**< Created but initialization incomplete */ - SOF_IPC4_PIPELINE_STATE_UNINITIALIZED = 1, - /**< Resets pipeline */ - SOF_IPC4_PIPELINE_STATE_RESET = 2, - /**< Pauses pipeline */ - SOF_IPC4_PIPELINE_STATE_PAUSED = 3, - /**< Starts pipeline */ - SOF_IPC4_PIPELINE_STATE_RUNNING = 4, - /**< Marks pipeline as expecting End Of Stream */ - SOF_IPC4_PIPELINE_STATE_EOS = 5, - /**< Stopped on error */ - SOF_IPC4_PIPELINE_STATE_ERROR_STOP, - /**< Saved to the host memory */ - SOF_IPC4_PIPELINE_STATE_SAVED + SOF_IPC4_PIPELINE_STATE_INVALID = 0, /**< Invalid or uninitialized pipeline state. */ + SOF_IPC4_PIPELINE_STATE_UNINITIALIZED = 1, /**< Created but module initialization is incomplete. */ + SOF_IPC4_PIPELINE_STATE_RESET = 2, /**< Reset state: buffers cleared, hardware inactive. */ + SOF_IPC4_PIPELINE_STATE_PAUSED = 3, /**< Paused state: buffers pre-allocated, clocks armed. */ + SOF_IPC4_PIPELINE_STATE_RUNNING = 4, /**< Running state: audio streaming actively scheduled. */ + SOF_IPC4_PIPELINE_STATE_EOS = 5, /**< End Of Stream (EOS): draining final buffered audio. */ + SOF_IPC4_PIPELINE_STATE_ERROR_STOP, /**< Pipeline halted due to unrecoverable DSP error. */ + SOF_IPC4_PIPELINE_STATE_SAVED /**< Pipeline context serialized to host memory for D3. */ }; -/* IDs for all pipeline ext data types in struct ipc4_pipeline_init_ext_object */ +/** + * \brief Extended pipeline object type identifiers. + * \ingroup ipc4_pipeline_api + */ enum ipc4_pipeline_ext_obj_id { - IPC4_GLB_PIPE_EXT_OBJ_ID_INVALID = 0, - IPC4_GLB_PIPE_EXT_OBJ_ID_MEM_DATA = 1, - IPC4_GLB_PIPE_EXT_OBJ_ID_MAX = IPC4_GLB_PIPE_EXT_OBJ_ID_MEM_DATA, + IPC4_GLB_PIPE_EXT_OBJ_ID_INVALID = 0, /**< Invalid extension object identifier. */ + IPC4_GLB_PIPE_EXT_OBJ_ID_MEM_DATA = 1, /**< Pipeline memory stack/heap allocation parameters. */ + IPC4_GLB_PIPE_EXT_OBJ_ID_MAX = IPC4_GLB_PIPE_EXT_OBJ_ID_MEM_DATA, /**< Maximum extension object ID. */ }; -/* data object for vendor bespoke data with ABI growth and backwards compat */ +/** + * \brief Header for extended pipeline initialization objects. + * \ingroup ipc4_pipeline_api + */ struct ipc4_pipeline_ext_object { - uint32_t last_object : 1; /* object is last in array if 1 else object follows. */ - uint32_t object_id : 15; /* unique ID for this object or globally */ - uint32_t object_words : 16; /* size in dwords (excluding this structure) */ + uint32_t last_object : 1; /**< 1 if terminating object in array, 0 if another object follows. */ + uint32_t object_id : 15; /**< Unique object identifier (enum ipc4_pipeline_ext_obj_id). */ + uint32_t object_words : 16; /**< Payload size in 32-bit DWORDs following this header. */ } __packed __aligned(4); -/* the object data will be placed in memory here and will have size "object_words" */ -/* Ext array data object for pipeline instance's memory requirements */ +/** + * \brief Memory allocation parameters for pipeline execution context. + * \ingroup ipc4_pipeline_api + */ struct ipc4_pipeline_ext_obj_mem_data { - uint32_t domain_id; /* userspace domain ID */ - uint32_t stack_bytes; /* required stack size in bytes */ - uint32_t heap_bytes; /* required heap size in bytes */ + uint32_t domain_id; /**< Userspace domain identifier. */ + uint32_t stack_bytes; /**< Stack size in bytes required for pipeline thread. */ + uint32_t heap_bytes; /**< Heap memory size in bytes required for pipeline graph. */ } __packed __aligned(4); -/* - * Host Driver sends this message to create a new pipeline instance. +/** + * \brief Container for extended pipeline creation payload. + * \ingroup ipc4_pipeline_api */ struct ipc4_pipeline_ext_payload { - uint32_t payload_words : 24; /* size in dwords (excluding this structure) */ - uint32_t data_obj_array : 1; /* struct ipc4_pipeline_ext_object data */ - uint32_t rsvd0 : 7; - uint32_t rsvd1; - uint32_t rsvd2; + uint32_t payload_words : 24; /**< Total payload size in 32-bit DWORDs. */ + uint32_t data_obj_array : 1; /**< 1 if struct ipc4_pipeline_ext_object array follows. */ + uint32_t rsvd0 : 7; /**< Reserved bits. */ + uint32_t rsvd1; /**< Reserved word. */ + uint32_t rsvd2; /**< Reserved word. */ } __packed __aligned(4); -/*! - * lp - indicates whether the pipeline should be kept on running in low power - * mode. On BXT the driver should set this flag to 1 for WoV pipeline. - * - * \remark hide_methods +/** + * \brief Pipeline creation command structure (SOF_IPC4_GLB_CREATE_PIPELINE). + * \ingroup ipc4_pipeline_api */ struct ipc4_pipeline_create { - union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< # pages for pipeline */ - uint32_t ppl_mem_size : 11; - /**< priority - uses enum ipc4_pipeline_priority */ - uint32_t ppl_priority : 5; - /**< pipeline id */ - uint32_t instance_id : 8; - /**< Global::CREATE_PIPELINE */ - uint32_t type : 5; - /**< Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /**< Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t ppl_mem_size : 11; /**< Number of 4KB memory pages allocated for pipeline. */ + uint32_t ppl_priority : 5; /**< Scheduling priority (enum ipc4_pipeline_priority). */ + uint32_t instance_id : 8; /**< Pipeline instance identifier (0..max_ppl-1). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_CREATE_PIPELINE (17). */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 0 for global firmware message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } primary; union{ - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< 1 - is low power */ - uint32_t lp : 1; - uint32_t rsvd1 : 3; - uint32_t attributes : 16; - uint32_t core_id : 4; - uint32_t rsvd2 : 5; - uint32_t payload : 1; - uint32_t _reserved_2 : 2; + uint32_t lp : 1; /**< 1 = low power pipeline (kept running during D0i3). */ + uint32_t rsvd1 : 3; /**< Reserved bits. */ + uint32_t attributes : 16; /**< Pipeline hardware attributes bitmask. */ + uint32_t core_id : 4; /**< Target DSP core ID hosting this pipeline. */ + uint32_t rsvd2 : 5; /**< Reserved bits. */ + uint32_t payload : 1; /**< 1 if struct ipc4_pipeline_ext_payload follows. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); -/*! - * SW Driver sends this IPC message to delete a pipeline from ADSP memory. - * - * All module instances and tasks that are associated with the pipeline are - * deleted too. - * - * There must be no existing binding from any pipeline's module instance - * to another pipeline to complete the command successfully. +/** + * \brief Pipeline deletion command structure (SOF_IPC4_GLB_DELETE_PIPELINE). + * \ingroup ipc4_pipeline_api * - * \remark hide_methods + * Deletes a pipeline and all its associated child module instances from DSP memory. + * All external cross-pipeline bindings must be severed prior to issuing delete. */ struct ipc4_pipeline_delete { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - uint32_t rsvd0 : 16; - /**< Ppl instance id */ - uint32_t instance_id : 8; - /**< Global::DELETE_PIPELINE */ - uint32_t type : 5; - /**< Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /**< Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t rsvd0 : 16; /**< Reserved padding. */ + uint32_t instance_id : 8; /**< Pipeline instance identifier to delete. */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_DELETE_PIPELINE (18). */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 0 for global firmware message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } primary; union{ - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - uint32_t rsvd1 : 30; - uint32_t _reserved_2 : 2; + uint32_t rsvd1 : 30; /**< Reserved padding. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); @@ -210,244 +190,231 @@ struct ipc4_pipeline_delete { * * \remark hide_methods */ +/** + * \brief Payload array containing pipeline IDs for multi-pipeline state transitions. + * \ingroup ipc4_pipeline_api + */ struct ipc4_pipeline_set_state_data { - /**< Number of items in ppl_id[] */ - uint32_t pipelines_count; - /**< Pipeline ids */ - uint32_t ppl_id[]; + uint32_t pipelines_count; /**< Number of pipeline instance IDs in ppl_id[]. */ + uint32_t ppl_id[]; /**< Array of pipeline instance identifiers. */ } __attribute__((packed, aligned(4))); +/** + * \brief Pipeline state transition command structure (SOF_IPC4_GLB_SET_PIPELINE_STATE). + * \ingroup ipc4_pipeline_api + * + * Directs one or more pipelines to transition their operational state (e.g. RESET -> PAUSED -> RUNNING). + * For multi-pipeline audio chains, drivers must start pipelines in reverse topological order + * (from output gateway backwards to input) to prevent intermediate buffer overruns. + */ struct ipc4_pipeline_set_state { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< new state, one of enum ipc4_pipeline_state */ + /**< Target pipeline state (enum ipc4_pipeline_state). */ uint32_t ppl_state : 16; - /**< pipeline instance id (ignored if multi_ppl =1) */ + /**< Target pipeline ID (ignored if multi_ppl == 1). */ uint32_t ppl_id : 8; - /**< Global::SET_PIPELINE_STATE */ + /**< Opcode: SOF_IPC4_GLB_SET_PIPELINE_STATE (19). */ uint32_t type : 5; - /**< Msg::MSG_REQUEST */ + /**< Direction: 0 for request. */ uint32_t rsp : 1; - - /**< Msg::FW_GEN_MSG */ + /**< Target: 0 for global firmware message. */ uint32_t msg_tgt : 1; - uint32_t _reserved_0: 1; + uint32_t _reserved_0: 1; /**< Reserved bit. */ } r; } primary; union{ - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< = 1 if there are more pipeline ids in payload */ + /**< 1 if additional pipeline IDs are provided in s_data payload. */ uint32_t multi_ppl : 1; - /**< = 1 if FW should sync state change across multiple ppls */ + /**< 1 if DSP should synchronize state transition across all pipelines. */ uint32_t sync_stop_start : 1; - uint32_t rsvd1 : 28; - uint32_t _reserved_2: 2; + uint32_t rsvd1 : 28; /**< Reserved padding. */ + uint32_t _reserved_2: 2; /**< Reserved bits. */ } r; } extension; - /* multiple pipeline states */ - struct ipc4_pipeline_set_state_data s_data; + struct ipc4_pipeline_set_state_data s_data; /**< Optional multi-pipeline ID list. */ } __attribute__((packed, aligned(4))); -/**< Reply to Set Pipeline State */ -/*! - * In case of error, there is failed pipeline id reported back. - * - \remark hide_methods -*/ +/** + * \brief Reply structure for pipeline state transition. + * \ingroup ipc4_pipeline_api + */ struct ipc4_pipeline_set_state_reply { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< status */ - uint32_t status : IPC4_IXC_STATUS_BITS; - /**< Global::SET_PIPELINE_STATE */ - uint32_t type : 5; - /**< Msg::MSG_REPLY */ - uint32_t rsp : 1; - /**< Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0: 1; + uint32_t status : IPC4_IXC_STATUS_BITS; /**< Status code (enum ipc4_status). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_SET_PIPELINE_STATE. */ + uint32_t rsp : 1; /**< 1 for reply. */ + uint32_t msg_tgt : 1; /**< 0 for global message. */ + uint32_t _reserved_0: 1; /**< Reserved bit. */ } r; } primary; union{ - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< id of failed pipeline on error */ + /**< ID of failed pipeline on error. */ uint32_t ppl_id : 30; - uint32_t _reserved_2: 2; + uint32_t _reserved_2: 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); -/**< This IPC message is sent to the FW in order to retrieve a pipeline state. */ -/*! \remark hide_methods */ +/** + * \brief Query pipeline current state command (SOF_IPC4_GLB_GET_PIPELINE_STATE). + * \ingroup ipc4_pipeline_api + */ struct ipc4_pipeline_get_state { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< pipeline id */ - uint32_t ppl_id : 8; - uint32_t rsvd : 16; - /**< Global::GET_PIPELINE_STATE */ - uint32_t type : 5; - /**< Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /**< Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0: 1; - } r; + uint32_t ppl_id : 8; /**< Target pipeline instance identifier. */ + uint32_t rsvd : 16; /**< Reserved padding. */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_GET_PIPELINE_STATE (20). */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 0 for global message. */ + uint32_t _reserved_0: 1; /**< Reserved bit. */ + } r; } primary; union{ - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - uint32_t rsvd1 : 30; - uint32_t _reserved_2: 2; + uint32_t rsvd1 : 30; /**< Reserved padding. */ + uint32_t _reserved_2: 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); -/**< Sent by the FW in response to GetPipelineState. */ -/*! \remark hide_methods */ +/** + * \brief Reply structure containing pipeline current operational state. + * \ingroup ipc4_pipeline_api + */ struct ipc4_pipeline_get_state_reply { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< status */ - uint32_t status :IPC4_IXC_STATUS_BITS; - /**< Global::GET_PIPELINE_STATE */ - uint32_t type : 5; - /**< Msg::MSG_REPLY */ - uint32_t rsp : 1; - /**< Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0: 1; + uint32_t status : IPC4_IXC_STATUS_BITS; /**< Status code (enum ipc4_status). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_GET_PIPELINE_STATE. */ + uint32_t rsp : 1; /**< 1 for reply. */ + uint32_t msg_tgt : 1; /**< 0 for global message. */ + uint32_t _reserved_0: 1; /**< Reserved bit. */ } r; } primary; union{ - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< one of PipelineState */ + /**< Current state (one of enum ipc4_pipeline_state). */ uint32_t state : 5; - uint32_t rsvd1 : 25; - uint32_t _reserved_2: 2; + uint32_t rsvd1 : 25; /**< Reserved padding. */ + uint32_t _reserved_2: 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); -/*! - * The size is expressed in number of pages. It is a total number of memory pages - * allocated for pipeline memory buffer and all separately allocated child - * module instances. - * - * \remark hide_methods +/** + * \brief Query memory context size required to serialize pipeline (SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE). + * \ingroup ipc4_pipeline_api */ struct ipc4_pipeline_get_context_size { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - uint32_t rsvd0 : 16; - /**< pipeline id */ - uint32_t instance_id : 8; - /**< Global::GET_PIPELINE_CONTEXT_SIZE */ - uint32_t type : 5; - /**< Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /**< Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t rsvd0 : 16; /**< Reserved padding. */ + uint32_t instance_id : 8; /**< Target pipeline instance ID. */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE (21). */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 0 for global message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } primary; union{ - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - uint32_t rsvd1 : 30; - uint32_t _reserved_2 : 2; + uint32_t rsvd1 : 30; /**< Reserved padding. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); -/**< Reply to Get Pipeline Context Size. */ -/*! \remark hide_methods */ +/** + * \brief Reply structure for pipeline context size query. + * \ingroup ipc4_pipeline_api + */ struct ipc4_pipeline_get_context_size_reply { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< status */ - uint32_t status :IPC4_IXC_STATUS_BITS; - /**< Global::GET_PIPELINE_CONTEXT_SIZE */ - uint32_t type : 5; - /**< Msg::MSG_REPLY */ - uint32_t rsp : 1; - /**< Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0: 1; + uint32_t status : IPC4_IXC_STATUS_BITS; /**< Status code (enum ipc4_status). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE. */ + uint32_t rsp : 1; /**< 1 for reply. */ + uint32_t msg_tgt : 1; /**< 0 for global message. */ + uint32_t _reserved_0: 1; /**< Reserved bit. */ } r; } primary; union{ - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< size of pipeline context (in number of pages) */ + /**< Size of pipeline serialization context in 4KB memory pages. */ uint32_t ctx_size : 16; - uint32_t rsvd1 : 14; - uint32_t _reserved_2: 2; + uint32_t rsvd1 : 14; /**< Reserved padding. */ + uint32_t _reserved_2: 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); +/** + * \brief Direct DMA Chaining configuration command (SOF_IPC4_GLB_CHAIN_DMA). + * \ingroup ipc4_pipeline_api + */ struct ipc4_chain_dma { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - uint32_t host_dma_id : 5; - uint32_t rsvd4 : 3; - uint32_t link_dma_id : 5; - uint32_t rsvd3 : 3; - /* allocate buffer specified by FIFO size */ - uint32_t allocate : 1; - uint32_t enable : 1; - /* controls SCS bit in both Host and Link gateway */ - uint32_t scs : 1; - uint32_t rsvd2 : 5; - /* Global::CHAIN_DMA */ - uint32_t type : 5; - /* Msg::MSG_REQUEST */ - uint32_t rsp : 1; - /* Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; + uint32_t host_dma_id : 5; /**< Host DMA channel identifier. */ + uint32_t rsvd4 : 3; /**< Reserved bits. */ + uint32_t link_dma_id : 5; /**< Link DMA channel identifier. */ + uint32_t rsvd3 : 3; /**< Reserved bits. */ + uint32_t allocate : 1; /**< Allocate FIFO buffer. */ + uint32_t enable : 1; /**< Enable DMA chaining. */ + uint32_t scs : 1; /**< Select stream context (SCS) bit in gateways. */ + uint32_t rsvd2 : 5; /**< Reserved bits. */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_CHAIN_DMA (14). */ + uint32_t rsp : 1; /**< 0 for request. */ + uint32_t msg_tgt : 1; /**< 0 for global message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; } primary; union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /* size of FIFO (bytes) */ - uint32_t fifo_size : 24; - uint32_t rsvd1 : 6; - uint32_t _reserved_2 : 2; + uint32_t fifo_size : 24; /**< Size of chaining FIFO buffer in bytes. */ + uint32_t rsvd1 : 6; /**< Reserved bits. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; } extension; } __attribute__((packed, aligned(4))); From 583d39f91bf29ec689226d75a368738781ec6844 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 13 Oct 2026 16:09:19 +0100 Subject: [PATCH 5/9] doc: ipc4: document base firmware parameters, hardware config, and performance metrics Signed-off-by: Liam Girdwood --- src/include/ipc4/base_fw.h | 957 ++++++++++++++---------------- src/include/ipc4/base_fw_vendor.h | 61 +- 2 files changed, 486 insertions(+), 532 deletions(-) diff --git a/src/include/ipc4/base_fw.h b/src/include/ipc4/base_fw.h index 354a7001cf33..6583365e755a 100644 --- a/src/include/ipc4/base_fw.h +++ b/src/include/ipc4/base_fw.h @@ -11,827 +11,762 @@ /** * \file include/ipc4/base_fw.h * \brief IPC4 Base Firmware parameters, memory configuration, and status definitions. - * \ingroup ipc4_api + * \ingroup ipc4_base_fw_api * NOTE: This ABI uses bit fields and is non portable. */ #ifndef __SOF_IPC4_BASE_FW_H__ #define __SOF_IPC4_BASE_FW_H__ -/* SOF FW performs autonomous management of clock sources. +/** + * \brief Clock states count. + * + * SOF FW performs autonomous management of clock sources. * Set MAX_CLK_STATES to 0 in order to propagate this information through IPC and thus * prevent reception of unsupported clock configuration. */ #define IPC4_MAX_CLK_STATES 0 -/* Max src queue count supported by ipc4 */ +/** \brief Maximum source queue count supported by IPC4. */ #define IPC4_MAX_SRC_QUEUE 8 -/* Max dst queue count supported by ipc4 */ +/** \brief Maximum destination queue count supported by IPC4. */ #define IPC4_MAX_DST_QUEUE 8 -/* Max module instance for single module count supported by ipc4 */ +/** \brief Maximum module instance count for a single module supported by IPC4. */ #define IPC4_MAX_MODULE_INSTANCES 256 -/* Max ll tasks for a schedule priority count supported by ipc4 */ +/** \brief Maximum low-latency tasks for a schedule priority count supported by IPC4. */ #define IPC4_MAX_LL_TASKS_PER_PRI_COUNT 16 -/* Max dp tasks count supported by ipc4 */ +/** \brief Maximum data-processing tasks count supported by IPC4. */ #define IPC4_MAX_DP_TASKS_COUNT 16 -/* Max external libraries count supported by ipc4 */ +/** \brief Maximum external libraries count supported by IPC4. */ #define IPC4_MAX_LIBS_COUNT 16 -/* Max pipeline count supported by ipc4 */ +/** \brief Maximum pipeline count supported by IPC4. */ #define IPC4_MAX_PPL_COUNT 32 +/** + * \brief IPC4 Base Firmware configuration and query parameter IDs. + * \ingroup ipc4_base_fw_api + * + * Parameter IDs used with LARGE_CONFIG_GET and LARGE_CONFIG_SET commands + * addressed to the Base FW module instance (module ID 0, instance ID 0). + */ enum ipc4_basefw_params { - /* Use LARGE_CONFIG_GET to retrieve fw properties as TLV structure - * with typeof AdspProperties. + /** + * Retrieve firmware properties as TLV structure with typeof AdspProperties + * via LARGE_CONFIG_GET. */ IPC4_DSP_PROPERTIES = 0, + /** Retrieve DSP resource state via LARGE_CONFIG_GET. */ IPC4_DSP_RESOURCE_STATE = 1, + /** Reserved parameter identifier. */ IPC4_RESERVED = 2, - /* Driver sends this request to enable/disable notifications. This message - * should be used by the driver in debug mode to avoid flooding host with - * underrun notifications when driver is stopped by breakpoint for example. + /** + * Enable or disable asynchronous notifications. Used in debug mode + * to prevent flooding the host with underrun notifications during breakpoints. */ IPC4_NOTIFICATION_MASK = 3, - /* Driver sends A-State Table data right after the Base FW is up and ready to - * handle IPC communication. The table is forwarded to the Power Manager to - * configure available power states according to the underlying platform. + /** + * Configure available power states according to the underlying platform. + * Driver sends A-State table data right after Base FW is up. */ IPC4_ASTATE_TABLE = 4, - /* Driver sends the DMA Control parameter in order to initialize or modify - * DMA gateway configuration outside of a stream lifetime. Typically a DMA - * gateway is initialized during pipeline creation when a Copier module is - * instantiated and attached to that gateway. Similarly the gateway is - * de-initialized when the Copiers parent pipeline is being destroyed. - * However sometimes the driver may want to control the gateway before or - * after a stream is being attached to it. - * - * The data of DMA Control parameter starts with DmaControl structure - * optionally followed by the target gateway specific data (that may consist - * of two parts, the former coming from NHLT BIOS tables and the latter - * aux_config in form of TLV list provided by the driver). + /** + * Initialize or modify DMA gateway configuration outside stream lifetime. + * Starts with struct ipc4_dma_control followed by optional gateway-specific data. */ IPC4_DMA_CONTROL = 5, - /* Driver sets this parameter to control state of FW logging. Driver may - * enable logging for each core and specify logging level. Driver also - * configures period of aging and FIFO full timers. Aging timer period - * specifies how frequently FW sends Log Buffer Status notification for new - * entries in case the usual notification sending criteria are not met - * (half of the buffer is full). Fifo full timer period specifies the latency - * of logging "dropped log entries" information after the content is consumed - * by the driver but no new log entry appears (which would trigger logging - * "dropped entries" as well). - * - * SystemTime property must be provided by the driver prior to enabling - *the logs for the first time, otherwise error is raised by FW since - * it will not be able to translate log event timestamps into the host - * CPU clock domain. - * - * Log FIFO content is reset on logs enabled by the driver, so the RP - * is expected to be 0, however the driver should not assume that value - * but just read the RP from FW Registers instead. + /** + * Configure firmware logging state (enable/disable per core, log level, + * aging timer, FIFO full timer). */ IPC4_ENABLE_LOGS = 6, - /* Use LARGE_CONFIG_SET/LARGE_CONFIG_GET to write/read FW configuration. - * - * Driver requests value of this Base FW property to discover FW configuration. - * Configuration data is returned in form of TLV list and contains items as - * defined in the next table. - * - * Driver may also set values of parameters that are marked as RW in the table. - * FirmwareConfig is expected to be queried/set once at the FW - * initialization time. Properties that are expected to be changed more - * frequently (e.g. current number of modules descriptors loaded or - * performance measurements state) are moved and became separate - * parameters. + /** + * Discover or set firmware configuration in TLV format (read/write + * via LARGE_CONFIG_GET / LARGE_CONFIG_SET). */ IPC4_FW_CONFIG = 7, - /* Use LARGE_CONFIG_GET to read HW configuration. - * - * Driver requests value of this Base FW property to discover underlying HW - * configuration. Configuration data is returned in form of TLV list. + /** + * Discover underlying hardware configuration in TLV format + * via LARGE_CONFIG_GET. */ IPC4_HW_CONFIG_GET = 8, - /* Use LARGE_CONFIG_GET to read modules configuration. - * - * Driver requests value of this Base FW property to retrieve list of the - * module entries loaded into the FW memory space (as part of either the - * image manifest or library manifest). - * - * The response may be too large to fit into a single message. The driver - * must be prepared to handle multiple fragments. + /** + * Retrieve list of module entries loaded into firmware memory space + * (image manifest or library manifest) via LARGE_CONFIG_GET. */ IPC4_MODULES_INFO_GET = 9, - /* Use LARGE_CONFIG_GET to read pipeline list. - * - * Driver requests value of this Base FW property to retrieve list of - * pipelines IDs. Once the list is received driver may retrieve properties of - * each pipeline by querying Pipeline Info specifying IDs from the list. - */ + /** Retrieve list of instantiated pipeline IDs via LARGE_CONFIG_GET. */ IPC4_PIPELINE_LIST_INFO_GET = 10, - /* Use LARGE_CONFIG_GET to read pipelines properties. - * - * Driver requests value of this Base FW property to retrieve properties of a - * pipeline. Full parameter id wrapped by APPLICATION_PARAM into the request - * payload is of ExtendedParameterId type where parameter_type is set to - * PIPELINE_PROPS and parameter_instance is set to the target pipeline id. - * - * Properties of a single pipeline are expected to fit into a single IPC - * response as there is a room for ~1K of IDs of tasks and modules instances. + /** + * Retrieve pipeline properties for a given pipeline ID + * via LARGE_CONFIG_GET. */ IPC4_PIPELINE_PROPS_GET = 11, - /* Use SCHEDULERS_INFO_GET to read schedulers configuration. - * - * Driver requests value of this Base FW property to retrieve list of task - * schedulers and tasks created inside the FW and being executed on a core. - * Full parameter id wrapped by APPLICATION_PARAM into the request payload - * is of ExtendedParameterId type where parameter_type is set to - * SCHEDULERS_INFO and parameter_instance is set to the target core id. + /** + * Retrieve list of task schedulers and tasks running on a core + * via LARGE_CONFIG_GET. */ IPC4_SCHEDULERS_INFO_GET = 12, - /* Use LARGE_CONFIG_GET to read gateway configuration */ + /** Retrieve gateway configuration information via LARGE_CONFIG_GET. */ IPC4_GATEWAYS_INFO_GET = 13, - /* Use LARGE_CONFIG_GET to get information on memory state. - * - * Driver requests value of this Base FW property to retrieve information - * about current DSP memory state. Configuration data is returned in form of - * TLV list and contains items as defined in the next table. - */ + /** Retrieve information about current DSP memory state via LARGE_CONFIG_GET. */ IPC4_MEMORY_STATE_INFO_GET = 14, - /* Use LARGE_CONFIG_GET to get information on power state. - * - * Driver requests value of this Base FW property to retrieve information - * about current DSP power state. Configuration data is returned in form of - * TLV list and contains items as defined in the next table. - */ + /** Retrieve information about current DSP power state via LARGE_CONFIG_GET. */ IPC4_POWER_STATE_INFO_GET = 15, - /* Use LARGE_CONFIG_GET to get information about libraries - * loaded into the ADSP memory. - */ + /** Retrieve information about external libraries loaded into DSP memory. */ IPC4_LIBRARIES_INFO_GET = 16, - /* Use LARGE_CONFIG_SET to set value of this Base FW property to control - * performance measurements state. There is one global flag that controls the - * state of performance measurements process globally. - * - * Driver may set value of this Base FW property to control state of - * performance measurements process in the DSP FW. - * - * This state is applied to MCPS monitoring only. Memory allocation - * state is always available. - */ + /** Control global performance measurement state (MCPS monitoring). */ IPC4_PERF_MEASUREMENTS_STATE = 17, - /* Use LARGE_CONFIG_GET to retrieve retrieve global performance data. FW - * sends a list of captured performance data per enabled core and power mode. - * MCPS are sampled each DSP system tick (1ms in D0) and used to compute peak - * and average values. - * - * Driver requests value of this Base FW property to retrieve performance data - * captured on the DSP. FW sends a list of items reported by FW components. - * KCPS are sampled either each DSP system tick (1ms in D0) for low latency - * and infrastructure components, or each processed frame otherwise. The KCPS - * are used to compute reported peak and average values by FW. - * - * Data items reported for resource_id = {module_id = 0, instance_id = - * core_id} contain total KCPS spent on each active core. - * - *This parameter reports only KCPS, while the memory state is reported - * by Memory State Info parameter. - */ + /** Retrieve global performance data (KCPS sampled per tick/frame). */ IPC4_GLOBAL_PERF_DATA = 18, - /* Use LARGE_CONFIG_GET to get information on l2 cache state. - * - * Driver requests value of this Base FW property to retrieve information - * about current state of L2 Cache. Available on platforms where L2 cache is - * in use, otherwise ADSP_IPC_UNAVAILABLE is returned. - */ + /** Retrieve L2 cache state information. */ IPC4_L2_CACHE_INFO_GET = 19, - /* Driver sets this property to pass down information about host system time. - * - * Driver sets this property to pass down information about current system - * time. It is used by FW to translate event timestamps (Logs, Probes packets - * for example) to the system time (current host time) domain. - * - * The value of system time is expressed in us - * Time is in UTC - * Epoch is 1601-01-01T00:00:00Z + /** + * Pass down host system time in microseconds (UTC, epoch 1601-01-01T00:00:00Z) + * to synchronize log and trace timestamps. */ IPC4_SYSTEM_TIME = 20, - /* Use LARGE_CONFIG_SET to configure firmware for performance */ + /** Configure firmware for performance mode via LARGE_CONFIG_SET. */ IPC4_PERFORMANCE_CONFIGURATION = 21, - /* Use LARGE_CONFIG_SET to register KCPS into power manager - * service per core 0. Negative numbers are allowed. - */ + /** Register KCPS into power manager service per core 0 (negative values allowed). */ IPC4_REGISTER_KCPS = 22, - /* Use LARGE_CONFIG_SET to request additional resource allocation */ + /** Request additional resource allocation via LARGE_CONFIG_SET. */ IPC4_RESOURCE_ALLOCATION_REQUEST = 23, - /* Driver may set value of this Base FW property to control state of - * I/o performance measurements process in the DSP FW. - */ + /** Control I/O performance measurement state in firmware. */ IPC4_IO_PERF_MEASUREMENTS_STATE = 24, - /* The command returns I/O statistics when they are enabled */ + /** Retrieve I/O global performance statistics. */ IPC4_IO_GLOBAL_PERF_DATA = 25, - /* The command is shorter version of Modules Info command. - * It is used to retrieve module ID for a specified module UUID. - */ + /** Retrieve module ID for a specified module UUID. */ IPC4_GET_MODULE_ID = 26, - /* EXTENDED_SYSTEM_TIME command returns current value of UTC, RTC and HH. - * The system time must be set first via SYSTEM_TIME command before - * EXTENDED_SYSTEM_TIME can be used. - */ + /** Retrieve current UTC, RTC, and ART timestamps (requires SYSTEM_TIME set first). */ IPC4_EXTENDED_SYSTEM_TIME = 27, - /* Driver may set value of this Base FW property to control state - * of telemetry collection process in the DSP FW. - * In started state, TELEMETRY_STATE command is used to change threshold - * and aging timer depend on system state. - */ + /** Control telemetry collection process state and thresholds. */ IPC4_TELEMETRY_STATE = 28, - /* The command to read data from the telemetry circular buffer. - * The telemetry data can be produced by firmware modules using - * System Service APIand then all telemetry is collected via one - * common mechanism provided by the base firmware. - */ + /** Read data from circular telemetry buffer. */ IPC4_TELEMETRY_DATA = 29, - /* This command is extended version of Global Performance Data which - * provides more details information about total number of - * cycles consumed by each of the modules. - */ + /** Extended global performance data with per-module DSP cycle statistics. */ IPC4_EXTENDED_GLOBAL_PERF_DATA = 30, - /* Use LARGE_CONFIG_SET to change SDW ownership */ - IPC4_SDW_OWNERSHIP = 31, + /** Configure SoundWire controller ownership via LARGE_CONFIG_SET. */ + IPC4_SDW_OWNERSHIP = 31, - /* This command is used by SW to notify FW for changing state of Mic Privacy */ + /** Notify firmware of hardware-managed microphone privacy state change. */ IPC4_MIC_PRIVACY_HW_MANAGED_STATE_CHANGE = 35, - /* Set policy mask for mic privacy in FW managed mode */ + /** Set policy mask for microphone privacy in firmware-managed mode. */ IPC4_SET_MIC_PRIVACY_FW_MANAGED_POLICY_MASK = 36, }; +/** + * \brief Firmware configuration parameter TLV IDs returned by IPC4_FW_CONFIG. + * \ingroup ipc4_base_fw_api + */ enum ipc4_fw_config_params { - /* Firmware version */ + /** Firmware version. */ IPC4_FW_VERSION_FW_CFG = 0, - /* Indicates whether legacy DMA memory is managed by FW */ + /** Indicates whether legacy DMA memory is managed by FW. */ IPC4_MEMORY_RECLAIMED_FW_CFG = 1, - /* Frequency of oscillator clock */ + /** Frequency of oscillator clock in Hz. */ IPC4_SLOW_CLOCK_FREQ_HZ_FW_CFG = 2, - /* Frequency of PLL clock */ + /** Frequency of PLL clock in Hz. */ IPC4_FAST_CLOCK_FREQ_HZ_FW_CFG = 3, - /* List of static and dynamic DMA buffer sizes. - * SW may configure minimum and maximum size for each buffer. + /** + * List of static and dynamic DMA buffer sizes. + * Host software may configure minimum and maximum size for each buffer. */ IPC4_DMA_BUFFER_CONFIG_FW_CFG = 4, - /* Audio Hub Link support level. - * Note: Lower 16-bits may be used in future to indicate - * implementation revision if necessary. + /** + * Audio Hub Link (ALH) support level. + * Lower 16 bits may indicate implementation revision. */ IPC4_ALH_SUPPORT_LEVEL_FW_CFG = 5, - /* Size of IPC downlink mailbox */ - IPC4_DL_MAILBOX_BYTES_FW_CFG = 6, - /* Size of IPC uplink mailbox */ - IPC4_UL_MAILBOX_BYTES_FW_CFG = 7, - /* Size of trace log buffer */ + /** Size of IPC downlink mailbox in bytes. */ + IPC4_DL_MAILBOX_BYTES_FW_CFG = 6, + /** Size of IPC uplink mailbox in bytes. */ + IPC4_UL_MAILBOX_BYTES_FW_CFG = 7, + /** Size of trace log buffer in bytes. */ IPC4_TRACE_LOG_BYTES_FW_CFG = 8, - /* Maximum number of pipelines that may be instantiated at the same time */ + /** Maximum number of pipelines that may be instantiated simultaneously. */ IPC4_MAX_PPL_CNT_FW_CFG = 9, - /* Maximum number of A-state table entries that may be configured by the driver. - * Driver may also use this value to estimate the size of data retrieved as - * ASTATE_TABLE property. + /** + * Maximum number of A-state table entries that may be configured by the driver. + * Driver may use this value to estimate the size of ASTATE_TABLE data. */ IPC4_MAX_ASTATE_COUNT_FW_CFG = 10, - /* Maximum number of input or output pins supported by a module */ + /** Maximum number of input or output pins supported by a module. */ IPC4_MAX_MODULE_PIN_COUNT_FW_CFG = 11, - /* Current total number of module entries loaded into the DSP */ + /** Current total number of module entries loaded into the DSP. */ IPC4_MODULES_COUNT_FW_CFG = 12, - /* Maximum number of module instances supported by FW */ + /** Maximum number of module instances supported by FW. */ IPC4_MAX_MOD_INST_COUNT_FW_CFG = 13, - /* Maximum number of LL tasks that may be allocated with - * the same priority (specified by a priority of the parent pipeline). + /** + * Maximum number of LL tasks that may be allocated with + * the same priority (specified by parent pipeline priority). */ IPC4_MAX_LL_TASKS_PER_PRI_COUNT_FW_CFG = 14, - /* Number of LL priorities */ + /** Number of Low Latency (LL) scheduling priorities. */ IPC4_LL_PRI_COUNT = 15, - /* Maximum number of DP tasks that may be allocated on a single core */ + /** Maximum number of DP tasks that may be allocated on a single core. */ IPC4_MAX_DP_TASKS_COUNT_FW_CFG = 16, - /* Maximum number of libraries that can be loaded into the ADSP memory */ + /** Maximum number of external libraries that can be loaded into ADSP memory. */ IPC4_MAX_LIBS_COUNT_FW_CFG = 17, - /* Configuration of system tick source and period */ + /** Configuration of system tick source and period. */ IPC4_SCHEDULER_CONFIGURATION = 18, - /* Frequency of xtal oscillator clock */ + /** Frequency of XTAL oscillator clock in Hz. */ IPC4_XTAL_FREQ_HZ_FW_CFG = 19, - /* Configuration of clocks */ + /** Configuration of clocks. */ IPC4_CLOCKS_CONFIGURATION = 20, - /* USB Audio Offload support */ + /** USB Audio Offload (UAOL) support indicator. */ IPC4_UAOL_SUPPORT = 21, - /* Configuration of Dynamic Power Gating Policy */ + /** Configuration of Dynamic Power Gating Policy. */ IPC4_POWER_GATING_POLICY = 22, - /* Configuration of assert mode - * Run-time asserts requires special handling by decoder. - * Asserts will be in format: "%passert", ptr_to_assert_desc. - * - * ptr_to_assert_desc will point to place in .asserts_desc section in ELF. - * Data must be cased to struct: struct assert_entry + /** + * Configuration of assert mode. + * Asserts use format "%passert", ptr_to_assert_desc in .asserts_desc section. */ IPC4_ASSERT_MODE = 23, - /* Size of telemetry buffer in bytes. The default size is 4KB */ - IPC4_TELEMETRY_BUFFER_SIZE = 24, - /* HW version information */ - IPC4_BUS_HARDWARE_ID = 25, - /* Total memory size available in debug window */ - IPC4_DEBUG_WINDOW_SIZE = 26, - /* Number of realtime Key Phrase Buffer (KPB) output pins */ - IPC4_KPB_RT_SINK_COUNT = 27, - /* Manual control of DMI L1 state */ - IPC4_DMI_FORCE_L1_EXIT = 28, - /* FW context save on D3 entry */ - IPC4_FW_CONTEXT_SAVE = 29, - /* Minimum size of host buffer in ms */ - IPC4_FW_MIN_HOST_BUFFER_PERIODS = 33, - /* decoder/encoder codec information */ - IPC4_FW_SOF_INFO = 35, - /* Total number of FW config parameters */ + /** Size of telemetry circular buffer in bytes (default 4KB). */ + IPC4_TELEMETRY_BUFFER_SIZE = 24, + /** Hardware version and bus hardware identifier. */ + IPC4_BUS_HARDWARE_ID = 25, + /** Total memory size available in debug window. */ + IPC4_DEBUG_WINDOW_SIZE = 26, + /** Number of real-time Key Phrase Buffer (KPB) output sink pins. */ + IPC4_KPB_RT_SINK_COUNT = 27, + /** Manual control of DMI L1 state exit. */ + IPC4_DMI_FORCE_L1_EXIT = 28, + /** Firmware context save on D3 power state entry. */ + IPC4_FW_CONTEXT_SAVE = 29, + /** Minimum size of host buffer in milliseconds. */ + IPC4_FW_MIN_HOST_BUFFER_PERIODS = 33, + /** SOF specific decoder/encoder codec information. */ + IPC4_FW_SOF_INFO = 35, + /** Total number of FW config parameters. */ IPC4_FW_CFG_PARAMS_COUNT, - /* Max config parameter id */ + /** Maximum FW config parameter ID value. */ IPC4_MAX_FW_CFG_PARAM = IPC4_FW_CFG_PARAMS_COUNT - 1, }; -/* - * tuple based array for SOF specific information under IPC4_FW_SOF_INFO - * tuple of fw_config +/** + * \brief Tuple-based parameters for SOF specific info under IPC4_FW_SOF_INFO. + * \ingroup ipc4_base_fw_api */ enum ipc4_fw_sof_info_params { - /* decoder/encoder codec information */ + /** Decoder/encoder codec information. */ IPC4_SOF_CODEC_INFO = 0, - /* Total number of SOF config parameters */ + /** Total number of SOF config parameters. */ IPC4_SOF_CFG_PARAMS_COUNT, - /* Max config parameter id */ + /** Maximum SOF config parameter ID value. */ IPC4_MAX_SOF_CFG_PARAM = IPC4_SOF_CFG_PARAMS_COUNT - 1, }; +/** + * \brief Hardware configuration parameter TLV IDs returned by IPC4_HW_CONFIG_GET. + * \ingroup ipc4_base_fw_api + */ enum ipc4_hw_config_params { - /* Version of cAVS implemented by FW (from ROMInfo) */ + /** Version of CAVS/ACE architecture implemented by FW (from ROMInfo). */ IPC4_CAVS_VER_HW_CFG = 0, - /* How many dsp cores are available in current audio subsystem */ + /** Number of DSP cores available in the audio subsystem. */ IPC4_DSP_CORES_HW_CFG = 1, - /* Size of a single memory page */ + /** Size of a single memory page in bytes (typically 4096). */ IPC4_MEM_PAGE_BYTES_HW_CFG = 2, - /* Total number of physical pages available for allocation */ + /** Total number of physical memory pages available for allocation. */ IPC4_TOTAL_PHYS_MEM_PAGES_HW_CFG = 3, - /* - * Number of items in controller_base_addr array is specified by - * controller_count. note Lower 16 bits of I2sVersion may be used - * in future to indicate implementation revision if necessary. + /** + * I2S controller capabilities. Array count given by controller_count. + * Lower 16 bits may indicate implementation revision. */ IPC4_I2S_CAPS_HW_CFG = 4, - /* GPDMA capabilities */ + /** General Purpose DMA (GPDMA) controller capabilities. */ IPC4_GPDMA_CAPS_HW_CFG = 5, - /*Total number of DMA gateways of all types */ + /** Total number of DMA gateways of all types. */ IPC4_GATEWAY_COUNT_HW_CFG = 6, - /* Number of HP SRAM memory banks manageable by DSP */ - IPC4_HP_EBB_COUNT_HW_CFG = 7, - /* Number of LP SRAM memory banks manageable by DSP */ - IPC4_LP_EBB_COUNT_HW_CFG = 8, - /* Size of a single memory bank (EBB) in bytes */ - IPC4_EBB_SIZE_BYTES_HW_CFG = 9, - /* UAOL capabilities */ + /** Number of High Power (HP) SRAM memory banks (EBBs) manageable by DSP. */ + IPC4_HP_EBB_COUNT_HW_CFG = 7, + /** Number of Low Power (LP) SRAM memory banks (EBBs) manageable by DSP. */ + IPC4_LP_EBB_COUNT_HW_CFG = 8, + /** Size of a single memory bank (EBB) in bytes. */ + IPC4_EBB_SIZE_BYTES_HW_CFG = 9, + /** USB Audio Offload (UAOL) controller capabilities. */ IPC4_UAOL_CAPS_HW_CFG = 10, - /* Mic privacy capabilities */ + /** Microphone privacy hardware capabilities. */ IPC4_INTEL_MIC_PRIVACY_CAPS_HW_CFG = 11 }; +/** + * \brief SRAM power memory type. + * \ingroup ipc4_base_fw_api + */ enum ipc4_memory_type { - /* High power sram memory */ + /** High Power (HP) SRAM memory. */ IPC4_HP_SRAM_MEMORY = 0, - /*Low power sram memory */ + /** Low Power (LP) SRAM memory. */ IPC4_LP_SRAM_MEMORY = 1 }; +/** + * \brief DSP resource state request types. + * \ingroup ipc4_base_fw_api + */ enum ipc4_resource_state_request { - /* - * This type is used to inform about free physical HP sram memory pages - * available. - */ + /** Query free physical HP SRAM memory pages available. */ IPC4_FREE_PHYS_MEM_PAGES = 0 }; -/* PhysMemPages describes current free phys memory pages */ +/** + * \brief Free physical memory page descriptor. + * \ingroup ipc4_base_fw_api + */ struct ipc4_phys_mem_pages { - uint32_t mem_type; - /* Number of pages */ - uint32_t pages; + uint32_t mem_type; /**< Memory type (enum ipc4_memory_type). */ + uint32_t pages; /**< Number of free memory pages available. */ } __attribute__((packed, aligned(4))); +/** \brief Notification bit index: gateway underrun notification. */ #define IPC4_UNDERRUN_AT_GATEWAY_NOTIFICATION_MASK_IDX 0 +/** \brief Notification bit index: mixer underrun notification. */ #define IPC4_UNDERRUN_AT_MIXER_NOTIFICATION_MASK_IDX 1 +/** \brief Notification bit index: budget violation notification. */ #define IPC4_BUDGET_VIOLATION_NOTIFICATION_MASK_IDX 2 +/** \brief Notification bit index: gateway overrun notification. */ #define IPC4_OVERRUN_AT_GATEWAY_NOTIFICATION_MASK_IDX 3 +/** + * \brief Notification mask configuration structure (IPC4_NOTIFICATION_MASK). + * \ingroup ipc4_base_fw_api + */ struct ipc4_notification_mask_info { - /* Indicates which notifications are begin enabled/disabled */ + /** Bitmask indicating which notifications are being modified. */ uint32_t ntfy_mask; - /* Indicates if notifications indicated by corresponding bits in ntfy_mask - * are enabled (b'1) or disabled (b'0). + /** + * Bitmask indicating enable (1) or disable (0) state for notifications + * selected in ntfy_mask. */ uint32_t enabled_mask; } __attribute__((packed, aligned(4))); +/** + * \brief Hardware clock source selection. + * \ingroup ipc4_base_fw_api + */ enum ipc4_clock_src { - /* Low Power XTAL (oscillator) clock source */ + /** Low Power XTAL oscillator clock source. */ IPC4_CLOCK_SRC_XTAL = 0, - - /* Low Power Ring Oscillator */ + /** Low Power Ring Oscillator (RO). */ IPC4_CLOCK_SRC_LP_RING_OSC, - /* High Power Ring Oscillator */ + /** High Power Ring Oscillator (RO). */ IPC4_CLOCK_SRC_HP_RING_OSC, - /* Low Power XTAL (oscillator) clock source - * Frequency depends on platform. This XTAL is different from CLOCK_SRC_XTAL - * because it is generate in IP (not given from platform), saving more power. + /** + * Low Power Wake-on-Voice (WoV) XTAL oscillator. + * Generated internal to IP for optimal low-power listening. */ IPC4_CLOCK_SRC_WOV_XTAL, + /** Invalid clock source sentinel. */ IPC4_CLOCK_SRC_INVALID, + /** Maximum valid clock source index. */ IPC4_CLOCK_SRC_MAX_IDX = IPC4_CLOCK_SRC_INVALID - 1, }; +/** + * \brief A-State frequency and load threshold entry. + * \ingroup ipc4_base_fw_api + */ struct ipc4_astate { - /* Kilo Cycles Per Second. - * Specifies core load threshold (expressed in kilo cycles per second). When - * load is below this threshold DSP is clocked from source specified by clk_src. - * - * Configuring 0 kcps in the first entry means that this clock source will be - * used in idle state only. + /** + * Core load threshold in Kilo-Cycles Per Second (KCPS). + * Below this threshold DSP is clocked from source specified by clock_src. + * 0 KCPS indicates clock source used in idle state only. */ uint32_t kcps; - /* Clock source associated with kcps threshold */ + /** Clock source associated with kcps threshold (enum ipc4_clock_src). */ enum ipc4_clock_src clock_src; } __attribute__((packed, aligned(4))); -/* Power Manager Astate Table */ +/** + * \brief Power Manager A-State configuration table (IPC4_ASTATE_TABLE). + * \ingroup ipc4_base_fw_api + */ struct ipc4_astate_table { - /* Number of entries in astates_ array. The value does not exceed maximum - * number specified by MAX_ASTATE_COUNT member of Base FWs - * FIRMWARE_CONFIG parameter. - */ + /** Number of active entries in astates_ array. */ uint32_t astates_count_; - /* Array of states. */ + /** Array of power states. */ struct ipc4_astate astates_[3]; } __attribute__((packed, aligned(4))); -/* All members have the same meaning as in the CopierGatewayCfg structure - * (except for the dma_buffer_size that is not used here). +/** + * \brief Direct DMA Gateway Control structure (IPC4_DMA_CONTROL). + * \ingroup ipc4_base_fw_api */ struct ipc4_dma_control { - uint32_t node_id; - uint32_t config_length; - uint32_t config_data[0]; + uint32_t node_id; /**< Target DMA gateway node ID (union ipc4_connector_node_id). */ + uint32_t config_length; /**< Configuration blob length in DWORDS. */ + uint32_t config_data[0]; /**< Gateway-specific configuration payload (NHLT blob / TLV). */ } __attribute__((packed, aligned(4))); +/** + * \brief Performance measurement process states. + * \ingroup ipc4_base_fw_api + */ enum ipc4_perf_measurements_state_set { - IPC4_PERF_MEASUREMENTS_DISABLED = 0, - IPC4_PERF_MEASUREMENTS_STOPPED = 1, - IPC4_PERF_MEASUREMENTS_STARTED = 2, - IPC4_PERF_MEASUREMENTS_PAUSED = 3, + IPC4_PERF_MEASUREMENTS_DISABLED = 0, /**< Performance measurements disabled. */ + IPC4_PERF_MEASUREMENTS_STOPPED = 1, /**< Performance measurements stopped. */ + IPC4_PERF_MEASUREMENTS_STARTED = 2, /**< Performance measurements actively running. */ + IPC4_PERF_MEASUREMENTS_PAUSED = 3, /**< Performance measurements paused. */ }; +/** + * \brief Single component performance measurement data item. + * \ingroup ipc4_base_fw_api + */ struct ipc4_perf_data_item { - /*ID of the core running the load being reported */ - uint32_t resource_id; - /* - * 0 - D0, - * 1 - D0i3, - */ - uint32_t power_mode : 1; - uint32_t rsvd : 30; - uint32_t is_removed : 1; - /* Peak KCPS (Kilo Cycles Per Second) captured */ - uint32_t peak_kcps; - /* Average KCPS (Kilo Cycles Per Second) measured */ - uint32_t avg_kcps; + uint32_t resource_id; /**< Resource ID: core ID or {module_id, instance_id}. */ + uint32_t power_mode : 1; /**< Power mode: 0 = D0, 1 = D0i3. */ + uint32_t rsvd : 30; /**< Reserved padding. */ + uint32_t is_removed : 1; /**< 1 if component was removed/uninstantiated. */ + uint32_t peak_kcps; /**< Peak Kilo Cycles Per Second captured. */ + uint32_t avg_kcps; /**< Average Kilo Cycles Per Second measured. */ } __attribute__((packed, aligned(4))); -/* - * PerfDataItem with additional fields required by module - * instance to properly calculate its performance data. - * NOTE: Only PerfDataItem is part of GlobalPerfData. +/** + * \brief Module instance performance data with internal iteration metrics. + * \ingroup ipc4_base_fw_api */ struct ipc4_perf_data_item_mi { - struct ipc4_perf_data_item item; - /* Total iteration count of module instance */ - uint32_t total_iteration_count; - /* Total cycles consumed by module instance */ - uint64_t total_cycles_consumed; + struct ipc4_perf_data_item item; /**< Base performance item header. */ + uint32_t total_iteration_count; /**< Total execution iteration count of module instance. */ + uint64_t total_cycles_consumed; /**< Total DSP cycles consumed by module instance. */ } __attribute__((packed, aligned(4))); +/** + * \brief Global DSP performance report payload (IPC4_GLOBAL_PERF_DATA). + * \ingroup ipc4_base_fw_api + */ struct ipc4_global_perf_data { - /* Specifies number of items in perf_items array */ - uint32_t perf_item_count; - /* Array of global performance measurements */ - struct ipc4_perf_data_item perf_items[1]; + uint32_t perf_item_count; /**< Number of items in perf_items array. */ + struct ipc4_perf_data_item perf_items[1]; /**< Array of performance measurement items. */ } __attribute__((packed, aligned(4))); +/** + * \brief Low latency interrupt source types. + * \ingroup ipc4_base_fw_api + */ enum ipc4_low_latency_interrupt_source { - IPC4_LOW_POWER_TIMER_INTERRUPT_SOURCE = 1, - IPC4_DMA_GATEWAY_INTERRUPT_SOURCE = 2 + IPC4_LOW_POWER_TIMER_INTERRUPT_SOURCE = 1, /**< Low Power Timer interrupt. */ + IPC4_DMA_GATEWAY_INTERRUPT_SOURCE = 2 /**< DMA Gateway completion interrupt. */ }; +/** + * \brief Scheduler tick and timer configuration (IPC4_SCHEDULER_CONFIGURATION). + * \ingroup ipc4_base_fw_api + */ struct ipc4_scheduler_config { - uint32_t sys_tick_multiplier; - uint32_t sys_tick_divider; - uint32_t sys_tick_source; - uint32_t sys_tick_cfg_length; - uint32_t sys_tick_cfg[1]; + uint32_t sys_tick_multiplier; /**< System tick multiplier factor. */ + uint32_t sys_tick_divider; /**< System tick divider factor. */ + uint32_t sys_tick_source; /**< System tick source clock. */ + uint32_t sys_tick_cfg_length; /**< Length of extra tick configuration. */ + uint32_t sys_tick_cfg[1]; /**< Extra tick configuration data. */ } __attribute__((packed, aligned(4))); +/** + * \brief 64-bit system timestamp split into lower and upper 32-bit words. + * \ingroup ipc4_base_fw_api + */ struct ipc4_system_time { - /* Lower DWORD of current system time value */ - uint32_t val_l; - /* Upper DWORD of current system time value */ - uint32_t val_u; + uint32_t val_l; /**< Lower 32 bits of microsecond timestamp. */ + uint32_t val_u; /**< Upper 32 bits of microsecond timestamp. */ } __attribute__((packed, aligned(4))); +/** + * \brief Host and DSP system time pairing for clock synchronization. + * \ingroup ipc4_base_fw_api + */ struct ipc4_system_time_info { - struct ipc4_system_time host_time; - struct ipc4_system_time dsp_time; + struct ipc4_system_time host_time; /**< Host CPU timestamp. */ + struct ipc4_system_time dsp_time; /**< Corresponding DSP timestamp. */ } __attribute__((packed, aligned(4))); +/** + * \brief Extended host/DSP system time with RTC and ART timestamps. + * \ingroup ipc4_base_fw_api + */ struct ipc4_ext_system_time { - /* Lower DWORD of current system time value. */ - uint32_t utc_l; - /* Upper DWORD of current system time value. */ - uint32_t utc_u; - /* Lower DWORD of current RTC value. */ - uint32_t rtc_l; - /* Upper DWORD of current RTC value. */ - uint32_t rtc_u; - /* Lower DWORD of current ART value. */ - uint32_t art_l; - /* Upper DWORD of current ART value. */ - uint32_t art_u; + uint32_t utc_l; /**< Lower DWORD of UTC system time. */ + uint32_t utc_u; /**< Upper DWORD of UTC system time. */ + uint32_t rtc_l; /**< Lower DWORD of Real Time Clock. */ + uint32_t rtc_u; /**< Upper DWORD of Real Time Clock. */ + uint32_t art_l; /**< Lower DWORD of Always Running Timer (ART). */ + uint32_t art_u; /**< Upper DWORD of Always Running Timer (ART). */ }; +/** + * \brief Pipeline attributes flags. + * \ingroup ipc4_base_fw_api + */ enum ipc4_pipeline_attributes { - /* Determines whether on pipeline will be allocated module(s) with ULP capability */ + /** Pipeline contains modules with Ultra Low Power (ULP) capability. */ IPC4_ULTRA_LOW_POWER = 0, - /* Determines whether on pipeline will be allocated - * module(s) that can report autonomous reset. - */ + /** Pipeline contains modules capable of autonomous reset reporting. */ IPC4_AUTONOMOUS_RESET = 1, }; +/** + * \brief Resource allocation request types. + * \ingroup ipc4_base_fw_api + */ enum ipc4_resource_allocation_type { - /* Allocate KCPS */ - IPC4_RAT_DSP_KCPS = 0, - IPC4_RAT_MEMORY = 1, + IPC4_RAT_DSP_KCPS = 0, /**< Allocate DSP processing capacity in KCPS. */ + IPC4_RAT_MEMORY = 1, /**< Allocate physical SRAM memory. */ }; +/** + * \brief KCPS resource allocation descriptor. + * \ingroup ipc4_base_fw_api + */ struct ipc4_resource_kcps { - uint32_t core_id; - int32_t kcps; + uint32_t core_id; /**< DSP core identifier. */ + int32_t kcps; /**< KCPS capacity to allocate or release (signed). */ } __attribute__((packed, aligned(4))); +/** + * \brief Memory resource allocation descriptor. + * \ingroup ipc4_base_fw_api + */ struct ipc4_resource_memory { - /* base address to allocate */ - uint32_t address; - /* size of allocate */ - uint32_t size; + uint32_t address; /**< Base physical address to allocate. */ + uint32_t size; /**< Size of memory allocation in bytes. */ } __attribute__((packed, aligned(4))); +/** + * \brief Resource allocation request structure (IPC4_RESOURCE_ALLOCATION_REQUEST). + * \ingroup ipc4_base_fw_api + */ struct ipc4_resource_request { - /* Type of resource to allocate */ - uint32_t ra_type; + uint32_t ra_type; /**< Resource allocation type (enum ipc4_resource_allocation_type). */ union { - /* Valid for ra_type == RAT_DSP_KCPS */ - struct ipc4_resource_kcps kcps; - /* Valid for ra_type == RAT_MEMORY */ - struct ipc4_resource_memory memory; - } ra_data; + struct ipc4_resource_kcps kcps; /**< KCPS data when ra_type == RAT_DSP_KCPS. */ + struct ipc4_resource_memory memory; /**< Memory data when ra_type == RAT_MEMORY. */ + } ra_data; /**< Resource payload union. */ } __attribute__((packed, aligned(4))); +/** \brief LP-SRAM state indicator index. */ #define IPC4_LPSRAM_STATE 0 +/** \brief HP-SRAM state indicator index. */ #define IPC4_HPSRAM_STATE 1 +/** + * \brief SRAM page allocation bitmask array. + * \ingroup ipc4_base_fw_api + */ struct ipc4_sram_state_page_alloc { - /* Number of items in page_alloc array */ - uint32_t page_alloc_count; - /* State of memory page allocation. - * bit[i] indicates whether i-th page is allocated. - */ + uint32_t page_alloc_count; /**< Number of items in page_alloc array. */ + /** Bit[i] indicates whether i-th memory page is allocated. */ uint16_t page_alloc[1]; } __attribute__((packed, aligned(4))); +/** + * \brief Detailed SRAM state and power bank information (IPC4_MEMORY_STATE_INFO_GET). + * \ingroup ipc4_base_fw_api + */ struct ipc4_sram_state_info { - /* Number of free memory pages */ - uint32_t free_phys_mem_pages; - /* Number of items in ebb_state array */ - uint32_t ebb_state_dword_count; - /* State of EBBs (memory banks) */ - /* bit[i] indicates whether i-th EBB is in use (1) or powered down (0) */ + uint32_t free_phys_mem_pages; /**< Number of free memory pages available. */ + uint32_t ebb_state_dword_count; /**< Number of items in ebb_state array. */ + /** Bit[i] indicates whether i-th EBB bank is powered up (1) or off (0). */ uint32_t ebb_state[1]; - struct ipc4_sram_state_page_alloc page_alloc_struct; + struct ipc4_sram_state_page_alloc page_alloc_struct; /**< Page allocation state. */ } __attribute__((packed, aligned(4))); +/** + * \brief Audio Hub Link (ALH) interface versions. + * \ingroup ipc4_base_fw_api + */ enum ipc4_alh_version { - IPC4_ALH_NO_SUPPORT, - IPC4_ALH_CAVS_1_8 = 0x10000, + IPC4_ALH_NO_SUPPORT, /**< ALH not supported. */ + IPC4_ALH_CAVS_1_8 = 0x10000, /**< CAVS 1.8+ ALH implementation. */ }; +/** + * \brief Properties of a dynamic or preloaded external library. + * \ingroup ipc4_base_fw_api + */ struct ipc4_library_props { - /* Library run-time identifier, depends on order of loading. */ - /* Base FW is always reported with id 0. */ - uint32_t id; - /* Name of the library. */ - uint8_t name[8]; - /* Major version of the library. */ - uint16_t major_version; - /* Minor version of the library. */ - uint16_t minor_version; - /* Hotfix version of the library. */ - uint16_t hotfix_version; - /* Build version of the library. */ - uint16_t build_version; - /* Number of modules packed into the library. */ - uint32_t num_module_entries; + uint32_t id; /**< Library runtime ID (Base FW is always 0). */ + uint8_t name[8]; /**< Library identifier name string. */ + uint16_t major_version; /**< Major version number. */ + uint16_t minor_version; /**< Minor version number. */ + uint16_t hotfix_version; /**< Hotfix version number. */ + uint16_t build_version; /**< Build version number. */ + uint32_t num_module_entries; /**< Number of modules provided by this library. */ } __packed __aligned(4); +/** + * \brief Library information report payload (IPC4_LIBRARIES_INFO_GET). + * \ingroup ipc4_base_fw_api + */ struct ipc4_libraries_info { - /* Specifies number of items in libraries array. */ - uint32_t library_count; - /* Array of libraries properties. */ - struct ipc4_library_props libraries[0]; + uint32_t library_count; /**< Number of libraries reported. */ + struct ipc4_library_props libraries[0]; /**< Array of library property structures. */ } __packed __aligned(4); +/** + * \brief Logging configuration and state control (IPC4_ENABLE_LOGS). + * \ingroup ipc4_base_fw_api + */ struct ipc4_log_state_info { - /* - * Specifies how frequently FW sends Log Buffer Status - * notification for new entries in case the usual notification - * sending criteria are not met (half of the buffer is full). The - * parameter is specified in number of system ticks. - */ + /** Aging timer period in system ticks for log buffer flush notification. */ uint32_t aging_timer_period; - - /* - * Specifies the latency of logging 'dropped log entries' - * information after the content is consumed by the driver but no - * new log entry appears (which would trigger logging 'dropped - * entries' as well). The parameter is specified in number of - * system ticks. - */ + /** Latency in system ticks for logging dropped entries after buffer read. */ uint32_t fifo_full_timer_period; - - /* 0 if logging is disabled, otherwise enabled */ + /** 1 to enable logging, 0 to disable. */ uint32_t enable; - - /* - * Logging mask of priorities and components for all - * supported providers. Nth entry in array gives priorities and - * components mask for Nth provider (library). - */ + /** Priority and component logging masks per library provider. */ uint32_t logs_mask[IPC4_MAX_LIBS_COUNT]; } __attribute__((packed, aligned(4))); +/** + * \brief Power state query types. + * \ingroup ipc4_base_fw_api + */ enum ipc4_power_state_type { - IPC4_ACTIVE_CORES_MASK = 0, - IPC4_CORE_KCPS = 1, + IPC4_ACTIVE_CORES_MASK = 0, /**< Query bitmask of currently active DSP cores. */ + IPC4_CORE_KCPS = 1, /**< Query core clock KCPS settings. */ }; -/* Scheduler info get structures */ - +/** + * \brief Single task properties within scheduler information. + * \ingroup ipc4_base_fw_api + */ struct task_props { - /* Unique ID of task. */ - uint32_t task_id; - /* Specifies number of items in module_instance_id array. */ - uint32_t module_instance_count; - /* Array of IDs of module instances running inside the task. */ - uint32_t module_instance_id[]; + uint32_t task_id; /**< Unique identifier of the task. */ + uint32_t module_instance_count; /**< Number of module instances attached to task. */ + uint32_t module_instance_id[]; /**< Array of module instance IDs executing in task. */ } __packed __aligned(4); +/** + * \brief Core scheduler properties and scheduled tasks. + * \ingroup ipc4_base_fw_api + */ struct scheduler_props { - /* Processing domain, one of: - * COMP_PROCESSING_DOMAIN_LL or COMP_PROCESSING_DOMAIN_DP - */ - uint32_t processing_domain; - /* ID of core that scheduler is running on. */ - uint32_t core_id; - /* Specifies number of items in task_info array. */ - uint32_t task_count; - struct task_props task_info[]; + uint32_t processing_domain; /**< Domain: COMP_PROCESSING_DOMAIN_LL or DP. */ + uint32_t core_id; /**< Core ID the scheduler executes on. */ + uint32_t task_count; /**< Number of tasks managed by scheduler. */ + struct task_props task_info[]; /**< Array of task descriptor structures. */ } __packed __aligned(4); +/** + * \brief Complete scheduler topology report (IPC4_SCHEDULERS_INFO_GET). + * \ingroup ipc4_base_fw_api + */ struct schedulers_info { - /* Specifies number of items in scheduler_info array. */ - uint32_t scheduler_count; - /* Array of scheduler properties. */ - struct scheduler_props scheduler_info[]; + uint32_t scheduler_count; /**< Number of schedulers reported. */ + struct scheduler_props scheduler_info[]; /**< Array of scheduler properties. */ } __packed __aligned(4); /** - * @brief Get the current DSP system time information for host-DSP clock synchronization. - * @return Pointer to struct ipc4_system_time_info containing current 64-bit timestamp. + * \brief Get current DSP system time information for host-DSP clock synchronization. + * \ingroup ipc4_base_fw_api + * \return Pointer to struct ipc4_system_time_info containing current 64-bit timestamp. */ struct ipc4_system_time_info *basefw_get_system_time_info(void); -/* Specifies I2S IPC4 version for PTL platform */ +/** \brief I2S IPC4 interface version for Panther Lake (PTL) platforms. */ static const uint32_t I2S_VER_30_PTL = 0x40000; +/** + * \brief FW component performance measurement item. + * \ingroup ipc4_base_fw_api + */ struct perf_data_item { - /* ID of the FW component */ - uint32_t resource_id; - /* 0 - D0, 1 - D0i3. */ - uint32_t power_mode : 1; - uint32_t rsvd : 30; - /* the component still exists (0) or has been already deleted (1) */ - uint32_t is_removed : 1; - /* Peak KCPS captured */ - uint32_t peak_kcps; - /* Average KCPS measured */ - uint32_t avg_kcps; + uint32_t resource_id; /**< Component resource ID. */ + uint32_t power_mode : 1; /**< Power mode: 0 = D0, 1 = D0i3. */ + uint32_t rsvd : 30; /**< Reserved bits. */ + uint32_t is_removed : 1; /**< 0 if component exists, 1 if deleted. */ + uint32_t peak_kcps; /**< Peak KCPS captured. */ + uint32_t avg_kcps; /**< Average KCPS measured. */ } __packed __aligned(4); +/** + * \brief Extended component performance metrics with DSP cycle counts. + * \ingroup ipc4_base_fw_api + */ struct ext_perf_data_item { - /* ID of the FW component */ - uint32_t resource_id; - /* 0 - D0, 1 - D0i3. */ - uint32_t power_mode : 1; - uint32_t rsvd : 30; - /* the component still exists (0) or has been already deleted (1) */ - uint32_t is_removed : 1; - /* peak number of DSP cycles used by a module */ - uint32_t module_peak_dsp_cycles; - /* total number of DSP used since by a module start of measurements, */ - uint64_t module_total_dsp_cycles_consumed; - /* how many times a module was executed */ - uint64_t module_total_dsp_iterations; - /* peak number of cycles used by a module. - * It is measured against DSP wall clock - */ - uint32_t module_peak_restricted_cycles; - /* total number of cycles used by a module since start of - * measurements. It is measured against DSP wall clock - */ - uint64_t module_total_restricted_cycles_consumed; - /* how many times a module invoke */ - uint64_t module_total_restricted_iterations; + uint32_t resource_id; /**< Component resource identifier. */ + uint32_t power_mode : 1; /**< Power mode: 0 = D0, 1 = D0i3. */ + uint32_t rsvd : 30; /**< Reserved bits. */ + uint32_t is_removed : 1; /**< 0 if component exists, 1 if deleted. */ + uint32_t module_peak_dsp_cycles; /**< Peak DSP cycles used in a single run. */ + uint64_t module_total_dsp_cycles_consumed; /**< Total cumulative DSP cycles consumed. */ + uint64_t module_total_dsp_iterations; /**< Total execution iteration count. */ + uint32_t module_peak_restricted_cycles; /**< Peak restricted cycles against wall clock. */ + uint64_t module_total_restricted_cycles_consumed; /**< Total restricted cycles consumed. */ + uint64_t module_total_restricted_iterations; /**< Total restricted iteration count. */ } __packed __aligned(4); +/** + * \brief Extended global performance data report (IPC4_EXTENDED_GLOBAL_PERF_DATA). + * \ingroup ipc4_base_fw_api + */ struct extended_global_perf_data { - /* Specifies number of items in perf_items array. */ - uint32_t perf_item_count; - /* Array of extended global performance measurements. */ - struct ext_perf_data_item perf_items[0]; + uint32_t perf_item_count; /**< Number of items in perf_items array. */ + struct ext_perf_data_item perf_items[0]; /**< Array of extended performance items. */ } __packed __aligned(4); +/** + * \brief Component performance data with wall clock cycle metrics. + * \ingroup ipc4_base_fw_api + */ struct perf_data_item_comp { - struct perf_data_item item; - /* Total iteration count of module instance */ - uint32_t total_iteration_count; - /* Total cycles consumed by module instance */ - uint64_t total_cycles_consumed; - /* usage statistics against DSP wallclock cycles */ - uint32_t restricted_peak_cycles; - uint64_t restricted_total_iterations; - uint64_t restricted_total_cycles; - + struct perf_data_item item; /**< Base performance item header. */ + uint32_t total_iteration_count; /**< Total module iteration count. */ + uint64_t total_cycles_consumed; /**< Total DSP cycles consumed. */ + uint32_t restricted_peak_cycles; /**< Peak cycles measured against wall clock. */ + uint64_t restricted_total_iterations; /**< Total restricted iteration count. */ + uint64_t restricted_total_cycles; /**< Total restricted cycles consumed. */ } __packed __aligned(4); +/** + * \brief Global DSP performance summary. + * \ingroup ipc4_base_fw_api + */ struct global_perf_data { - /* Specifies number of items in perf_items array. */ - uint32_t perf_item_count; - /* Array of global performance measurements. */ - struct perf_data_item perf_items[0]; - + uint32_t perf_item_count; /**< Number of items in perf_items array. */ + struct perf_data_item perf_items[0]; /**< Array of performance items. */ } __packed __aligned(4); #endif /* __SOF_IPC4_BASE_FW_H__ */ diff --git a/src/include/ipc4/base_fw_vendor.h b/src/include/ipc4/base_fw_vendor.h index e54b9214e196..98250eac9c3a 100644 --- a/src/include/ipc4/base_fw_vendor.h +++ b/src/include/ipc4/base_fw_vendor.h @@ -8,6 +8,7 @@ /** * \file ipc4/base_fw_vendor.h * \brief Platform specific IPC4 base firmware functionality. + * \ingroup ipc4_base_fw_api */ #ifndef __SOF_IPC4_BASE_FW_VENDOR_H__ @@ -28,8 +29,9 @@ struct comp_dev; /** * \brief Vendor specific routine to add data tuples to FW_CONFIG * structure sent to host via IPC. - * \param[out] data_offset data offset after tuples added - * \param[in] data pointer where to add new entries + * \ingroup ipc4_base_fw_api + * \param[out] data_offset Data offset after tuples added. + * \param[in,out] data Pointer to destination buffer where to add new entries. * \return 0 if successful, error code otherwise. */ int basefw_vendor_fw_config(uint32_t *data_offset, char *data); @@ -37,32 +39,42 @@ int basefw_vendor_fw_config(uint32_t *data_offset, char *data); /** * \brief Vendor specific routine to add data tuples to HW_CONFIG * structure sent to host via IPC. - * \param[out] data_offset data offset after tuples added - * \param[in] data pointer where to add new entries + * \ingroup ipc4_base_fw_api + * \param[out] data_offset Data offset after tuples added. + * \param[in,out] data Pointer to destination buffer where to add new entries. * \return 0 if successful, error code otherwise. */ int basefw_vendor_hw_config(uint32_t *data_offset, char *data); /** - * \brief Vendor specific routine which return the pointer to + * \brief Vendor specific routine which returns the pointer to * the boot base manifest. - * \return pointer to struct if successful, null otherwise. + * \ingroup ipc4_base_fw_api + * \return Pointer to struct sof_man_fw_desc if successful, NULL otherwise. */ struct sof_man_fw_desc *basefw_vendor_get_manifest(void); /** * \brief Vendor specific routine to get information about modules. - * Function add information and sent to host via IPC. - * \param[out] data_offset data offset after structure added - * \param[in] data pointer where to add new entries + * Function adds module information sent to host via IPC. + * \ingroup ipc4_base_fw_api + * \param[out] data_offset Data offset after structure added. + * \param[in,out] data Pointer to destination buffer where to add new entries. * \return 0 if successful, error code otherwise. */ int basefw_vendor_modules_info_get(uint32_t *data_offset, char *data); /** - * \brief Implement vendor specific parameter for basefw module. - * This function is called for parameters not handled by - * generic base_fw code. + * \brief Implement vendor specific parameter retrieval for basefw module. + * This function is called for parameters not handled by generic base_fw code. + * \ingroup ipc4_base_fw_api + * \param[in] dev Pointer to base firmware component device. + * \param[in] param_id Parameter ID requested. + * \param[in] first_block True if this is the first block of large config. + * \param[in] last_block True if this is the last block of large config. + * \param[in,out] data_offset Offset into large configuration buffer. + * \param[out] data Buffer to receive parameter payload. + * \return 0 on success, negative error code on failure. */ int basefw_vendor_get_large_config(struct comp_dev *dev, uint32_t param_id, @@ -72,9 +84,16 @@ int basefw_vendor_get_large_config(struct comp_dev *dev, char *data); /** - * \brief Implement vendor specific parameter for basefw module. - * This function is called for parameters not handled by - * generic base_fw code. + * \brief Implement vendor specific parameter configuration for basefw module. + * This function is called for parameters not handled by generic base_fw code. + * \ingroup ipc4_base_fw_api + * \param[in] dev Pointer to base firmware component device. + * \param[in] param_id Parameter ID configured. + * \param[in] first_block True if this is the first block of large config. + * \param[in] last_block True if this is the last block of large config. + * \param[in] data_offset Offset into large configuration buffer. + * \param[in] data Pointer to parameter payload. + * \return 0 on success, negative error code on failure. */ int basefw_vendor_set_large_config(struct comp_dev *dev, uint32_t param_id, @@ -84,12 +103,12 @@ int basefw_vendor_set_large_config(struct comp_dev *dev, const char *data); /** - * @brief Vendor specific routine to configure DMA gateway. - * - * @param node_id The node ID of the DMA gateway to configure. - * @param config_data pointer to the configuration data. - * @param data_size Size of the configuration data. - * @return 0 if successful, error code otherwise. + * \brief Vendor specific routine to configure DMA gateway. + * \ingroup ipc4_base_fw_api + * \param[in] node_id The node ID of the DMA gateway to configure. + * \param[in] config_data Pointer to the configuration data. + * \param[in] data_size Size of the configuration data in bytes. + * \return 0 if successful, error code otherwise. */ int basefw_vendor_dma_control(uint32_t node_id, const char *config_data, From d96c8257e347dd12d4ad09adc50413c416e7414d Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 13 Oct 2026 16:11:22 +0100 Subject: [PATCH 6/9] doc: ipc4: document gateway connectors, ALH aggregation, DMIC, and SSP configuration Signed-off-by: Liam Girdwood --- src/include/ipc4/alh.h | 56 ++++++---- src/include/ipc4/dmic.h | 203 +++++++++-------------------------- src/include/ipc4/gateway.h | 212 ++++++++++++++++--------------------- src/include/ipc4/ssp.h | 124 +++++++++++++--------- 4 files changed, 252 insertions(+), 343 deletions(-) diff --git a/src/include/ipc4/alh.h b/src/include/ipc4/alh.h index d7077a7eb017..a503ac1b10bf 100644 --- a/src/include/ipc4/alh.h +++ b/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 #include +/** \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) diff --git a/src/include/ipc4/dmic.h b/src/include/ipc4/dmic.h index d09332ec9c5c..494c367f6bb0 100644 --- a/src/include/ipc4/dmic.h +++ b/src/include/ipc4/dmic.h @@ -13,37 +13,35 @@ /** * \file include/ipc4/dmic.h - * \brief IPC4 DMIC definitions. + * \brief IPC4 Digital Microphone (DMIC) gateway and PDM controller configuration. + * \ingroup ipc4_gateway_api * NOTE: This ABI uses bit fields and is non portable. */ -/* IOCTL ID of DMIC Set Gain Coefficients */ +/** \brief IOCTL command ID for DMIC set gain coefficients. */ #define DMIC_SET_GAIN_COEFFICIENTS 2 -/* Maximum number of dmic gain coefficients */ +/** \brief Maximum number of DMIC gain coefficients. */ #define DMIC_MAX_GAIN_COEFFS_CNT 4 /** - * @brief Structure representing the global configuration for DMIC (Digital Microphone) module. + * \brief Global hardware configuration for DMIC controller. + * \ingroup ipc4_gateway_api */ union dmic_global_cfg { - /** - * @brief Raw 32-bit value of Global Cfg. - */ + /** Raw 32-bit clock on delay value. */ uint32_t clock_on_delay; - /** - * @brief Bitfields of Extended Global Config. - */ + /** Extended global configuration bitfields. */ struct { /** - * @brief Specifies the period in milliseconds to override data with silence after + * Specifies the period in milliseconds to override data with silence after * DMA transfer is started. */ uint32_t silence_period : 16; /** - * @brief Specifies the period in milliseconds for fade-in to apply on input data + * Specifies the period in milliseconds for fade-in to apply on input data * (following silence_period if applied). */ uint32_t fade_in_period : 16; @@ -51,169 +49,72 @@ union dmic_global_cfg { } __packed __aligned(4); /** - * @brief Structure representing the configuration of a DMIC channel. + * \brief Configuration parameters for a single DMIC channel. + * \ingroup ipc4_gateway_api */ struct dmic_channel_cfg { - /** - * @brief Outcontrol - */ - uint32_t out_control; + uint32_t out_control; /**< Output control register value. */ }; /** - * @brief Structure representing FIR (Finite Impulse Response) configuration. + * \brief Finite Impulse Response (FIR) decimation filter configuration. + * \ingroup ipc4_gateway_api */ struct dmic_fir_cfg { - /** - * @brief FIR_CONTROL - * Control register for FIR configuration. - */ - uint32_t fir_control; - - /** - * @brief FIR_CONFIG - * Configuration register for FIR filter. - */ - uint32_t fir_config; - - /** - * @brief DC_OFFSET_LEFT - * DC offset value for the left channel. - */ - uint32_t dc_offset_left; - - /** - * @brief DC_OFFSET_RIGHT - * DC offset value for the right channel. - */ - uint32_t dc_offset_rigth; - - /** - * @brief OUT_GAIN_LEFT - * Output gain value for the left channel. - */ - uint32_t out_gain_left; - - /** - * @brief OUT_GAIN_RIGHT - * Output gain value for the right channel. - */ - uint32_t out_gain_rigth; - - /** - * @brief rsvd_2 - * Reserved field. - */ - uint32_t rsvd_2[2]; + uint32_t fir_control; /**< FIR filter control register value. */ + uint32_t fir_config; /**< FIR filter configuration register value. */ + uint32_t dc_offset_left; /**< DC offset compensation value for left channel. */ + uint32_t dc_offset_rigth; /**< DC offset compensation value for right channel. */ + uint32_t out_gain_left; /**< Output gain value for left channel. */ + uint32_t out_gain_rigth; /**< Output gain value for right channel. */ + uint32_t rsvd_2[2]; /**< Reserved padding. */ } __packed __aligned(4); /** - * @brief Structure representing the configuration of the PDM control for DMIC. + * \brief Pulse Density Modulation (PDM) controller configuration for DMIC. + * \ingroup ipc4_gateway_api * - * This structure defines the configuration parameters for the PDM control of the DMIC - * (Digital Microphone) module. It includes fields for controlling the CIC (Cascaded - * Integrator-Comb) filter, MIC (Microphone) control, SoundWire mapping, FIR (Finite - * Impulse Response) configurations, and FIR coefficients. + * Defines the configuration parameters for the PDM control of the DMIC + * module, including CIC decimation filter, microphone gain/control, + * SoundWire pin mapping, and dual FIR filter cascades. */ struct dmic_pdm_ctrl_cfg { - /** - * @brief CIC_CONTROL - * Control register for CIC configuration. - */ - uint32_t cic_control; - /** - * @brief CIC_CONFIG - * Configuration register for CIC filter. - */ - uint32_t cic_config; - /** - * @brief Reserved field - */ - uint32_t rsvd_0; - /** - * @brief MIC_CONTROL - * Control register for MIC configuration. - */ - uint32_t mic_control; - /** - * @brief - * This field is used on platforms with SoundWire, otherwise ignored. - */ - uint32_t pdmsm; - /** - * @brief Index of another PDMCtrlCfg to be used as a source of FIR coefficients. - */ - uint32_t reuse_fir_from_pdm; - /** - * @brief Reserved field - */ - uint32_t rsvd_1[2]; - /** - * @brief FIR configurations - */ - struct dmic_fir_cfg fir_config[2]; - /** - * @brief Array of FIR coefficients, channel A goes first, then channel B. - */ - uint32_t fir_coeffs[0]; + uint32_t cic_control; /**< CIC filter control register value. */ + uint32_t cic_config; /**< CIC filter configuration register value. */ + uint32_t rsvd_0; /**< Reserved padding. */ + uint32_t mic_control; /**< Microphone control register value. */ + uint32_t pdmsm; /**< SoundWire PDM stream mapping (ignored on non-SDW). */ + uint32_t reuse_fir_from_pdm; /**< Index of another PDM controller to reuse FIR coefficients from. */ + uint32_t rsvd_1[2]; /**< Reserved padding. */ + struct dmic_fir_cfg fir_config[2]; /**< Cascaded FIR decimation filter configurations. */ + uint32_t fir_coeffs[0]; /**< Variable-length array of FIR coefficients (channel A then B). */ } __packed __aligned(4); /** - * @brief Structure representing the configuration blob for DMIC (Digital Microphone) settings. + * \brief Complete configuration blob for Digital Microphone (DMIC) settings. + * \ingroup ipc4_gateway_api * - * This structure contains various configuration settings for DMIC, including time-slot mappings, - * global configuration, PDM channel configuration, and PDM controller configuration. + * Contains time-slot mappings, global clock/ramp settings, channel routing, + * and per-PDM controller decimation parameters. */ struct dmic_config_blob { - /** - * @brief Time-slot mappings. - */ - uint32_t ts_group[4]; - - /** - * @brief DMIC global configuration. - */ - union dmic_global_cfg global_cfg; - - /** - * @brief PDM channels to be programmed using data from channel_cfg array. - */ - uint32_t channel_ctrl_mask : 8; - - /** - * @brief Clock source for DMIC. - */ - uint32_t clock_source : 8; - - /** - * @brief Reserved field. - */ - uint32_t rsvd : 16; - - /** - * @brief PDM channel configuration settings. - */ - struct dmic_channel_cfg channel_cfg[0]; - - /** - * @brief PDM controllers to be programmed using data from pdm_ctrl_cfg array. - */ - uint32_t pdm_ctrl_mask; - - /** - * @brief PDM controller configuration settings. - */ - struct dmic_pdm_ctrl_cfg pdm_ctrl_cfg[0]; + uint32_t ts_group[4]; /**< Time-slot grouping mappings. */ + union dmic_global_cfg global_cfg; /**< Global clock delay and fade parameters. */ + uint32_t channel_ctrl_mask : 8; /**< PDM channels to program from channel_cfg. */ + uint32_t clock_source : 8; /**< Clock source selection for DMIC. */ + uint32_t rsvd : 16; /**< Reserved padding. */ + struct dmic_channel_cfg channel_cfg[0]; /**< Variable-length channel configurations. */ + uint32_t pdm_ctrl_mask; /**< Bitmask of active PDM controllers. */ + struct dmic_pdm_ctrl_cfg pdm_ctrl_cfg[0]; /**< Variable-length PDM controller configurations. */ } __packed __aligned(4); /** - * @brief Structure representing the configuration data for DMIC. + * \brief Top-level DMIC configuration data container. + * \ingroup ipc4_gateway_api */ struct dmic_config_data { - /**< Gateway attributes */ - union ipc4_gateway_attributes gtw_attributes; - /**< DMIC Configuration BLOB */ - struct dmic_config_blob dmic_blob; + union ipc4_gateway_attributes gtw_attributes; /**< Gateway memory allocation attributes. */ + struct dmic_config_blob dmic_blob; /**< Hardware DMIC configuration blob. */ } __packed __aligned(4); #endif /* __SOF_IPC4_DMIC_H__ */ diff --git a/src/include/ipc4/gateway.h b/src/include/ipc4/gateway.h index fb0ffca72f5b..81fa389e2a09 100644 --- a/src/include/ipc4/gateway.h +++ b/src/include/ipc4/gateway.h @@ -18,7 +18,7 @@ /** * \file include/ipc4/gateway.h * \brief IPC4 audio gateway attributes, ALH, HDA, and SoundWire gateway definitions. - * \ingroup ipc4_api + * \ingroup ipc4_gateway_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -28,196 +28,166 @@ #include #include -/**< Type of the gateway. */ +/** + * \brief Hardware and virtual audio gateway connector types. + * \ingroup ipc4_gateway_api + */ enum ipc4_connector_node_id_type { - /**< HD/A host output (-> DSP). */ + /** HD/A host output stream (Host to DSP playback). */ ipc4_hda_host_output_class = 0, - /**< HD/A host input (<- DSP). */ + /** HD/A host input stream (DSP to Host capture). */ ipc4_hda_host_input_class = 1, - /**< HD/A host input/output (rsvd for future use). */ + /** HD/A host bidirectional stream (reserved for future use). */ ipc4_hda_host_inout_class = 2, - /**< HD/A link output (DSP ->). */ + /** HD/A link output (DSP to external codec playback). */ ipc4_hda_link_output_class = 8, - /**< HD/A link input (DSP <-). */ + /** HD/A link input (external codec to DSP capture). */ ipc4_hda_link_input_class = 9, - /**< HD/A link input/output (rsvd for future use). */ + /** HD/A link bidirectional stream (reserved for future use). */ ipc4_hda_link_inout_class = 10, - /**< DMIC link input (DSP <-). */ + /** Digital Microphone (DMIC) link input (microphones to DSP capture). */ ipc4_dmic_link_input_class = 11, - /**< I2S link output (DSP ->). */ + /** I2S/SSP link output (DSP to I2S codec playback). */ ipc4_i2s_link_output_class = 12, - /**< I2S link input (DSP <-). */ + /** I2S/SSP link input (I2S codec to DSP capture). */ ipc4_i2s_link_input_class = 13, - /**< ALH link output, legacy for SNDW (DSP ->). */ + /** ALH link output, legacy alias for SoundWire (DSP to SoundWire link). */ ipc4_alh_link_output_class = 16, - /**< ALH link input, legacy for SNDW (DSP <-). */ + /** ALH link input, legacy alias for SoundWire (SoundWire link to DSP). */ ipc4_alh_link_input_class = 17, - /**< SNDW link output (DSP ->). */ + /** SoundWire link output stream (DSP to SoundWire codec playback). */ ipc4_alh_snd_wire_stream_link_output_class = 16, - /**< SNDW link input (DSP <-). */ + /** SoundWire link input stream (SoundWire codec to DSP capture). */ ipc4_alh_snd_wire_stream_link_input_class = 17, - /**< UAOL link output (DSP ->). */ + /** USB Audio Offload (UAOL) link output (DSP to UAOL controller). */ ipc4_alh_uaol_stream_link_output_class = 18, - /**< UAOL link input (DSP <-). */ + /** USB Audio Offload (UAOL) link input (UAOL controller to DSP). */ ipc4_alh_uaol_stream_link_input_class = 19, - /**< IPC output (DSP ->). */ + /** Inter-Processor Communication (IPC) output (DSP to host/peer). */ ipc4_ipc_output_class = 20, - /**< IPC input (DSP <-). */ + /** Inter-Processor Communication (IPC) input (host/peer to DSP). */ ipc4_ipc_input_class = 21, - /**< I2S Multi gtw output (DSP ->). */ + /** I2S aggregated multi-gateway output. */ ipc4_i2s_multi_link_output_class = 22, - /**< I2S Multi gtw input (DSP <-). */ + /** I2S aggregated multi-gateway input. */ ipc4_i2s_multi_link_input_class = 23, - /**< GPIO */ + /** GPIO hardware gateway. */ ipc4_gpio_class = 24, - /**< SPI */ + /** SPI hardware gateway output. */ ipc4_spi_output_class = 25, + /** SPI hardware gateway input. */ ipc4_spi_input_class = 26, + /** Sentinel marking maximum connector node ID type. */ ipc4_max_connector_node_id_type }; -/**< Invalid raw node id (to indicate uninitialized node id). */ +/** \brief Invalid raw node identifier sentinel. */ #define IPC4_INVALID_NODE_ID 0xffffffff -/**< all bits of v_index and dma_type */ +/** \brief Bitmask covering virtual index and DMA type bits. */ #define IPC4_NODE_ID_MASK 0x1fff -/**< Base top-level structure of an address of a gateway. */ -/*! - * The virtual index value, presented on the top level as raw 8 bits, - * is expected to be encoded in a gateway specific way depending on - * the actual type of gateway. +/** + * \brief Audio gateway addressing descriptor (connector node ID). + * \ingroup ipc4_gateway_api + * + * Encodes the gateway type and virtual DMA channel index for HDA, ALH, + * DMIC, and SSP gateways. */ union ipc4_connector_node_id { + uint32_t dw; /**< Raw 32-bit value of node ID. */ - /**< Raw 32-bit value of node id. */ - uint32_t dw; - - /**< Bit fields */ struct { - /**< Index of the virtual DMA at the gateway. */ - uint32_t v_index : 8; - - /**< Type of the gateway, one of ConnectorNodeId::Type values. */ - uint32_t dma_type : 5; - - /**< Rsvd field. */ - uint32_t _rsvd : 19; - } f; /**<< Bits */ + uint32_t v_index : 8; /**< Virtual DMA channel or FIFO index. */ + uint32_t dma_type : 5; /**< Gateway type (enum ipc4_connector_node_id_type). */ + uint32_t _rsvd : 19; /**< Reserved bits. */ + } f; /**< Bitfield access structure. */ } __attribute__((packed, aligned(4))); +/** \brief Base node ID for host output DMA channels. */ #define IPC4_HW_HOST_OUTPUT_NODE_ID_BASE 0x00 +/** \brief Node ID assigned to firmware code loader DMA. */ #define IPC4_HW_CODE_LOADER_NODE_ID 0x0F +/** \brief Base node ID for link input DMA channels. */ #define IPC4_HW_LINK_INPUT_NODE_ID_BASE 0x10 -/*! - * Attributes are usually provided along with the gateway configuration - * BLOB when the FW is requested to instantiate that gateway. +/** + * \brief Gateway buffer allocation attributes. + * \ingroup ipc4_gateway_api * - * There are flags which requests FW to allocate gateway related data - * (buffers and other items used while transferring data, like linked list) - * to be allocated from a special memory area, e.g low power memory. + * Configures special memory placement for gateway FIFOs and DMA buffers. */ union ipc4_gateway_attributes { + uint32_t dw; /**< Raw 32-bit attributes value. */ - /**< Raw value */ - uint32_t dw; - - /**< Access to the fields */ struct { - /**< Gateway data requested in low power memory. */ - uint32_t lp_buffer_alloc : 1; - - /**< Gateway data requested in register file memory. */ - uint32_t alloc_from_reg_file : 1; - - /**< Reserved field */ - uint32_t _rsvd : 30; - } bits; /**<< Bits */ + uint32_t lp_buffer_alloc : 1; /**< Allocate gateway buffers in Low Power (LP) SRAM. */ + uint32_t alloc_from_reg_file : 1; /**< Allocate gateway structures from DSP register file. */ + uint32_t _rsvd : 30; /**< Reserved bits. */ + } bits; /**< Bitfield access structure. */ } __attribute__((packed, aligned(4))); -/**< Gateway configuration BLOB structure. */ -/*! - * Actual config_blob content depends on the specific target gateway type. +/** + * \brief Generic gateway configuration blob container. + * \ingroup ipc4_gateway_api */ struct ipc4_gateway_config_data { - /**< Gateway attributes */ - union ipc4_gateway_attributes gtw_attributes; - - /**< Configuration BLOB */ - uint32_t config_blob[]; + union ipc4_gateway_attributes gtw_attributes; /**< Memory allocation attributes. */ + uint32_t config_blob[]; /**< Variable-length gateway-specific configuration payload. */ } __attribute__((packed, aligned(4))); -/**< Configuration for the IPC Gateway */ +/** + * \brief Configuration parameters for IPC Host Gateway. + * \ingroup ipc4_gateway_api + */ struct ipc4_ipc_gateway_config_blob { + uint32_t buffer_size; /**< Size of gateway circular buffer in bytes. */ - /**< Size of the gateway buffer, specified in bytes */ - uint32_t buffer_size; - - /**< Flags */ union { struct { - /**< Activates high threshold notification */ - /*! - * Indicates whether notification should be sent to the host - * when the size of data in the buffer reaches the high threshold - * specified by threshold_high parameter. - */ - uint32_t notif_high : 1; - - /**< Activates low threshold notification */ - /*! - * Indicates whether notification should be sent to the host - * when the size of data in the buffer reaches the low threshold - * specified by threshold_low parameter. - */ - uint32_t notif_low : 1; - - /**< Reserved field */ - uint32_t rsvd : 30; - } f; /**<< Bits */ - /**< Raw value of flags */ - uint32_t flags_raw; - } u; /**<< Flags */ - - /**< High threshold */ - /*! - * Specifies the high threshold (in bytes) for notifying the host - * about the buffered data level. - */ - uint32_t threshold_high; - - /**< Low threshold */ - /*! - * Specifies the low threshold (in bytes) for notifying the host - * about the buffered data level. - */ - uint32_t threshold_low; + uint32_t notif_high : 1; /**< Send notification when buffer exceeds high threshold. */ + uint32_t notif_low : 1; /**< Send notification when buffer falls below low threshold. */ + uint32_t rsvd : 30; /**< Reserved bits. */ + } f; /**< Bitfield access structure. */ + uint32_t flags_raw; /**< Raw 32-bit flags value. */ + } u; /**< Notification threshold flags union. */ + + uint32_t threshold_high; /**< High buffer fill watermark in bytes. */ + uint32_t threshold_low; /**< Low buffer fill watermark in bytes. */ } __attribute__((packed, aligned(4))); +/** + * \brief Gateway peripheral category bitmask. + * \ingroup ipc4_gateway_api + */ enum ipc4_gateway_type { - ipc4_gtw_none = BIT(0), - ipc4_gtw_host = BIT(1), - ipc4_gtw_dmic = BIT(2), - ipc4_gtw_link = BIT(3), - ipc4_gtw_alh = BIT(4), - ipc4_gtw_ssp = BIT(5), - ipc4_gtw_all = BIT(6) - 1 + ipc4_gtw_none = BIT(0), /**< No gateway specified. */ + ipc4_gtw_host = BIT(1), /**< Host DMA gateway. */ + ipc4_gtw_dmic = BIT(2), /**< Digital microphone gateway. */ + ipc4_gtw_link = BIT(3), /**< HD/A link gateway. */ + ipc4_gtw_alh = BIT(4), /**< Audio Hub Link / SoundWire gateway. */ + ipc4_gtw_ssp = BIT(5), /**< SSP / I2S gateway. */ + ipc4_gtw_all = BIT(6) - 1 /**< Bitmask covering all gateway types. */ }; +/** + * \brief Audio data stream direction flags. + * \ingroup ipc4_gateway_api + */ enum ipc4_direction_type { - ipc4_playback = BIT(0), - ipc4_capture = BIT(1), - ipc4_bidirection = BIT(0) | BIT(1) + ipc4_playback = BIT(0), /**< Playback stream direction (host/memory to peripheral). */ + ipc4_capture = BIT(1), /**< Capture stream direction (peripheral to host/memory). */ + ipc4_bidirection = BIT(0) | BIT(1) /**< Bidirectional stream direction. */ }; +/** \brief Helper macro to construct direction bitmask from index. */ #define IPC4_DIRECTION(x) BIT(x) #endif diff --git a/src/include/ipc4/ssp.h b/src/include/ipc4/ssp.h index 752cb59193bf..a2133b04b01c 100644 --- a/src/include/ipc4/ssp.h +++ b/src/include/ipc4/ssp.h @@ -13,7 +13,8 @@ /** * \file include/ipc4/ssp.h - * \brief IPC4 global definitions. + * \brief IPC4 Synchronous Serial Port (SSP / I2S) gateway and TDM configuration. + * \ingroup ipc4_gateway_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -23,96 +24,115 @@ #include #include +/** \brief Invalid TDM slot mapping sentinel value. */ #define I2S_TDM_INVALID_SLOT_MAP1 0xF +/** \brief Maximum number of audio channels supported over SSP TDM. */ #define I2S_TDM_MAX_CHANNEL_COUNT 8 +/** \brief Maximum number of TDM slot mapping entries. */ #define I2S_TDM_MAX_SLOT_MAP_COUNT 8 -/* i2s Configuration BLOB building blocks */ - -/* i2s registers for i2s Configuration */ +/** + * \brief Hardware register configuration values for Intel SSP/I2S controller. + * \ingroup ipc4_gateway_api + */ struct ipc4_ssp_config { - uint32_t ssc0; - uint32_t ssc1; - uint32_t sscto; - uint32_t sspsp; - uint32_t sstsa; - uint32_t ssrsa; - uint32_t ssc2; - uint32_t sspsp2; - uint32_t ssc3; - uint32_t ssioc; + uint32_t ssc0; /**< Serial Serial Control register 0 (mode, data size). */ + uint32_t ssc1; /**< Serial Serial Control register 1 (clocks, phase, polarity). */ + uint32_t sscto; /**< Serial Serial Control Timeout register. */ + uint32_t sspsp; /**< Serial Serial Port Serial Protocol register (frame sync timing). */ + uint32_t sstsa; /**< Serial Serial Tx Time Slot Active register. */ + uint32_t ssrsa; /**< Serial Serial Rx Time Slot Active register. */ + uint32_t ssc2; /**< Serial Serial Control register 2 (extended FIFO control). */ + uint32_t sspsp2; /**< Serial Serial Port Serial Protocol register 2. */ + uint32_t ssc3; /**< Serial Serial Control register 3. */ + uint32_t ssioc; /**< Serial Serial I/O Control register (pin directions). */ } __attribute__((packed, aligned(4))); +/** + * \brief Master Clock (MCLK) divider hardware configuration. + * \ingroup ipc4_gateway_api + */ struct ipc4_ssp_mclk_config { - /* master clock divider control register */ - uint32_t mdivc; - - /* master clock divider ratio register */ - uint32_t mdivr; + uint32_t mdivc; /**< Master clock divider control register. */ + uint32_t mdivr; /**< Master clock divider ratio register. */ } __attribute__((packed, aligned(4))); +/** + * \brief Combined SSP hardware and clock configuration structure. + * \ingroup ipc4_gateway_api + */ struct ipc4_ssp_driver_config { - struct ipc4_ssp_config i2s_config; - struct ipc4_ssp_mclk_config mclk_config; + struct ipc4_ssp_config i2s_config; /**< SSP controller register values. */ + struct ipc4_ssp_mclk_config mclk_config; /**< Master clock generator configuration. */ } __attribute__((packed, aligned(4))); +/** + * \brief SSP interface clock start control parameters. + * \ingroup ipc4_gateway_api + */ struct ipc4_ssp_start_control { - /* delay in msec between enabling interface (moment when - * Copier instance is being attached to the interface) and actual - * interface start. Value of 0 means no delay. + /** + * Delay in milliseconds between enabling interface (when Copier is attached) + * and actual interface start. Value of 0 means no delay. */ uint32_t clock_warm_up : 16; - /* specifies if parameters target MCLK (1) or SCLK (0) */ + /** Target clock: 1 for MCLK, 0 for SCLK. */ uint32_t mclk : 1; - /* value of 1 means that clock should be started immediately - * even if no Copier instance is currently attached to the interface. + /** + * 1 means start clock immediately even if no Copier is attached. */ uint32_t warm_up_ovr : 1; - uint32_t rsvd0 : 14; + uint32_t rsvd0 : 14; /**< Reserved padding. */ } __attribute__((packed, aligned(4))); +/** + * \brief SSP interface clock stop control parameters. + * \ingroup ipc4_gateway_api + */ struct ipc4_ssp_stop_control { - /* delay in msec between stopping the interface - * (moment when Copier instance is being detached from the interface) - * and interface clock stop. Value of 0 means no delay. + /** + * Delay in milliseconds between stopping interface (when Copier detaches) + * and stopping interface clocks. 0 means no delay. */ uint32_t clock_stop_delay : 16; - /* value of 1 means that clock should be kept running (infinite - * stop delay) after Copier instance detaches from the interface. - */ + /** 1 means keep clock running continuously after Copier detaches. */ uint32_t keep_running : 1; - /* value of 1 means that clock should be stopped immediately */ + /** 1 means stop clock immediately upon detachment. */ uint32_t clock_stop_ovr : 1; - uint32_t rsvd1 : 14; + uint32_t rsvd1 : 14; /**< Reserved padding. */ } __attribute__((packed, aligned(4))); +/** + * \brief SSP dynamic DMA and clock control union. + * \ingroup ipc4_gateway_api + */ union ipc4_ssp_dma_control { + /** Start and stop clock delay controls. */ struct ipc4_ssp_control { - struct ipc4_ssp_start_control start_control; - struct ipc4_ssp_stop_control stop_control; - } control_data; + struct ipc4_ssp_start_control start_control; /**< Clock warm-up parameters. */ + struct ipc4_ssp_stop_control stop_control; /**< Clock stop delay parameters. */ + } control_data; /**< Clock lifecycle controls. */ + /** Fractional M/N clock divider settings. */ struct ipc4_mn_div_config { - uint32_t mval; - uint32_t nval; - } mndiv_control_data; + uint32_t mval; /**< M numerator value. */ + uint32_t nval; /**< N denominator value. */ + } mndiv_control_data; /**< M/N divider ratio. */ } __attribute__((packed, aligned(4))); +/** + * \brief Full SSP/I2S gateway configuration blob structure. + * \ingroup ipc4_gateway_api + */ struct ipc4_ssp_configuration_blob { - union ipc4_gateway_attributes gw_attr; - - /* TDM time slot mappings */ - uint32_t tdm_ts_group[I2S_TDM_MAX_SLOT_MAP_COUNT]; - - /* i2s port configuration */ - struct ipc4_ssp_driver_config i2s_driver_config; - - /* optional configuration parameters */ - union ipc4_ssp_dma_control i2s_dma_control[]; + union ipc4_gateway_attributes gw_attr; /**< Gateway memory allocation attributes. */ + uint32_t tdm_ts_group[I2S_TDM_MAX_SLOT_MAP_COUNT]; /**< TDM time slot channel mappings. */ + struct ipc4_ssp_driver_config i2s_driver_config; /**< SSP controller and MCLK registers. */ + union ipc4_ssp_dma_control i2s_dma_control[]; /**< Optional dynamic DMA/clock controls. */ } __attribute__((packed, aligned(4))); #endif From 7104afacfa5b8d54b5989f52a2b5262634d22c2f Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 13 Oct 2026 16:13:03 +0100 Subject: [PATCH 7/9] doc: ipc4: document notifications, mailbox registers, probes, and logging Signed-off-by: Liam Girdwood --- src/include/ipc4/fw_reg.h | 200 +++++++++---------- src/include/ipc4/logging.h | 5 +- src/include/ipc4/notification.h | 336 +++++++++++++++++--------------- src/include/ipc4/probe.h | 72 ++++--- 4 files changed, 332 insertions(+), 281 deletions(-) diff --git a/src/include/ipc4/fw_reg.h b/src/include/ipc4/fw_reg.h index 4f55b2f3cf2f..744c5e457686 100644 --- a/src/include/ipc4/fw_reg.h +++ b/src/include/ipc4/fw_reg.h @@ -18,7 +18,7 @@ /** * \file include/ipc4/fw_reg.h * \brief IPC4 firmware registers in mailbox window 0 for host telemetry and status. - * \ingroup ipc4_api + * \ingroup ipc4_notification_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -30,157 +30,161 @@ #include #include -/* Reports current ROM/FW status. */ +/** + * \brief Firmware Status Register (FSR) located at offset 0x0 in Mailbox Window 0. + * \ingroup ipc4_notification_api + */ struct ipc4_fw_status_reg { - uint32_t state : 28; - /* Last module ID updated FSR */ - uint32_t module : 3; - /* State of DSP core */ - uint32_t running : 1; + uint32_t state : 28; /**< Current firmware execution / boot state. */ + uint32_t module : 3; /**< Last module ID that updated FSR. */ + uint32_t running : 1; /**< DSP core active execution flag (1 = running). */ } __attribute__((packed, aligned(4))); +/** + * \brief Last error code reported by ROM or Base FW. + * \ingroup ipc4_notification_api + */ typedef uint32_t ipc4_last_error; +/** + * \brief Firmware power and clock status register (offset 0x8 in Mailbox Window 0). + * \ingroup ipc4_notification_api + */ struct ipc4_fw_pwr_status { - /* currently set astate */ - uint32_t curr_astate : 4; - /* cached IMR usage status for previous D0i3 */ - uint32_t cached_imr_usage_status : 1; - uint32_t curr_fstate : 3; - uint32_t wake_tick_period : 5; - uint32_t active_pipelines_count : 6; - uint32_t rsvd0 : 13; + uint32_t curr_astate : 4; /**< Currently active A-state index. */ + uint32_t cached_imr_usage_status : 1; /**< Cached IMR usage status from previous D0i3. */ + uint32_t curr_fstate : 3; /**< Currently active F-state index. */ + uint32_t wake_tick_period : 5; /**< Wake tick period configuration. */ + uint32_t active_pipelines_count : 6; /**< Number of currently active pipelines. */ + uint32_t rsvd0 : 13; /**< Reserved padding bits. */ } __attribute__((packed, aligned(4))); +/** + * \brief Pipeline DMA tracking registers in Mailbox Window 0. + * \ingroup ipc4_notification_api + */ struct ipc4_pipeline_registers { /** * Stream start offset (LPIB) reported by mixin module allocated on pipeline attached * to Host Output Gateway when first data is being mixed to mixout module. When data * is not mixed (right after creation/after reset) value "(uint64_t)-1" is reported. * In number of bytes. - * */ + */ uint64_t stream_start_offset; /** * Stream end offset (LPIB) reported by mixin module allocated on pipeline attached * to Host Output Gateway during transition from RUNNING to PAUSED. When data * is not mixed (right after creation/after reset) value "(uint64_t)-1" is reported. When - * first data is mixed then value "0"is reported. + * first data is mixed then value "0" is reported. * In number of bytes. - * */ + */ uint64_t stream_end_offset; } __attribute__((packed, aligned(8))); +/** \brief Maximum audio channels supported in PeakVol telemetry registers. */ #define IPC4_PV_MAX_SUPPORTED_CHANNELS 8 + +/** + * \brief Peak volume and meter registers for low-latency host inspection. + * \ingroup ipc4_notification_api + */ struct ipc4_peak_volume_regs { - uint32_t peak_meter[IPC4_PV_MAX_SUPPORTED_CHANNELS]; - uint32_t current_volume[IPC4_PV_MAX_SUPPORTED_CHANNELS]; - uint32_t target_volume[IPC4_PV_MAX_SUPPORTED_CHANNELS]; + uint32_t peak_meter[IPC4_PV_MAX_SUPPORTED_CHANNELS]; /**< Real-time per-channel peak meter values. */ + uint32_t current_volume[IPC4_PV_MAX_SUPPORTED_CHANNELS]; /**< Current attenuated volume levels. */ + uint32_t target_volume[IPC4_PV_MAX_SUPPORTED_CHANNELS]; /**< Target ramping volume levels. */ } __attribute__((packed, aligned(4))); +/** + * \brief Link Linear Position (LLP) and wallclock snapshot. + * \ingroup ipc4_notification_api + */ struct ipc4_llp_reading { - /* lower part of 64-bit LLP */ - uint32_t llp_l; - /* upper part of 64-bit LLP */ - uint32_t llp_u; - /* lower part of 64-bit Wallclock */ - uint32_t wclk_l; - /* upper part of 64-bit Wallclock */ - uint32_t wclk_u; + uint32_t llp_l; /**< Lower 32 bits of 64-bit Link Linear Position. */ + uint32_t llp_u; /**< Upper 32 bits of 64-bit Link Linear Position. */ + uint32_t wclk_l; /**< Lower 32 bits of 64-bit DSP wallclock. */ + uint32_t wclk_u; /**< Upper 32 bits of 64-bit DSP wallclock. */ } __attribute__((packed, aligned(4))); +/** + * \brief Extended Link Linear Position reading with total processed data bytes. + * \ingroup ipc4_notification_api + */ struct ipc4_llp_reading_extended { - struct ipc4_llp_reading llp_reading; - /* total processed data (low part) */ - uint32_t tpd_low; - /* total processed data (high part) */ - uint32_t tpd_high; + struct ipc4_llp_reading llp_reading; /**< Base LLP and wallclock reading. */ + uint32_t tpd_low; /**< Lower 32 bits of total processed data bytes. */ + uint32_t tpd_high; /**< Upper 32 bits of total processed data bytes. */ } __attribute__((packed, aligned(4))); +/** + * \brief Mailbox Window 0 reading slot for a single gateway. + * \ingroup ipc4_notification_api + */ struct ipc4_llp_reading_slot { - uint32_t node_id; - struct ipc4_llp_reading reading; + uint32_t node_id; /**< Audio gateway connector node ID. */ + struct ipc4_llp_reading reading; /**< Corresponding LLP position reading. */ } __attribute__((packed, aligned(4))); +/** + * \brief ROM build, version, and load capability information. + * \ingroup ipc4_notification_api + */ union ipc4_rom_info { struct { - uint32_t fuse_values: 8; - uint32_t load_method: 1; - uint32_t downlink_IPC_use_DMA: 1; - uint32_t load_method_reserved: 2; - uint32_t implementation_revision_min: 4; - uint32_t implementation_revision_maj: 4; - uint32_t implementation_version_min: 4; - uint32_t implementation_version_maj: 4; - uint32_t reserved : 4; - } bits; + uint32_t fuse_values: 8; /**< Hardware fuse configuration values. */ + uint32_t load_method: 1; /**< Image loading method (DMA or memory). */ + uint32_t downlink_IPC_use_DMA: 1; /**< 1 if downlink IPC uses DMA buffer. */ + uint32_t load_method_reserved: 2; /**< Reserved load bits. */ + uint32_t implementation_revision_min: 4; /**< Minor implementation revision. */ + uint32_t implementation_revision_maj: 4; /**< Major implementation revision. */ + uint32_t implementation_version_min: 4; /**< Minor implementation version. */ + uint32_t implementation_version_maj: 4; /**< Major implementation version. */ + uint32_t reserved : 4; /**< Reserved padding bits. */ + } bits; /**< Bitfield layout. */ struct { - uint32_t rsvd1: 16; - uint32_t type: 12; - uint32_t rsvd2: 4; - } platform; + uint32_t rsvd1: 16; /**< Reserved bits. */ + uint32_t type: 12; /**< Platform architecture type identifier. */ + uint32_t rsvd2: 4; /**< Reserved bits. */ + } platform; /**< Platform interpretation. */ } __attribute__((packed, aligned(4))); -/* Number of dsp core supported in FW Regs. */ +/** \brief Maximum number of DSP cores supported in firmware register table. */ #define IPC4_MAX_SUPPORTED_ADSP_CORES 8 -/* Number of pipeline registers slots in FW Regs. */ +/** \brief Number of pipeline register slots in firmware register table. */ #define IPC4_MAX_PIPELINE_REG_SLOTS 16 -/* Number of PeakVol registers slots in FW Regs. */ +/** \brief Number of PeakVol register slots in firmware register table. */ #define IPC4_MAX_PEAK_VOL_REG_SLOTS 16 -/* Number of GPDMA LLP Reading slots in FW Regs. */ +/** \brief Number of GPDMA LLP reading slots in firmware register table. */ #define IPC4_MAX_LLP_GPDMA_READING_SLOTS 24 -/* Number of Aggregated SNDW Reading slots in FW Regs. */ +/** \brief Number of Aggregated SoundWire reading slots in firmware register table. */ #define IPC4_MAX_LLP_SNDW_READING_SLOTS 16 -/* Current ABI version of the FwRegisters layout. */ +/** \brief Current ABI version of the Mailbox Window 0 FwRegisters layout. */ #define IPC4_FW_REGS_ABI_VER 1 -/* FW Registers exposes additional DSP / FW state information to the driver. */ +/** + * \brief Mailbox Window 0 firmware register layout exposed to host driver. + * \ingroup ipc4_notification_api + */ struct ipc4_fw_registers { - /* Current ROM / FW status(at 0x0) */ - struct ipc4_fw_status_reg fsr; - - /* Last ROM / FW error code(at 0x4). */ - ipc4_last_error lec; - - /* Current DSP clock status(at 0x8). */ - struct ipc4_fw_pwr_status fps; - - /* Last Native Error Code(from external library) (at 0xC). */ - uint32_t lnec; - - /* Copy of LTRC HW register value(FW only) (at 0x10). */ - uint32_t ltr; - - uint32_t rsvd0; - - /* ROM info(at 0x18). */ - union ipc4_rom_info rom_info; - - /* Version of the layout, set to the current FW_REGS_ABI_VER (at 0x1C). */ - uint32_t abi_ver; - - uint8_t slave_core_sts[IPC4_MAX_SUPPORTED_ADSP_CORES]; - - uint32_t rsvd2[6]; - - /* State of pipelines attached to host output gateways. */ - struct ipc4_pipeline_registers pipeline_regs[IPC4_MAX_PIPELINE_REG_SLOTS]; - - /* State of PeakVol instances, indexed by the PeakVol's instance_id. */ - struct ipc4_peak_volume_regs peak_vol_regs[IPC4_MAX_PEAK_VOL_REG_SLOTS]; - - /* LLP Readings for single link gateways. */ - struct ipc4_llp_reading_slot llp_gpdma_reading_slots[IPC4_MAX_LLP_GPDMA_READING_SLOTS]; - - /* LLP Readings for SNDW aggregated link gateways. */ - struct ipc4_llp_reading_slot llp_sndw_reading_slots[IPC4_MAX_LLP_SNDW_READING_SLOTS - 1]; - - /* LLP Readings for EVAD gateway. */ - struct ipc4_llp_reading_slot llp_evad_reading_slot; + struct ipc4_fw_status_reg fsr; /**< Current ROM / FW status (at offset 0x0). */ + ipc4_last_error lec; /**< Last ROM / FW error code (at offset 0x4). */ + struct ipc4_fw_pwr_status fps; /**< Current DSP power / clock status (at offset 0x8). */ + uint32_t lnec; /**< Last Native Error Code from external library (at offset 0xC). */ + uint32_t ltr; /**< Copy of LTRC hardware register value (at offset 0x10). */ + uint32_t rsvd0; /**< Reserved padding. */ + union ipc4_rom_info rom_info; /**< ROM version and load capabilities (at offset 0x18). */ + uint32_t abi_ver; /**< Layout version (IPC4_FW_REGS_ABI_VER at offset 0x1C). */ + uint8_t slave_core_sts[IPC4_MAX_SUPPORTED_ADSP_CORES]; /**< Status byte per secondary core. */ + uint32_t rsvd2[6]; /**< Reserved padding. */ + struct ipc4_pipeline_registers pipeline_regs[IPC4_MAX_PIPELINE_REG_SLOTS]; /**< Pipeline LPIB offsets. */ + struct ipc4_peak_volume_regs peak_vol_regs[IPC4_MAX_PEAK_VOL_REG_SLOTS]; /**< Peak meter telemetry. */ + struct ipc4_llp_reading_slot llp_gpdma_reading_slots[IPC4_MAX_LLP_GPDMA_READING_SLOTS]; /**< GPDMA LLP readings. */ + struct ipc4_llp_reading_slot llp_sndw_reading_slots[IPC4_MAX_LLP_SNDW_READING_SLOTS - 1]; /**< SoundWire LLP readings. */ + struct ipc4_llp_reading_slot llp_evad_reading_slot; /**< EVAD gateway LLP reading. */ } __attribute__((packed, aligned(4))); #endif diff --git a/src/include/ipc4/logging.h b/src/include/ipc4/logging.h index 3fda5201267b..32548b23fb73 100644 --- a/src/include/ipc4/logging.h +++ b/src/include/ipc4/logging.h @@ -6,16 +6,18 @@ /** * @file ipc4/logging.h * @brief IPC4 host logging control and configuration interface. - * @ingroup ipc4_api + * @ingroup ipc4_telemetry_probe_api */ #ifndef __SOF_IPC4_LOGGING_H__ #define __SOF_IPC4_LOGGING_H__ +/** \brief Page size in bytes for mtrace memory window DMA logging buffers. */ #define SOF_IPC4_LOGGING_MTRACE_PAGE_SIZE 0x1000 /** * @brief Configure and enable firmware logging requested by the host via IPC4. + * @ingroup ipc4_telemetry_probe_api * @param first_block True if this buffer is the first chunk of logging configuration. * @param last_block True if this buffer is the final chunk of logging configuration. * @param data_offset_or_size Byte offset or payload size of the configuration block. @@ -29,6 +31,7 @@ int ipc4_logging_enable_logs(bool first_block, /** * @brief Shutdown active IPC4 firmware logging and flush remaining trace buffers. + * @ingroup ipc4_telemetry_probe_api * @return 0 on success, negative error code on failure. */ int ipc4_logging_shutdown(void); diff --git a/src/include/ipc4/notification.h b/src/include/ipc4/notification.h index 870cef798407..5ff63ab60758 100644 --- a/src/include/ipc4/notification.h +++ b/src/include/ipc4/notification.h @@ -18,7 +18,7 @@ /** * \file include/ipc4/notification.h * \brief IPC4 asynchronous notifications, GLITCH reports, and FW ready events. - * \ingroup ipc4_api + * \ingroup ipc4_notification_api */ #ifndef __IPC4_NOTIFICATION_H__ @@ -29,121 +29,101 @@ #include #include -/* ipc4 notification msg */ +/** + * \brief Unsolicited DSP-to-host asynchronous notification types. + * \ingroup ipc4_notification_api + */ enum sof_ipc4_notification_type { - SOF_IPC4_NOTIFY_PHRASE_DETECTED = 4, - SOF_IPC4_NOTIFY_RESOURCE_EVENT = 5, - SOF_IPC4_NOTIFY_LOG_BUFFER_STATUS = 6, - SOF_IPC4_NOTIFY_TIMESTAMP_CAPTURED = 7, - SOF_IPC4_NOTIFY_FW_READY = 8, - SOF_IPC4_FW_AUD_CLASS_RESULT = 9, - SOF_IPC4_EXCEPTION_CAUGHT = 10, - SOF_IPC4_MODULE_NOTIFICATION = 12, - SOF_IPC4_UAOL_EVENT = 13, - SOF_IPC4_PROBE_DATA_AVAILABLE = 14, - SOF_IPC4_WATCHDOG_TIMEOUT = 15, - SOF_IPC4_MANAGEMENT_SERVICE = 16, + SOF_IPC4_NOTIFY_PHRASE_DETECTED = 4, /**< Key phrase detected by wake-on-voice engine. */ + SOF_IPC4_NOTIFY_RESOURCE_EVENT = 5, /**< Resource event (underrun, overrun, budget violation). */ + SOF_IPC4_NOTIFY_LOG_BUFFER_STATUS = 6, /**< Trace log buffer half-full or aging timer expired. */ + SOF_IPC4_NOTIFY_TIMESTAMP_CAPTURED = 7, /**< Audio wallclock timestamp captured. */ + SOF_IPC4_NOTIFY_FW_READY = 8, /**< Firmware initialization complete and ready for IPC. */ + SOF_IPC4_FW_AUD_CLASS_RESULT = 9, /**< Audio classifier / acoustic event result. */ + SOF_IPC4_EXCEPTION_CAUGHT = 10, /**< Critical DSP exception or panic caught. */ + SOF_IPC4_MODULE_NOTIFICATION = 12, /**< Generic module-specific event notification. */ + SOF_IPC4_UAOL_EVENT = 13, /**< USB Audio Offload event notification. */ + SOF_IPC4_PROBE_DATA_AVAILABLE = 14, /**< Probe extraction buffer contains recorded audio. */ + SOF_IPC4_WATCHDOG_TIMEOUT = 15, /**< Watchdog timer timeout interrupt on DSP core. */ + SOF_IPC4_MANAGEMENT_SERVICE = 16, /**< System management service event notification. */ }; /** - * \brief Resource Event Notification provides unified structure for events that may be raised by - * identifiable entity from inside the FW. + * \brief Specific resource event types reported by identifiable FW entities. + * \ingroup ipc4_notification_api */ enum sof_ipc4_resource_event_type { - /* MCPS budget for the module exceeded */ - SOF_IPC4_BUDGET_VIOLATION = 0, - /* Underrun detected by the Mixer */ - SOF_IPC4_MIXER_UNDERRUN_DETECTED = 1, - /* Stream data segment completed by the gateway */ - SOF_IPC4_STREAM_DATA_SEGMENT = 2, - /* Error caught during data processing */ - SOF_IPC4_PROCESS_DATA_ERROR = 3, - /* Stack overflow in a module instance */ - SOF_IPC4_STACK_OVERFLOW = 4, - /* KPB changed buffering mode */ - SOF_IPC4_BUFFERING_MODE_CHANGED = 5, - /* Underrun detected by gateway. */ - SOF_IPC4_GATEWAY_UNDERRUN_DETECTED = 6, - /* Overrun detected by gateway */ - SOF_IPC4_GATEWAY_OVERRUN_DETECTED = 7, - /* DP task missing the deadline */ - SOF_IPC4_EDF_DOMAIN_UNSTABLE = 8, - /* Watchdog notification */ - SOF_IPC4_WATCHDOG_EVENT = 9, - /* IPC gateway reached high threshold */ - SOF_IPC4_GATEWAY_HIGH_THRES = 10, - /* IPC gateway reached low threshold */ - SOF_IPC4_GATEWAY_LOW_THRES = 11, - /* Bit Count Error detected on I2S port */ - SOF_IPC4_I2S_BCE_DETECTED = 12, - /* Clock detected/loss on I2S port */ - SOF_IPC4_I2S_CLK_STATE_CHANGED = 13, - /* I2S Sink started/stopped dropping data in non-blk mode */ - SOF_IPC4_I2S_SINK_MODE_CHANGED = 14, - /* I2S Source started/stopped generating 0's in non-blk mode */ - SOF_IPC4_I2S_SOURCE_MODE_CHANGED = 15, - /* Frequency drift exceeded limit in SRE */ - SOF_IPC4_SRE_DRIFT_TOO_HIGH = 16, - /* The notification should be sent only once after exceeding threshold or aging timer. */ - SOF_IPC4_TELEMETRY_DATA_STATUS = 17, - /* SNDW debug notification e.g. external VAD detected */ - SOF_IPC4_SNDW_DEBUG_INFO = 18, - /* Invalid type */ - SOF_IPC4_INVALID_RESOURCE_EVENT_TYPE = 19, + SOF_IPC4_BUDGET_VIOLATION = 0, /**< MCPS budget for module or core exceeded. */ + SOF_IPC4_MIXER_UNDERRUN_DETECTED = 1, /**< Underrun detected by mixer/mixin component. */ + SOF_IPC4_STREAM_DATA_SEGMENT = 2, /**< Stream data segment completed by gateway. */ + SOF_IPC4_PROCESS_DATA_ERROR = 3, /**< Error caught during audio processing. */ + SOF_IPC4_STACK_OVERFLOW = 4, /**< Stack overflow detected in module or thread. */ + SOF_IPC4_BUFFERING_MODE_CHANGED = 5, /**< Key Phrase Buffer (KPB) buffering mode changed. */ + SOF_IPC4_GATEWAY_UNDERRUN_DETECTED = 6, /**< Underrun detected at peripheral DMA gateway. */ + SOF_IPC4_GATEWAY_OVERRUN_DETECTED = 7, /**< Overrun detected at peripheral DMA gateway. */ + SOF_IPC4_EDF_DOMAIN_UNSTABLE = 8, /**< Data-processing EDF task missed its deadline. */ + SOF_IPC4_WATCHDOG_EVENT = 9, /**< Watchdog expiration event. */ + SOF_IPC4_GATEWAY_HIGH_THRES = 10, /**< IPC gateway reached high watermark threshold. */ + SOF_IPC4_GATEWAY_LOW_THRES = 11, /**< IPC gateway reached low watermark threshold. */ + SOF_IPC4_I2S_BCE_DETECTED = 12, /**< Bit Count Error detected on I2S/SSP port. */ + SOF_IPC4_I2S_CLK_STATE_CHANGED = 13, /**< Clock state change (detected/lost) on I2S port. */ + SOF_IPC4_I2S_SINK_MODE_CHANGED = 14, /**< I2S sink mode change (started/stopped dropping). */ + SOF_IPC4_I2S_SOURCE_MODE_CHANGED = 15, /**< I2S source mode change (started/stopped zero-fill). */ + SOF_IPC4_SRE_DRIFT_TOO_HIGH = 16, /**< Sample Rate Estimator frequency drift exceeded limit. */ + SOF_IPC4_TELEMETRY_DATA_STATUS = 17, /**< Telemetry buffer exceeded threshold or aged. */ + SOF_IPC4_SNDW_DEBUG_INFO = 18, /**< SoundWire debug notification (e.g. external VAD). */ + SOF_IPC4_INVALID_RESOURCE_EVENT_TYPE = 19, /**< Invalid resource event sentinel. */ }; -/* Resource Type - source of the event */ +/** + * \brief Originator resource category firing a resource event. + * \ingroup ipc4_notification_api + */ enum sof_ipc4_resource_type { - /* Module instance */ - SOF_IPC4_MODULE_INSTANCE = 0, - /* Pipeline */ - SOF_IPC4_PIPELINE = 1, - /* Gateway */ - SOF_IPC4_GATEWAY = 2, - /* EDF Task*/ - SOF_IPC4_EDF_TASK = 3, - /* Invalid type */ - SOF_IPC4_INVALID_RESOURCE_TYPE = 4, + SOF_IPC4_MODULE_INSTANCE = 0, /**< Event originated from a module instance. */ + SOF_IPC4_PIPELINE = 1, /**< Event originated from a pipeline. */ + SOF_IPC4_GATEWAY = 2, /**< Event originated from a DMA gateway. */ + SOF_IPC4_EDF_TASK = 3, /**< Event originated from an EDF DP task. */ + SOF_IPC4_INVALID_RESOURCE_TYPE = 4, /**< Invalid resource type sentinel. */ }; +/** \brief Global notification direction bitmask. */ #define SOF_IPC4_GLB_NOTIFY_DIR_MASK BIT(29) +/** \brief Reply status mask in primary register. */ #define SOF_IPC4_REPLY_STATUS_MASK 0xFFFFFF +/** \brief Bit shift for notification type in primary register. */ #define SOF_IPC4_GLB_NOTIFY_TYPE_SHIFT 16 +/** \brief Bit shift for message type in primary register. */ #define SOF_IPC4_GLB_NOTIFY_MSG_TYPE_SHIFT 24 +/** \brief Pre-computed header word for FW_READY notification. */ #define SOF_IPC4_FW_READY \ (((SOF_IPC4_NOTIFY_FW_READY) << (SOF_IPC4_GLB_NOTIFY_TYPE_SHIFT)) |\ ((SOF_IPC4_GLB_NOTIFICATION) << (SOF_IPC4_GLB_NOTIFY_MSG_TYPE_SHIFT))) +/** \brief FW_READY extension flag indicating dynamic libraries were restored. */ #define SOF_IPC4_FW_READY_LIB_RESTORED BIT(15) +/** \brief Helper macro to construct notification primary header DWORD. */ #define SOF_IPC4_NOTIF_HEADER(notif_type) \ ((notif_type) << (SOF_IPC4_GLB_NOTIFY_TYPE_SHIFT) | \ ((SOF_IPC4_GLB_NOTIFICATION) << (SOF_IPC4_GLB_NOTIFY_MSG_TYPE_SHIFT))) /** - * \brief IPC MAJOR 4 notification header. All IPC4 notifications use this header. + * \brief Standard 32-bit IPC4 notification primary header word. + * \ingroup ipc4_notification_api */ union ipc4_notification_header { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit register value. */ struct { - uint32_t rsvd0 : 16; - - /**< Notification::MODULE_EVENT */ - uint32_t notif_type : 8; - - /**< One of Global::Type */ - uint32_t type : 5; - - /**< Msg::MSG_REQUEST */ - uint32_t rsp : 1; - - /**< Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - - uint32_t _reserved_0 : 1; - } r; + uint32_t rsvd0 : 16; /**< Reserved bits. */ + uint32_t notif_type : 8; /**< Notification type (enum sof_ipc4_notification_type). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_NOTIFICATION (23). */ + uint32_t rsp : 1; /**< Message direction: 0 for request/notification. */ + uint32_t msg_tgt : 1; /**< Message target: 0 for global message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ + } r; /**< Bitfield layout. */ } __packed __aligned(4); /** @@ -163,58 +143,61 @@ struct ipc4_voice_cmd_notification { /**< Msg::MSG_NOTIFICATION */ uint32_t rsp : 1; /**< Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _reserved_0 : 1; - } r; - } primary; + uint32_t msg_tgt : 1; /**< Message target: 0 for global message. */ + uint32_t _reserved_0 : 1; /**< Reserved bit. */ + } r; /**< Primary bitfields. */ + } primary; /**< Primary 32-bit register union. */ union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit register value. */ struct { - /**< Final speaker verification score in range of 0..8192 */ - uint32_t sv_score : 16; - uint32_t rsvd1 : 14; - uint32_t _reserved_2 : 2; - } r; - } extension; + uint32_t sv_score : 16; /**< Final speaker verification score (0..8192). */ + uint32_t rsvd1 : 14; /**< Reserved bits. */ + uint32_t _reserved_2 : 2; /**< Reserved bits. */ + } r; /**< Extension bitfields. */ + } extension; /**< Extension 32-bit register union. */ } __packed __aligned(4); /** - * \brief This notification is reported by the Base FW when DSP core receive WDT timeout interrupt. + * \brief Watchdog timeout notification structure (SOF_IPC4_WATCHDOG_TIMEOUT). + * \ingroup ipc4_notification_api + * + * Reported by Base FW when a DSP core encounters a watchdog timeout interrupt. */ struct ipc4_watchdog_timeout_notification { union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit register value. */ struct { - /* ID of a core that timeouted. */ - uint32_t core_id : 4; - /* Indicates that it was first timeout and crash dump was done */ - uint32_t first_timeout : 1; - uint32_t rsvd : 11; - /* Notification::WATCHDOG_TIMEOUT */ - uint32_t notif_type : 8; - /* Global::NOTIFICATION */ - uint32_t type : 5; - /* Msg::MSG_NOTIFICATION (0) */ - uint32_t rsp : 1; - /* Msg::FW_GEN_MSG */ - uint32_t msg_tgt : 1; - uint32_t _hw_rsvd_0 : 1; - } r; - } primary; + uint32_t core_id : 4; /**< ID of core that timed out. */ + uint32_t first_timeout : 1; /**< 1 if initial timeout and crash dump was taken. */ + uint32_t rsvd : 11; /**< Reserved padding. */ + uint32_t notif_type : 8; /**< SOF_IPC4_WATCHDOG_TIMEOUT. */ + uint32_t type : 5; /**< SOF_IPC4_GLB_NOTIFICATION. */ + uint32_t rsp : 1; /**< 0 for notification. */ + uint32_t msg_tgt : 1; /**< 0 for global message. */ + uint32_t _hw_rsvd_0 : 1; /**< Hardware reserved bit. */ + } r; /**< Primary bitfield layout. */ + } primary; /**< Primary register value. */ union { - uint32_t dat; + uint32_t dat; /**< Raw 32-bit register value. */ struct { - uint32_t rsvd1 : 30; - uint32_t _hw_rsvd_2 : 2; - } r; - } extension; + uint32_t rsvd1 : 30; /**< Reserved padding. */ + uint32_t _hw_rsvd_2 : 2; /**< Hardware reserved bits. */ + } r; /**< Extension bitfield layout. */ + } extension; /**< Extension register value. */ } __packed __aligned(4); +/** + * \brief Helper to initialize watchdog timeout notification structure. + * \ingroup ipc4_notification_api + * \param notif Pointer to watchdog timeout notification structure to initialize. + * \param core_id DSP core ID that timed out. + * \param first_timeout True if this is the first timeout event. + */ static inline void ipc4_notification_watchdog_init(struct ipc4_watchdog_timeout_notification *notif, uint32_t core_id, bool first_timeout) { @@ -234,78 +217,121 @@ static inline void ipc4_notification_watchdog_init(struct ipc4_watchdog_timeout_ } /** - * \brief This notification is sent by a shim of module instance on error raised by data processing - * function. - * - * In case of 3rd party IP error_code is set to its native error code returned by the 3rd party - * library. + * \brief Data payload for process data error event (SOF_IPC4_PROCESS_DATA_ERROR). + * \ingroup ipc4_notification_api */ struct ipc4_process_data_error_event_data { - /* Error code returned by data processing function */ - uint32_t error_code; + uint32_t error_code; /**< Native error code returned by processing function. */ }; /** - * \brief This notification is sent by the mixer on stream underrun detection. The frequency of - * sending this notification by Mixer depends on the MixIn settings. + * \brief Data payload for mixer underrun event (SOF_IPC4_MIXER_UNDERRUN_DETECTED). + * \ingroup ipc4_notification_api */ struct ipc4_mixer_underrun_event_data { - /* Indicates EndOfStream */ - uint32_t eos_flag; - /* Data processed by module (in bytes) */ - uint32_t data_mixed; - /* Expected data to be processed (in bytes) */ - uint32_t expected_data_mixed; + uint32_t eos_flag; /**< End-Of-Stream flag (1 if EOS reached). */ + uint32_t data_mixed; /**< Bytes of data successfully mixed. */ + uint32_t expected_data_mixed; /**< Expected bytes of data to be mixed. */ }; /** - * \brief Input data payload is reserved field in parent technical spec which can be easily - * extendable if needed by specific resource event types in the future. For backward compatibility - * the size of this structure is 6 dw. + * \brief Polymorphic payload for generic resource event notification. + * \ingroup ipc4_notification_api */ union ipc4_resource_event_data { - /* Raw data */ - uint32_t dws[6]; - /* Process Data Error Data (res type = MODULE_INSTANCE) */ - struct ipc4_process_data_error_event_data process_data_error; - /* Mixer Underrun Detected Data (res type = PIPELINE) */ - struct ipc4_mixer_underrun_event_data mixer_underrun; + uint32_t dws[6]; /**< Raw 6-DWORD data array for backwards compatibility. */ + struct ipc4_process_data_error_event_data process_data_error; /**< Process error payload. */ + struct ipc4_mixer_underrun_event_data mixer_underrun; /**< Mixer underrun payload. */ }; +/** + * \brief Full resource event notification structure sent in Mailbox Window 0. + * \ingroup ipc4_notification_api + */ struct ipc4_resource_event_data_notification { - /* Type of originator (see sof_ipc4_resource_type) */ - uint32_t resource_type; - /* ID of resource firing event */ - uint32_t resource_id; - /* Type of fired event (see sof_ipc4_resource_event_type enum) */ - uint32_t event_type; - /* Explicit alignment as ipc4_resource_event_data contains 64bit fields and needs - * alignment - */ - uint32_t reserved0; - /* Detailed event data */ - union ipc4_resource_event_data event_data; + uint32_t resource_type; /**< Source category (enum sof_ipc4_resource_type). */ + uint32_t resource_id; /**< Instance identifier of the firing entity. */ + uint32_t event_type; /**< Event type (enum sof_ipc4_resource_event_type). */ + uint32_t reserved0; /**< Explicit alignment padding for 64-bit alignment. */ + union ipc4_resource_event_data event_data; /**< Event-specific data union. */ } __packed __aligned(8); +/** \brief Size in bytes of resource event notification data packet. */ #define IPC4_RESOURCE_EVENT_SIZE sizeof(struct ipc4_resource_event_data_notification) +/** + * \brief Send process data error notification message to host. + * \ingroup ipc4_notification_api + * \param resource_id ID of module instance encountering error. + * \param error_code Module-specific error code. + */ void send_process_data_error_notif_msg(uint32_t resource_id, uint32_t error_code); +/** + * \brief Send Copier gateway xrun (underrun/overrun) notification to host. + * \ingroup ipc4_notification_api + * \param pipeline_id Target pipeline identifier. + * \param dir Stream direction (playback underrun or capture overrun). + * \return True if sent successfully, false otherwise. + */ bool send_copier_gateway_xrun_notif_msg(uint32_t pipeline_id, enum sof_ipc_stream_direction dir); + +/** + * \brief Send DMA gateway xrun notification to host. + * \ingroup ipc4_notification_api + * \param resource_id Gateway connector node ID. + * \param dir Stream direction. + * \return True if sent successfully, false otherwise. + */ bool send_gateway_xrun_notif_msg(uint32_t resource_id, enum sof_ipc_stream_direction dir); +/** + * \brief Send mixer underrun notification message to host. + * \ingroup ipc4_notification_api + * \param resource_id Target mixer pipeline identifier. + * \param eos_flag End of stream flag. + * \param data_mixed Actual bytes mixed. + * \param expected_data_mixed Expected bytes mixed. + */ void send_mixer_underrun_notif_msg(uint32_t resource_id, uint32_t eos_flag, uint32_t data_mixed, uint32_t expected_data_mixed); + +/** + * \brief Update host notification enable/disable bitmasks. + * \ingroup ipc4_notification_api + * \param ntfy_mask Bitmask of notifications to update. + * \param enabled_mask Target state (1 = enable, 0 = disable) for selected bits. + */ void ipc4_update_notification_mask(uint32_t ntfy_mask, uint32_t enabled_mask); #if defined(__ZEPHYR__) && defined(CONFIG_SOF_FULL_ZEPHYR_APPLICATION) +/** + * \brief Send generic resource event notification. + * \ingroup ipc4_notification_api + * \param resource_id ID of originator resource. + * \param event_type Event type (enum sof_ipc4_resource_event_type). + * \param resource_type Resource category (enum sof_ipc4_resource_type). + * \param data Pointer to event payload. + * \param data_size Size of event payload in bytes. + * \return True on success, false on failure. + */ __syscall bool send_resource_notif(uint32_t resource_id, uint32_t event_type, uint32_t resource_type, void *data, uint32_t data_size); #include #else +/** + * \brief Implementation of send_resource_notif for non-Zephyr builds. + * \ingroup ipc4_notification_api + * \param resource_id ID of originator resource. + * \param event_type Event type (enum sof_ipc4_resource_event_type). + * \param resource_type Resource category (enum sof_ipc4_resource_type). + * \param data Pointer to event payload. + * \param data_size Size of event payload in bytes. + * \return True on success, false on failure. + */ bool z_impl_send_resource_notif(uint32_t resource_id, uint32_t event_type, uint32_t resource_type, void *data, uint32_t data_size); #define send_resource_notif z_impl_send_resource_notif diff --git a/src/include/ipc4/probe.h b/src/include/ipc4/probe.h index 96efc1bb7acd..d2fc0a40cd97 100644 --- a/src/include/ipc4/probe.h +++ b/src/include/ipc4/probe.h @@ -15,9 +15,10 @@ * original so it's easier to track changes with IPC host code. */ -/* +/** * \file include/ipc4/probe.h - * \brief probe ipc4 definitions. + * \brief IPC4 audio probe injection, extraction, and DMA definitions. + * \ingroup ipc4_telemetry_probe_api * NOTE: This ABI uses bit fields and is non portable. */ @@ -29,69 +30,86 @@ #include #include -/* - * Buffer id used in the probe output stream headers for - * logging data packet. +/** + * \brief Buffer ID used in probe output stream headers for logging data packet. */ #define PROBE_LOGGING_BUFFER_ID 0x01000000 +/** \brief Probe extraction mode: extract audio from pipeline to host. */ #define PROBE_PURPOSE_EXTRACTION 0 +/** \brief Probe injection mode: inject host audio into pipeline. */ #define PROBE_PURPOSE_INJECTION 1 +/** \brief Probe point attached to module input pin. */ #define PROBE_TYPE_INPUT 0 +/** \brief Probe point attached to module output pin. */ #define PROBE_TYPE_OUTPUT 1 +/** \brief Probe point attached to internal module buffer. */ #define PROBE_TYPE_INTERNAL 2 +/** \brief Probe module parameter: add injection DMA channel. */ #define IPC4_PROBE_MODULE_INJECTION_DMA_ADD 1 +/** \brief Probe module parameter: detach injection DMA channel. */ #define IPC4_PROBE_MODULE_INJECTION_DMA_DETACH 2 +/** \brief Probe module parameter: connect probe points. */ #define IPC4_PROBE_MODULE_PROBE_POINTS_ADD 3 +/** \brief Probe module parameter: disconnect probe points. */ #define IPC4_PROBE_MODULE_DISCONNECT_PROBE_POINTS 4 +/** \brief Probe module parameter: query active/available probe points. */ #define IPC4_PROBE_MODULE_AVAILABLE_PROBE_POINTS 5 /** - * Description of probe dma + * \brief Probe DMA channel descriptor. + * \ingroup ipc4_telemetry_probe_api */ struct probe_dma { - uint32_t stream_tag; /**< Node_id associated with this DMA */ - uint32_t dma_buffer_size; /**< Size of buffer associated with this DMA */ + uint32_t stream_tag; /**< Node ID / stream tag associated with this DMA. */ + uint32_t dma_buffer_size; /**< Size of buffer in bytes associated with this DMA. */ } __attribute__((packed, aligned(4))); /** - * Description of probe point id + * \brief Unique identifier for a probe attachment point. + * \ingroup ipc4_telemetry_probe_api */ typedef union probe_point_id { - uint32_t full_id; + uint32_t full_id; /**< Raw 32-bit probe point identifier. */ struct { - uint32_t module_id : 16; /**< Target module ID */ - uint32_t instance_id : 8; /**< Target module instance ID */ - uint32_t type : 2; /**< Probe point type as specified by ProbeType enumeration */ - uint32_t index : 6; /**< Queue index inside target module */ - } fields; + uint32_t module_id : 16; /**< Target module ID. */ + uint32_t instance_id : 8; /**< Target module instance ID. */ + uint32_t type : 2; /**< Probe point type (PROBE_TYPE_xxx). */ + uint32_t index : 6; /**< Pin / queue index inside target module. */ + } fields; /**< Bitfield access structure. */ } __attribute__((packed, aligned(4))) probe_point_id_t; /** - * Description of probe point + * \brief Probe point attachment descriptor. + * \ingroup ipc4_telemetry_probe_api */ struct probe_point { - probe_point_id_t buffer_id; /**< ID of buffer to which probe is attached */ - uint32_t purpose; /**< PROBE_PURPOSE_xxx */ - uint32_t stream_tag; /**< Stream tag of DMA via which data will be provided for injection. - * For extraction purposes, stream tag is ignored when received, - * but returned actual extraction stream tag via INFO function. - */ + probe_point_id_t buffer_id; /**< ID of module buffer/pin to which probe is attached. */ + uint32_t purpose; /**< Extraction or injection (PROBE_PURPOSE_xxx). */ + uint32_t stream_tag; /**< Stream tag of DMA providing data for injection or receiving extraction. */ } __attribute__((packed, aligned(4))); +/** + * \brief Discovery response listing active probe points or DMA channels. + * \ingroup ipc4_telemetry_probe_api + */ struct sof_ipc_probe_info_params { - uint32_t num_elems; /**< Count of elements in array */ + uint32_t num_elems; /**< Count of elements in payload array. */ union { - struct probe_dma probe_dma[0]; /**< DMA info */ - struct probe_point probe_point[0]; /**< Probe Point info */ + struct probe_dma probe_dma[0]; /**< Array of active DMA descriptors. */ + struct probe_point probe_point[0]; /**< Array of active probe point descriptors. */ }; } __attribute__((packed, aligned(4))); +/** + * \brief Probe module configuration structure. + * \ingroup ipc4_telemetry_probe_api + */ struct ipc4_probe_module_cfg { - struct ipc4_base_module_cfg base_cfg; - struct probe_dma gtw_cfg; + struct ipc4_base_module_cfg base_cfg; /**< Base module configuration parameters. */ + struct probe_dma gtw_cfg; /**< Associated probe gateway DMA configuration. */ } __packed __aligned(4); #endif /* __SOF_IPC4_PROBE_H__ */ From a9401fe47c4860bfffb39da3169ebda3114ab983 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 13 Oct 2026 16:26:55 +0100 Subject: [PATCH 8/9] doc: ipc4: fix Doxygen comment syntax on preceding enum and struct members 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 --- src/include/ipc4/detect_test.h | 6 +- src/include/ipc4/error_status.h | 84 +++++++++++++-------------- src/include/ipc4/header.h | 76 ++++++++++++------------ src/include/ipc4/kpb.h | 4 +- src/include/ipc4/module.h | 54 ++++++++--------- src/include/ipc4/notification.h | 13 ++--- src/include/ipc4/pipeline.h | 20 +++---- src/include/module/ipc4/base-config.h | 16 ++--- 8 files changed, 134 insertions(+), 139 deletions(-) diff --git a/src/include/ipc4/detect_test.h b/src/include/ipc4/detect_test.h index a3a46d1cf14d..3745f0098388 100644 --- a/src/include/ipc4/detect_test.h +++ b/src/include/ipc4/detect_test.h @@ -20,13 +20,13 @@ * \ingroup ipc4_telemetry_probe_api */ enum ipc4_detect_test_module_config_params { - /**< Send neural network keyword detection model binary blob via LargeConfigSet. */ + /** Send neural network keyword detection model binary blob via LargeConfigSet. */ IPC4_DETECT_TEST_SET_MODEL_BLOB = 1, - /**< Configure Keyword Detector operational thresholds and parameters via LargeConfigSet. */ + /** Configure Keyword Detector operational thresholds and parameters via LargeConfigSet. */ IPC4_DETECT_TEST_SET_CONFIG = 2, - /**< Query current Keyword Detector operational configuration via LargeConfigGet. */ + /** Query current Keyword Detector operational configuration via LargeConfigGet. */ IPC4_DETECT_TEST_GET_CONFIG = 3 }; diff --git a/src/include/ipc4/error_status.h b/src/include/ipc4/error_status.h index 679d9a425196..783cc19dc422 100644 --- a/src/include/ipc4/error_status.h +++ b/src/include/ipc4/error_status.h @@ -21,7 +21,7 @@ #ifndef __SOF_IPC4_ERROR_STATUS_H__ #define __SOF_IPC4_ERROR_STATUS_H__ -/**< Number of bits allocated for processing status in the Primary reply DWORD (24 bits). */ +/** Number of bits allocated for processing status in the Primary reply DWORD (24 bits). */ #define IPC4_IXC_STATUS_BITS 24 /** @@ -33,108 +33,108 @@ * convey subsystem-specific failures (module management, probes, gateways, and clocking). */ enum ipc4_status { - /**< The operation was successful */ + /** The operation was successful */ IPC4_SUCCESS = 0, - /**< Invalid parameter specified */ + /** Invalid parameter specified */ IPC4_ERROR_INVALID_PARAM = 1, - /**< Unknown message type specified */ + /** Unknown message type specified */ IPC4_UNKNOWN_MESSAGE_TYPE = 2, - /**< Not enough space in the IPC reply buffer to complete the request */ + /** Not enough space in the IPC reply buffer to complete the request */ IPC4_OUT_OF_MEMORY = 3, - /**< The system or resource is busy */ + /** The system or resource is busy */ IPC4_BUSY = 4, - /**< Replaced ADSP IPC PENDING (unused) - according to cAVS v0.5 */ + /** Replaced ADSP IPC PENDING (unused) - according to cAVS v0.5 */ IPC4_BAD_STATE = 5, - /**< Unknown error while processing the request */ + /** Unknown error while processing the request */ IPC4_FAILURE = 6, - /**< Unsupported operation requested */ + /** Unsupported operation requested */ IPC4_INVALID_REQUEST = 7, - /**< Specified resource not found */ + /** Specified resource not found */ IPC4_INVALID_RESOURCE_ID = 9, - /**< A resource's ID requested to be created is already assigned */ + /** A resource's ID requested to be created is already assigned */ IPC4_RESOURCE_ID_EXISTS = 10, - /**< Required resource is in invalid state */ + /** Required resource is in invalid state */ IPC4_INVALID_RESOURCE_STATE = 12, - /**< Requested power transition failed to complete */ + /** Requested power transition failed to complete */ IPC4_POWER_TRANSITION_FAILED = 13, - /**< Manifest of the library being loaded is invalid */ + /** Manifest of the library being loaded is invalid */ IPC4_INVALID_MANIFEST = 14, - /**< Requested service or data is unavailable on the target platform */ + /** Requested service or data is unavailable on the target platform */ IPC4_UNAVAILABLE = 15, /* Load/unload library specific codes */ - /**< Library target address is out of storage memory range */ + /** Library target address is out of storage memory range */ IPC4_LOAD_ADDRESS_OUT_OF_RANGE = 42, - /**< Image verification by CSE failed */ + /** Image verification by CSE failed */ IPC4_CSE_VALIDATION_FAILED = 44, - /**< General module management error */ + /** General module management error */ IPC4_MOD_MGMT_ERROR = 100, - /**< Module loading failed */ + /** Module loading failed */ IPC4_MOD_LOAD_CL_FAILED = 101, - /**< Integrity check of the loaded module content failed */ + /** Integrity check of the loaded module content failed */ IPC4_MOD_LOAD_INVALID_HASH = 102, - /**< Attempt to unload code of the module in use */ + /** Attempt to unload code of the module in use */ IPC4_MOD_INSTANCE_EXISTS = 103, - /**< Other failure of module instance initialization request */ + /** Other failure of module instance initialization request */ IPC4_MOD_NOT_INITIALIZED = 104, - /**< Invalid (out of range) module ID provided */ + /** Invalid (out of range) module ID provided */ IPC4_MOD_INVALID_ID = 110, - /**< Invalid module instance ID provided */ + /** Invalid module instance ID provided */ IPC4_MOD_INST_INVALID_ID = 111, - /**< Invalid queue (pin) ID provided */ + /** Invalid queue (pin) ID provided */ IPC4_QUEUE_INVALID_ID = 112, - /**< Invalid destination queue (pin) ID provided */ + /** Invalid destination queue (pin) ID provided */ IPC4_QUEUE_DST_INVALID_ID = 113, - /**< Invalid target code ID provided */ + /** Invalid target code ID provided */ IPC4_INVALID_CORE_ID = 116, - /**< Injection DMA buffer is too small for probing the input pin */ + /** Injection DMA buffer is too small for probing the input pin */ IPC4_PROBE_DMA_INJECTION_BUFFER_TOO_SMALL = 117, - /**< Extraction DMA buffer is too small for probing the output pin */ + /** Extraction DMA buffer is too small for probing the output pin */ IPC4_PROBE_DMA_EXTRACTION_BUFFER_TOO_SMALL = 118, - /**< Invalid ID of configuration item provided in TLV list */ + /** Invalid ID of configuration item provided in TLV list */ IPC4_INVALID_CONFIG_PARAM_ID = 120, - /**< Invalid length of configuration item provided in TLV list */ + /** Invalid length of configuration item provided in TLV list */ IPC4_INVALID_CONFIG_DATA_LEN = 121, - /**< Invalid structure of configuration item provided */ + /** Invalid structure of configuration item provided */ IPC4_INVALID_CONFIG_DATA_STRUCT = 122, - /**< Initialization of DMA Gateway failed */ + /** Initialization of DMA Gateway failed */ IPC4_GATEWAY_NOT_INITIALIZED = 140, - /**< Invalid ID of gateway provided */ + /** Invalid ID of gateway provided */ IPC4_GATEWAY_NOT_EXIST = 141, - /**< Setting state of DMA Gateway failed */ + /** Setting state of DMA Gateway failed */ IPC4_GATEWAY_STATE_NOT_SET = 142, - /**< DMA_CONTROL message targeting gateway not allocated yet */ + /** DMA_CONTROL message targeting gateway not allocated yet */ IPC4_GATEWAY_NOT_ALLOCATED = 143, - /**< Attempt to configure SCLK while I2S port is running */ + /** Attempt to configure SCLK while I2S port is running */ IPC4_SCLK_ALREADY_RUNNING = 150, - /**< Attempt to configure MCLK while I2S port is running */ + /** Attempt to configure MCLK while I2S port is running */ IPC4_MCLK_ALREADY_RUNNING = 151, - /**< Attempt to stop SCLK that is not running */ + /** Attempt to stop SCLK that is not running */ IPC4_NO_RUNNING_SCLK = 152, - /**< Attempt to stop MCLK that is not running */ + /** Attempt to stop MCLK that is not running */ IPC4_NO_RUNNING_MCLK = 153, - /**< Reverted for ULP purposes */ + /** Reverted for ULP purposes */ IPC4_PIPELINE_STATE_NOT_SET = 164, - /**< HDA chained gateways wrong state transition*/ + /** HDA chained gateways wrong state transition*/ IPC4_INVALID_CHAIN_STATE_TRANSITION = 3018, IPC4_MAX_STATUS = ((1 << IPC4_IXC_STATUS_BITS) - 1) diff --git a/src/include/ipc4/header.h b/src/include/ipc4/header.h index 23682f0d8e13..3f71a2e9cf4c 100644 --- a/src/include/ipc4/header.h +++ b/src/include/ipc4/header.h @@ -35,9 +35,9 @@ * \ingroup ipc4_envelope_api */ enum ipc4_message_target { - /**< Global firmware message (dispatched to Base FW or global handler). */ + /** Global firmware message (dispatched to Base FW or global handler). */ SOF_IPC4_MESSAGE_TARGET_FW_GEN_MSG = 0, - /**< Module-specific message (routed directly to module instance by module_id). */ + /** Module-specific message (routed directly to module instance by module_id). */ SOF_IPC4_MESSAGE_TARGET_MODULE_MSG = 1 }; @@ -46,9 +46,9 @@ enum ipc4_message_target { * \ingroup ipc4_envelope_api */ enum ipc4_message_direction { - /**< Host-to-DSP command request, or unsolicited DSP-to-host notification. */ + /** Host-to-DSP command request, or unsolicited DSP-to-host notification. */ SOF_IPC4_MESSAGE_DIR_MSG_REQUEST = 0, - /**< Command completion response / reply. */ + /** Command completion response / reply. */ SOF_IPC4_MESSAGE_DIR_MSG_REPLY = 1, }; @@ -57,50 +57,50 @@ enum ipc4_message_direction { * \ingroup ipc4_envelope_api */ enum ipc4_message_type { - /**< Boot configuration handshake. */ + /** Boot configuration handshake. */ SOF_IPC4_GLB_BOOT_CONFIG = 0, - /**< ROM control command (directed to ADSP ROM bootloader). */ + /** ROM control command (directed to ADSP ROM bootloader). */ SOF_IPC4_GLB_ROM_CONTROL = 1, - /**< Execute IPC gateway command. */ + /** Execute IPC gateway command. */ SOF_IPC4_GLB_IPCGATEWAY_CMD = 2, /* GAP HERE- DO NOT USE - size 10 (3 .. 12) */ - /**< Execute performance measurement command. */ + /** Execute performance measurement command. */ SOF_IPC4_GLB_PERF_MEASUREMENTS_CMD = 13, - /**< DMA chain setup and configuration command. */ + /** DMA chain setup and configuration command. */ SOF_IPC4_GLB_CHAIN_DMA = 14, - /**< Load multiple module binary images. */ + /** Load multiple module binary images. */ SOF_IPC4_GLB_LOAD_MULTIPLE_MODULES = 15, - /**< Unload multiple module binary images. */ + /** Unload multiple module binary images. */ SOF_IPC4_GLB_UNLOAD_MULTIPLE_MODULES = 16, - /**< Create pipeline with specified ID, priority, and memory attributes. */ + /** Create pipeline with specified ID, priority, and memory attributes. */ SOF_IPC4_GLB_CREATE_PIPELINE = 17, - /**< Delete pipeline and associated module graph. */ + /** Delete pipeline and associated module graph. */ SOF_IPC4_GLB_DELETE_PIPELINE = 18, - /**< Transition pipeline state (RESET, PAUSED, RUNNING, EOS). */ + /** Transition pipeline state (RESET, PAUSED, RUNNING, EOS). */ SOF_IPC4_GLB_SET_PIPELINE_STATE = 19, - /**< Retrieve current pipeline state. */ + /** Retrieve current pipeline state. */ SOF_IPC4_GLB_GET_PIPELINE_STATE = 20, - /**< Query pipeline context memory size. */ + /** Query pipeline context memory size. */ SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE = 21, - /**< Save pipeline context to host memory before power gating. */ + /** Save pipeline context to host memory before power gating. */ SOF_IPC4_GLB_SAVE_PIPELINE = 22, - /**< Restore pipeline context from host memory after wake. */ + /** Restore pipeline context from host memory after wake. */ SOF_IPC4_GLB_RESTORE_PIPELINE = 23, - /**< Load dynamic library via HD-Audio DMA. */ + /** Load dynamic library via HD-Audio DMA. */ SOF_IPC4_GLB_LOAD_LIBRARY = 24, - /**< Prepare for dynamic library loading. */ + /** Prepare for dynamic library loading. */ SOF_IPC4_GLB_LOAD_LIBRARY_PREPARE = 25, - /**< Internal firmware control message. */ + /** Internal firmware control message. */ SOF_IPC4_GLB_INTERNAL_MESSAGE = 26, - /**< Asynchronous notification event from DSP to host driver. */ + /** Asynchronous notification event from DSP to host driver. */ SOF_IPC4_GLB_NOTIFICATION = 27, /* GAP HERE- DO NOT USE - size 3 (28 .. 30) */ - /**< Enter GDB debugging stub to wait for host debugger in memory window. */ + /** Enter GDB debugging stub to wait for host debugger in memory window. */ SOF_IPC4_GLB_ENTER_GDB = 31, - /**< Maximum supported global message opcode count. */ + /** Maximum supported global message opcode count. */ SOF_IPC4_GLB_MAX_IXC_MESSAGE_TYPE = 32 }; @@ -129,28 +129,28 @@ struct ipc4_message_request { uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< Command-specific payload, pipeline ID, or module/instance identifier. */ + /** Command-specific payload, pipeline ID, or module/instance identifier. */ uint32_t rsvd0 : 24; - /**< 5-bit message opcode (enum ipc4_message_type or enum sof_ipc4_module_type). */ + /** 5-bit message opcode (enum ipc4_message_type or enum sof_ipc4_module_type). */ uint32_t type : 5; - /**< Direction: 0 for request/notification (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST). */ + /** Direction: 0 for request/notification (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST). */ uint32_t rsp : 1; - /**< Target selector: 0 for global firmware, 1 for module instance. */ + /** Target selector: 0 for global firmware, 1 for module instance. */ uint32_t msg_tgt : 1; - /**< Hardware reserved control bit. */ + /** Hardware reserved control bit. */ uint32_t _reserved_0 : 1; } r; } primary; union { uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< Command-specific extension payload, buffer offsets, or parameter flags. */ + /** Command-specific extension payload, buffer offsets, or parameter flags. */ uint32_t ext_data : 30; - /**< Hardware reserved control bits. */ + /** Hardware reserved control bits. */ uint32_t _reserved_0 : 2; } r; } extension; @@ -168,19 +168,19 @@ struct ipc4_message_reply { uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< Command processing status (one of enum ipc4_status). */ + /** Command processing status (one of enum ipc4_status). */ uint32_t status : 24; - /**< Message type, symmetric to the incoming request. */ + /** Message type, symmetric to the incoming request. */ uint32_t type : 5; - /**< Direction: 1 for reply (SOF_IPC4_MESSAGE_DIR_MSG_REPLY). */ + /** Direction: 1 for reply (SOF_IPC4_MESSAGE_DIR_MSG_REPLY). */ uint32_t rsp : 1; - /**< Target: symmetric to request (FW_GEN_MSG or MODULE_MSG). */ + /** Target: symmetric to request (FW_GEN_MSG or MODULE_MSG). */ uint32_t msg_tgt : 1; - /**< Hardware control reserved bit. */ + /** Hardware control reserved bit. */ uint32_t _reserved_0 : 1; } r; } primary; @@ -189,10 +189,10 @@ struct ipc4_message_reply { uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< Extension reply data, transfer length, or additional status information. */ + /** Extension reply data, transfer length, or additional status information. */ uint32_t rsvd1 : 30; - /**< Hardware control reserved bits. */ + /** Hardware control reserved bits. */ uint32_t _reserved_2 : 2; } r; } extension; diff --git a/src/include/ipc4/kpb.h b/src/include/ipc4/kpb.h index 2ee8cef3e865..18476604728b 100644 --- a/src/include/ipc4/kpb.h +++ b/src/include/ipc4/kpb.h @@ -30,9 +30,9 @@ struct ipc4_kpb_module_cfg { * \ingroup ipc4_telemetry_probe_api */ enum ipc4_kpb_module_config_params { - /**< Configure module IDs that execute within Fast Mode (FM) draining tasks. */ + /** Configure module IDs that execute within Fast Mode (FM) draining tasks. */ KP_BUF_CFG_FM_MODULE = 1, - /**< Real-time sink microphone channel selector ID. */ + /** Real-time sink microphone channel selector ID. */ KP_BUF_CLIENT_MIC_SELECT = 11, }; diff --git a/src/include/ipc4/module.h b/src/include/ipc4/module.h index 691e83112aa4..feb6ece147be 100644 --- a/src/include/ipc4/module.h +++ b/src/include/ipc4/module.h @@ -116,9 +116,9 @@ struct ipc4_module_init_ext_obj_dp_data { * \ingroup ipc4_module_api */ struct ipc4_module_init_ext_init { - /**< If set to 1, proc_domain is ignored and processing domain is RTOS scheduling. */ + /** If set to 1, proc_domain is ignored and processing domain is RTOS scheduling. */ uint32_t rtos_domain : 1; - /**< Indicates that GNA coprocessor is used by module and gna_config follows. */ + /** Indicates that GNA coprocessor is used by module and gna_config follows. */ uint32_t gna_used : 1; uint32_t data_obj_array : 1; /**< 1 if followed by struct ipc4_module_init_ext_object array. */ uint32_t rsvd_0 : 29; /**< Reserved bits. */ @@ -139,7 +139,7 @@ struct ipc4_module_init_ext_data { * \ingroup ipc4_module_api */ struct ipc4_module_init_gna_config { - /**< Number of GNA cycles required to process one input frame. */ + /** Number of GNA cycles required to process one input frame. */ uint32_t gna_cpc; uint32_t rsvd; /**< Reserved padding. */ } __attribute__((packed, aligned(4))); @@ -164,15 +164,15 @@ struct ipc4_module_init_instance { uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< Module class ID index from the FW manifest. */ + /** Module class ID index from the FW manifest. */ uint32_t module_id : 16; - /**< Module instance ID unique within the module class (0..max_instances-1). */ + /** Module instance ID unique within the module class (0..max_instances-1). */ uint32_t instance_id : 8; - /**< Opcode: SOF_IPC4_MOD_INIT_INSTANCE (0). */ + /** Opcode: SOF_IPC4_MOD_INIT_INSTANCE (0). */ uint32_t type : 5; - /**< Direction: 0 for request (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST). */ + /** Direction: 0 for request (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST). */ uint32_t rsp : 1; - /**< Target: 1 for module message (SOF_IPC4_MESSAGE_TARGET_MODULE_MSG). */ + /** Target: 1 for module message (SOF_IPC4_MESSAGE_TARGET_MODULE_MSG). */ uint32_t msg_tgt : 1; uint32_t _reserved_0 : 1; /**< Reserved hardware control bit. */ } r; @@ -182,15 +182,15 @@ struct ipc4_module_init_instance { uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< Size of initialization payload in 32-bit DWORDs. */ + /** Size of initialization payload in 32-bit DWORDs. */ uint32_t param_block_size : 16; - /**< ID of parent pipeline, or #IPC4_INVALID_PIPELINE_ID. */ + /** ID of parent pipeline, or #IPC4_INVALID_PIPELINE_ID. */ uint32_t ppl_instance_id : 8; - /**< Target DSP core ID on which this instance will execute (0..3). */ + /** Target DSP core ID on which this instance will execute (0..3). */ uint32_t core_id : 4; - /**< Processing domain (0 = Low-Latency LL, 1 = Data Processing DP). */ + /** Processing domain (0 = Low-Latency LL, 1 = Data Processing DP). */ uint32_t proc_domain : 1; - /**< 1 if extended initialization structures follow. */ + /** 1 if extended initialization structures follow. */ uint32_t extended_init : 1; uint32_t _hw_reserved_2 : 2; /**< Reserved hardware bits. */ } r; @@ -208,15 +208,15 @@ struct ipc4_module_bind_unbind { uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< Source module class identifier. */ + /** Source module class identifier. */ uint32_t module_id : 16; - /**< Source module instance identifier. */ + /** Source module instance identifier. */ uint32_t instance_id : 8; - /**< Opcode: SOF_IPC4_MOD_BIND (5) or SOF_IPC4_MOD_UNBIND (6). */ + /** Opcode: SOF_IPC4_MOD_BIND (5) or SOF_IPC4_MOD_UNBIND (6). */ uint32_t type : 5; - /**< Direction: 0 for request (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST). */ + /** Direction: 0 for request (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST). */ uint32_t rsp : 1; - /**< Target: 1 for module message (SOF_IPC4_MESSAGE_TARGET_MODULE_MSG). */ + /** Target: 1 for module message (SOF_IPC4_MESSAGE_TARGET_MODULE_MSG). */ uint32_t msg_tgt : 1; uint32_t _reserved_0 : 1; /**< Reserved hardware control bit. */ } r; @@ -226,13 +226,13 @@ struct ipc4_module_bind_unbind { uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< Destination module class identifier. */ + /** Destination module class identifier. */ uint32_t dst_module_id : 16; - /**< Destination module instance identifier. */ + /** Destination module instance identifier. */ uint32_t dst_instance_id : 8; - /**< Destination input queue/pin index (0..7). */ + /** Destination input queue/pin index (0..7). */ uint32_t dst_queue : SOF_IPC4_DST_QUEUE_ID_BITFIELD_SIZE; - /**< Source output queue/pin index (0..7). */ + /** Source output queue/pin index (0..7). */ uint32_t src_queue : SOF_IPC4_SRC_QUEUE_ID_BITFIELD_SIZE; uint32_t _reserved_2 : 2; /**< Reserved hardware control bits. */ } r; @@ -319,13 +319,13 @@ struct ipc4_module_large_config { uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< Chunk byte size (single block) or cumulative byte offset (multi-block). */ + /** Chunk byte size (single block) or cumulative byte offset (multi-block). */ uint32_t data_off_size : 20; - /**< Parameter type identifier (module-specific or #VENDOR_CONFIG_PARAM). */ + /** Parameter type identifier (module-specific or #VENDOR_CONFIG_PARAM). */ uint32_t large_param_id : 8; - /**< Set to 1 on the terminating chunk of a multi-block transfer. */ + /** Set to 1 on the terminating chunk of a multi-block transfer. */ uint32_t final_block : 1; - /**< Set to 1 on the initial chunk of a multi-block transfer. */ + /** Set to 1 on the initial chunk of a multi-block transfer. */ uint32_t init_block : 1; uint32_t _reserved_2 : 2; /**< Reserved bits. */ } r; @@ -428,7 +428,7 @@ struct ipc4_module_set_d0ix { */ struct ipc4_dx_state_info { uint32_t core_mask; /**< Bitmask indicating which DSP cores are subject to state change. */ - /**< Target state bitmask: bit[core_id] = 0 -> put to D3, bit[core_id] = 1 -> put to D0. */ + /** Target state bitmask: bit[core_id] = 0 -> put to D3, bit[core_id] = 1 -> put to D0. */ uint32_t dx_mask; } __attribute__((packed, aligned(4))); diff --git a/src/include/ipc4/notification.h b/src/include/ipc4/notification.h index 5ff63ab60758..e7b4b3174682 100644 --- a/src/include/ipc4/notification.h +++ b/src/include/ipc4/notification.h @@ -134,15 +134,10 @@ struct ipc4_voice_cmd_notification { uint32_t dat; struct { - /**< ID of detected keyword */ - uint32_t word_id : 16; - /**< Notification::PHRASE_DETECTED */ - uint32_t notif_type : 8; - /**< Global::NOTIFICATION */ - uint32_t type : 5; - /**< Msg::MSG_NOTIFICATION */ - uint32_t rsp : 1; - /**< Msg::FW_GEN_MSG */ + uint32_t word_id : 16; /**< ID of detected keyword. */ + uint32_t notif_type : 8; /**< Notification type (SOF_IPC4_NOTIFY_PHRASE_DETECTED). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_NOTIFICATION. */ + uint32_t rsp : 1; /**< Direction: 0 for unsolicited notification. */ uint32_t msg_tgt : 1; /**< Message target: 0 for global message. */ uint32_t _reserved_0 : 1; /**< Reserved bit. */ } r; /**< Primary bitfields. */ diff --git a/src/include/ipc4/pipeline.h b/src/include/ipc4/pipeline.h index c7452ffb03fe..7987c390b34f 100644 --- a/src/include/ipc4/pipeline.h +++ b/src/include/ipc4/pipeline.h @@ -212,15 +212,15 @@ struct ipc4_pipeline_set_state { uint32_t dat; /**< Raw 32-bit Primary register value. */ struct { - /**< Target pipeline state (enum ipc4_pipeline_state). */ + /** Target pipeline state (enum ipc4_pipeline_state). */ uint32_t ppl_state : 16; - /**< Target pipeline ID (ignored if multi_ppl == 1). */ + /** Target pipeline ID (ignored if multi_ppl == 1). */ uint32_t ppl_id : 8; - /**< Opcode: SOF_IPC4_GLB_SET_PIPELINE_STATE (19). */ + /** Opcode: SOF_IPC4_GLB_SET_PIPELINE_STATE (19). */ uint32_t type : 5; - /**< Direction: 0 for request. */ + /** Direction: 0 for request. */ uint32_t rsp : 1; - /**< Target: 0 for global firmware message. */ + /** Target: 0 for global firmware message. */ uint32_t msg_tgt : 1; uint32_t _reserved_0: 1; /**< Reserved bit. */ } r; @@ -230,9 +230,9 @@ struct ipc4_pipeline_set_state { uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< 1 if additional pipeline IDs are provided in s_data payload. */ + /** 1 if additional pipeline IDs are provided in s_data payload. */ uint32_t multi_ppl : 1; - /**< 1 if DSP should synchronize state transition across all pipelines. */ + /** 1 if DSP should synchronize state transition across all pipelines. */ uint32_t sync_stop_start : 1; uint32_t rsvd1 : 28; /**< Reserved padding. */ uint32_t _reserved_2: 2; /**< Reserved bits. */ @@ -263,7 +263,7 @@ struct ipc4_pipeline_set_state_reply { uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< ID of failed pipeline on error. */ + /** ID of failed pipeline on error. */ uint32_t ppl_id : 30; uint32_t _reserved_2: 2; /**< Reserved bits. */ } r; @@ -319,7 +319,7 @@ struct ipc4_pipeline_get_state_reply { uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< Current state (one of enum ipc4_pipeline_state). */ + /** Current state (one of enum ipc4_pipeline_state). */ uint32_t state : 5; uint32_t rsvd1 : 25; /**< Reserved padding. */ uint32_t _reserved_2: 2; /**< Reserved bits. */ @@ -376,7 +376,7 @@ struct ipc4_pipeline_get_context_size_reply { uint32_t dat; /**< Raw 32-bit Extension register value. */ struct { - /**< Size of pipeline serialization context in 4KB memory pages. */ + /** Size of pipeline serialization context in 4KB memory pages. */ uint32_t ctx_size : 16; uint32_t rsvd1 : 14; /**< Reserved padding. */ uint32_t _reserved_2: 2; /**< Reserved bits. */ diff --git a/src/include/module/ipc4/base-config.h b/src/include/module/ipc4/base-config.h index b006ff4dadb8..1bde90106523 100644 --- a/src/include/module/ipc4/base-config.h +++ b/src/include/module/ipc4/base-config.h @@ -190,12 +190,12 @@ struct ipc4_output_pin_format { * \ingroup ipc4_format_api */ struct ipc4_base_module_cfg_ext { - /**< Number of input pin format entries following in pin_formats[] (maximum 8). */ + /** Number of input pin format entries following in pin_formats[] (maximum 8). */ uint16_t nb_input_pins; - /**< Number of output pin format entries following in pin_formats[] (maximum 8). */ + /** Number of output pin format entries following in pin_formats[] (maximum 8). */ uint16_t nb_output_pins; uint8_t reserved[12]; /**< Reserved padding; must be set to 0. */ - /**< + /** * Variable-length array of input pin formats followed immediately by output pin formats. * Formats are matched by pin_index rather than array index. */ @@ -225,9 +225,9 @@ struct ipc4_base_module_extended_cfg { * \ingroup ipc4_format_api */ enum ipc4_base_module_params { - /**< Retrieve module instance runtime memory and queue properties via LargeConfigGet. */ + /** Retrieve module instance runtime memory and queue properties via LargeConfigGet. */ IPC4_MOD_INST_PROPS = 0xFE, - /**< Enable or disable module instance processing via ConfigSet (0 = disable, 1 = enable). */ + /** Enable or disable module instance processing via ConfigSet (0 = disable, 1 = enable). */ IPC4_MOD_INST_ENABLE = 0x3000 }; @@ -236,13 +236,13 @@ enum ipc4_base_module_params { * \ingroup ipc4_format_api */ struct ipc4_pin_props { - /**< Stream type (one of enum ipc4_stream_type). */ + /** Stream type (one of enum ipc4_stream_type). */ uint32_t stream_type; - /**< Active audio format of the stream (valid when stream_type == IPC4_STREAM_PCM). */ + /** Active audio format of the stream (valid when stream_type == IPC4_STREAM_PCM). */ struct ipc4_audio_format format; - /**< Physical DMA queue ID connected to this pin (-1 if unassigned). */ + /** Physical DMA queue ID connected to this pin (-1 if unassigned). */ uint32_t phys_queue_id; } __attribute__((packed, aligned(4))); From 5f6a4953d579294af0002cfea20252f4c32e28eb Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 13 Oct 2026 19:21:04 +0100 Subject: [PATCH 9/9] doc: ipc4: address review feedback on core range, opcodes, probe, and sample types Address Copilot review feedback on PR #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 --- src/include/ipc4/module.h | 2 +- src/include/ipc4/notification.h | 10 +++++----- src/include/ipc4/probe.h | 2 +- src/include/ipc4/ssp.h | 20 ++++++++++---------- src/include/module/ipc4/base-config.h | 4 ++-- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/src/include/ipc4/module.h b/src/include/ipc4/module.h index feb6ece147be..c1d0011b1623 100644 --- a/src/include/ipc4/module.h +++ b/src/include/ipc4/module.h @@ -186,7 +186,7 @@ struct ipc4_module_init_instance { uint32_t param_block_size : 16; /** ID of parent pipeline, or #IPC4_INVALID_PIPELINE_ID. */ uint32_t ppl_instance_id : 8; - /** Target DSP core ID on which this instance will execute (0..3). */ + /** Target DSP core ID on which this instance will execute (platform-dependent, 0..CONFIG_CORE_COUNT - 1). */ uint32_t core_id : 4; /** Processing domain (0 = Low-Latency LL, 1 = Data Processing DP). */ uint32_t proc_domain : 1; diff --git a/src/include/ipc4/notification.h b/src/include/ipc4/notification.h index e7b4b3174682..c2a55dd32284 100644 --- a/src/include/ipc4/notification.h +++ b/src/include/ipc4/notification.h @@ -119,7 +119,7 @@ union ipc4_notification_header { struct { uint32_t rsvd0 : 16; /**< Reserved bits. */ uint32_t notif_type : 8; /**< Notification type (enum sof_ipc4_notification_type). */ - uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_NOTIFICATION (23). */ + uint32_t type : 5; /**< Opcode: SOF_IPC4_GLB_NOTIFICATION (27). */ uint32_t rsp : 1; /**< Message direction: 0 for request/notification. */ uint32_t msg_tgt : 1; /**< Message target: 0 for global message. */ uint32_t _reserved_0 : 1; /**< Reserved bit. */ @@ -267,7 +267,7 @@ void send_process_data_error_notif_msg(uint32_t resource_id, uint32_t error_code * \ingroup ipc4_notification_api * \param pipeline_id Target pipeline identifier. * \param dir Stream direction (playback underrun or capture overrun). - * \return True if sent successfully, false otherwise. + * \return True if dispatched or suppressed by notification mask; false if notification pool was exhausted and caller should retry. */ bool send_copier_gateway_xrun_notif_msg(uint32_t pipeline_id, enum sof_ipc_stream_direction dir); @@ -276,7 +276,7 @@ bool send_copier_gateway_xrun_notif_msg(uint32_t pipeline_id, enum sof_ipc_strea * \ingroup ipc4_notification_api * \param resource_id Gateway connector node ID. * \param dir Stream direction. - * \return True if sent successfully, false otherwise. + * \return True if dispatched or suppressed by notification mask; false if notification pool was exhausted and caller should retry. */ bool send_gateway_xrun_notif_msg(uint32_t resource_id, enum sof_ipc_stream_direction dir); @@ -309,7 +309,7 @@ void ipc4_update_notification_mask(uint32_t ntfy_mask, uint32_t enabled_mask); * \param resource_type Resource category (enum sof_ipc4_resource_type). * \param data Pointer to event payload. * \param data_size Size of event payload in bytes. - * \return True on success, false on failure. + * \return True if dispatched or suppressed by notification mask; false if notification pool was exhausted and caller should retry. */ __syscall bool send_resource_notif(uint32_t resource_id, uint32_t event_type, uint32_t resource_type, void *data, uint32_t data_size); @@ -325,7 +325,7 @@ __syscall bool send_resource_notif(uint32_t resource_id, uint32_t event_type, * \param resource_type Resource category (enum sof_ipc4_resource_type). * \param data Pointer to event payload. * \param data_size Size of event payload in bytes. - * \return True on success, false on failure. + * \return True if dispatched or suppressed by notification mask; false if notification pool was exhausted and caller should retry. */ bool z_impl_send_resource_notif(uint32_t resource_id, uint32_t event_type, uint32_t resource_type, void *data, uint32_t data_size); diff --git a/src/include/ipc4/probe.h b/src/include/ipc4/probe.h index d2fc0a40cd97..2f20d10cd4bf 100644 --- a/src/include/ipc4/probe.h +++ b/src/include/ipc4/probe.h @@ -88,7 +88,7 @@ typedef union probe_point_id { struct probe_point { probe_point_id_t buffer_id; /**< ID of module buffer/pin to which probe is attached. */ uint32_t purpose; /**< Extraction or injection (PROBE_PURPOSE_xxx). */ - uint32_t stream_tag; /**< Stream tag of DMA providing data for injection or receiving extraction. */ + uint32_t stream_tag; /**< Stream tag of DMA providing injection data (for injection probes); ignored for extraction where firmware automatically binds the configured extraction DMA tag. */ } __attribute__((packed, aligned(4))); /** diff --git a/src/include/ipc4/ssp.h b/src/include/ipc4/ssp.h index a2133b04b01c..87a8c3397fbd 100644 --- a/src/include/ipc4/ssp.h +++ b/src/include/ipc4/ssp.h @@ -36,16 +36,16 @@ * \ingroup ipc4_gateway_api */ struct ipc4_ssp_config { - uint32_t ssc0; /**< Serial Serial Control register 0 (mode, data size). */ - uint32_t ssc1; /**< Serial Serial Control register 1 (clocks, phase, polarity). */ - uint32_t sscto; /**< Serial Serial Control Timeout register. */ - uint32_t sspsp; /**< Serial Serial Port Serial Protocol register (frame sync timing). */ - uint32_t sstsa; /**< Serial Serial Tx Time Slot Active register. */ - uint32_t ssrsa; /**< Serial Serial Rx Time Slot Active register. */ - uint32_t ssc2; /**< Serial Serial Control register 2 (extended FIFO control). */ - uint32_t sspsp2; /**< Serial Serial Port Serial Protocol register 2. */ - uint32_t ssc3; /**< Serial Serial Control register 3. */ - uint32_t ssioc; /**< Serial Serial I/O Control register (pin directions). */ + uint32_t ssc0; /**< Synchronous Serial Port Control register 0 (SSCR0: mode, data size). */ + uint32_t ssc1; /**< Synchronous Serial Port Control register 1 (SSCR1: clocks, phase, polarity). */ + uint32_t sscto; /**< Synchronous Serial Port Control Timeout register (SSCTO). */ + uint32_t sspsp; /**< Synchronous Serial Port Programmable Serial Protocol register (SSPSP: frame sync timing). */ + uint32_t sstsa; /**< Synchronous Serial Port Tx Time Slot Active register (SSTSA). */ + uint32_t ssrsa; /**< Synchronous Serial Port Rx Time Slot Active register (SSRSA). */ + uint32_t ssc2; /**< Synchronous Serial Port Control register 2 (SSCR2: extended FIFO control). */ + uint32_t sspsp2; /**< Synchronous Serial Port Programmable Serial Protocol register 2 (SSPSP2). */ + uint32_t ssc3; /**< Synchronous Serial Port Control register 3 (SSCR3). */ + uint32_t ssioc; /**< Synchronous Serial Port I/O Control register (SSIOC: pin directions). */ } __attribute__((packed, aligned(4))); /** diff --git a/src/include/module/ipc4/base-config.h b/src/include/module/ipc4/base-config.h index 1bde90106523..1769643a0c6b 100644 --- a/src/include/module/ipc4/base-config.h +++ b/src/include/module/ipc4/base-config.h @@ -116,8 +116,8 @@ enum ipc4_interleaved_style { * \ingroup ipc4_format_api */ enum ipc4_sample_type { - IPC4_TYPE_MSB_INTEGER = 0, /**< Integer with Most Significant Byte first. */ - IPC4_TYPE_LSB_INTEGER = 1, /**< Integer with Least Significant Byte first. */ + IPC4_TYPE_MSB_INTEGER = 0, /**< Integer with valid bits MSB-aligned in container (e.g. S24 in bits [31:8]). */ + IPC4_TYPE_LSB_INTEGER = 1, /**< Integer with valid bits LSB-aligned in container (e.g. S24 in bits [23:0]). */ IPC4_TYPE_SIGNED_INTEGER = 2, /**< Standard 2's complement signed integer (e.g. Q1.15, Q1.23, Q1.31). */ IPC4_TYPE_UNSIGNED_INTEGER = 3, /**< Unsigned integer PCM. */ IPC4_TYPE_FLOAT = 4, /**< 32-bit IEEE 754 floating point. */