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/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/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/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/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/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, diff --git a/src/include/ipc4/detect_test.h b/src/include/ipc4/detect_test.h index 603bf1741b2c..3745f0098388 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/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/error_status.h b/src/include/ipc4/error_status.h index 4d65b5596710..783cc19dc422 100644 --- a/src/include/ipc4/error_status.h +++ b/src/include/ipc4/error_status.h @@ -14,118 +14,127 @@ /** * \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 */ + /** 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/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/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/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..3f71a2e9cf4c 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 diff --git a/src/include/ipc4/kpb.h b/src/include/ipc4/kpb.h index 0c56942313c3..18476604728b 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/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/module.h b/src/include/ipc4/module.h index db1a074151a5..c1d0011b1623 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. - */ + /** Number of GNA cycles required to process one input frame. */ 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 (platform-dependent, 0..CONFIG_CORE_COUNT - 1). */ 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 diff --git a/src/include/ipc4/notification.h b/src/include/ipc4/notification.h index 870cef798407..c2a55dd32284 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 (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. */ + } r; /**< Bitfield layout. */ } __packed __aligned(4); /** @@ -154,67 +134,65 @@ 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 msg_tgt : 1; - uint32_t _reserved_0 : 1; - } r; - } primary; + 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. */ + } 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 +212,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 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); + +/** + * \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 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); +/** + * \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 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); #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 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); #define send_resource_notif z_impl_send_resource_notif diff --git a/src/include/ipc4/pipeline.h b/src/include/ipc4/pipeline.h index da756364dc6a..7987c390b34f 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))); diff --git a/src/include/ipc4/probe.h b/src/include/ipc4/probe.h index 96efc1bb7acd..2f20d10cd4bf 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 injection data (for injection probes); ignored for extraction where firmware automatically binds the configured extraction DMA tag. */ } __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__ */ diff --git a/src/include/ipc4/ssp.h b/src/include/ipc4/ssp.h index 752cb59193bf..87a8c3397fbd 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; /**< 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))); +/** + * \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 diff --git a/src/include/module/ipc4/base-config.h b/src/include/module/ipc4/base-config.h index 82a6d552306b..1769643a0c6b 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 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. */ + 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)));