IPC4 Host-DSP Protocol API#

The IPC4 protocol defines the structured binary communication interface between the host operating system driver and the Sound Open Firmware (SOF) DSP runtime. Used extensively across modern Intel platforms (Tiger Lake, Alder Lake, Raptor Lake, Meteor Lake, Arrow Lake, Lunar Lake, and Panther Lake), IPC4 governs audio pipeline construction, dynamic module lifecycle, inter-module pin binding, hardware peripheral gateway configuration, large parameter configuration handshakes, and real-time asynchronous telemetry.

Architecture & Protocol Overview#

The IPC4 protocol is built upon hardware doorbells, shared SRAM mailbox windows, and a uniform 64-bit message envelope.

1. Shared Memory Mailbox Windows#

Host and DSP exchange control messages and telemetry through memory-mapped SRAM windows:

Mailbox Window 0 (Control & Status):
- Offset 0x0000 - 0x0FFF (Firmware Status & Telemetry Registers): Exposes the 32-bit Firmware Status Register (fsr), Last Error Code (lec), Power Status (fps), ROM information, pipeline LPIB positions, real-time PeakVol meters, and Link Linear Position (LLP) wallclock readings (ipc4_fw_registers).
- Offset 0x1000 - 0x1FFF (Downlink Mailbox): Host writes request payloads (e.g. module initialization blobs, pipeline configs).
- Offset 0x2000 - 0x2FFF (Uplink Mailbox): DSP writes reply payloads and unsolicited asynchronous notification structures.
Mailbox Window 1 (Probes & Bulk Data): Dedicated memory window for audio extraction/injection probes, trace DMA streams, and bulk configuration buffers.

2. 64-bit Message Envelope#

Every IPC4 communication consists of two 32-bit hardware registers: the Primary Register and the Extension Register.

+-----------------------------------------------------------------------------------------------+
|                                  IPC4 Primary Header (DWORD 0)                                |
+---------------+---------+--------+--------------------+---------------------------------------+
| Bit 31 (RSVD) | 30 (TGT)| 29(RSP)| Bits 28:24 (TYPE)  | Bits 23:0 (Type-Specific Parameters)  |
+---------------+---------+--------+--------------------+---------------------------------------+
| Reserved (0)  | 0=GLB   | 0=REQ  | Opcode (0..31)     | Module Instance / Pipeline ID /       |
|               | 1=MOD   | 1=RSP  |                    | Status Code (in replies)              |
+---------------+---------+--------+--------------------+---------------------------------------+

+-----------------------------------------------------------------------------------------------+
|                                 IPC4 Extension Header (DWORD 1)                               |
+---------------------------------------+---------------+---------------------------------------+
| Bits 31:30 (Reserved)                 | Bit 29..24    | Bits 23:0 (Extension-Specific Data)   |
+---------------------------------------+---------------+---------------------------------------+
| Reserved bits                         | Large Config  | Param ID / Data Offset & Size /       |
|                                       | Flags (FB/LB) | Pipeline Context Pages                |
+---------------------------------------+---------------+---------------------------------------+

Target Bit (``msg_tgt``):
- 0 (Global Message): Targets firmware core services (pipelines, base firmware, gateway control).
- 1 (Module Message): Addressed to a specific module instance identified by its 16-bit Module ID and 8-bit Instance ID.
Response Bit (``rsp``):
- 0: Request from sender (or unsolicited DSP-to-host notification).
- 1: Reply to a previous request, returning status code in bits 23:0 of Primary.

3. Doorbell Handshake Flow#

Command exchange follows a strict, non-reentrant hardware doorbell handshake:

Host Driver                                                  DSP Firmware
    |                                                              |
    |  1. Write payload to Downlink Mailbox (Window 0)             |
    |  2. Write Primary & Extension registers                      |
    |  3. Set Host-to-DSP Doorbell (BUSY = 1)                      |
    |------------------------------------------------------------->|  (Interrupt)
    |                                                              |
    |                                                              |  4. Read Primary & Ext
    |                                                              |  5. Dispatch command
    |                                                              |  6. Write reply payload
    |                                                              |     to Uplink Mailbox
    |                                                              |  7. Write status to Primary
    |                                                              |  8. Clear DSP BUSY &
    |  (Interrupt)                                                 |     Set DSP-to-Host DONE
    |<-------------------------------------------------------------|
    |                                                              |
    |  9. Read reply status and Uplink payload                     |
    | 10. Clear DONE bit (handshake complete)                      |
    |                                                              |

4. Audio Pipeline Construction & State Machine#

Audio processing graphs are built and controlled dynamically by the host driver:

Host Driver                                                  DSP Firmware
    |                                                              |
    |  SOF_IPC4_GLB_CREATE_PIPELINE (ppl_id, priority, memory)     |
    |------------------------------------------------------------->|  Create pipeline container
    |<-------------------------------------------------------------|  Reply (STATUS_SUCCESS)
    |                                                              |
    |  SOF_IPC4_MOD_INIT_INSTANCE (mod_id, inst_id, base_cfg)      |
    |------------------------------------------------------------->|  Instantiate module in pipeline
    |<-------------------------------------------------------------|  Reply (STATUS_SUCCESS)
    |                                                              |
    |  SOF_IPC4_MOD_BIND (src_mod, src_pin -> dst_mod, dst_pin)    |
    |------------------------------------------------------------->|  Connect inter-module queue
    |<-------------------------------------------------------------|  Reply (STATUS_SUCCESS)
    |                                                              |
    |  SOF_IPC4_GLB_SET_PIPELINE_STATE (PAUSED)                    |
    |------------------------------------------------------------->|  Allocate buffers & gateways
    |<-------------------------------------------------------------|  Reply (STATUS_SUCCESS)
    |                                                              |
    |  SOF_IPC4_GLB_SET_PIPELINE_STATE (RUNNING)                   |
    |------------------------------------------------------------->|  Start processing tasks (LL/DP)
    |<-------------------------------------------------------------|  Reply (STATUS_SUCCESS)
    |                                                              |

State transitions adhere to strict ordering:

Forward Transitions (RESET -> PAUSED -> RUNNING): Processed from source modules to sink modules.
Reverse Transitions (RUNNING -> PAUSED -> RESET): Processed in strict reverse order (sink modules to source modules) to guarantee clean drain without FIFO underflow.

5. Large Configuration Multi-Chunk Protocol#

When parameter data exceeds the mailbox capacity (4KB), the IPC4 protocol utilizes fragmented multi-chunk transactions:

Host Driver                                                  DSP Firmware
    |                                                              |
    |  LARGE_CONFIG_SET (Chunk 0, first_block=1, last_block=0)     |
    |  [Payload: bytes 0 .. 4095]                                  |
    |------------------------------------------------------------->|  Accumulate into staging buffer
    |<-------------------------------------------------------------|  Reply (STATUS_SUCCESS)
    |                                                              |
    |  LARGE_CONFIG_SET (Chunk 1, first_block=0, last_block=0)     |
    |  [Payload: bytes 4096 .. 8191]                               |
    |------------------------------------------------------------->|  Accumulate
    |<-------------------------------------------------------------|  Reply (STATUS_SUCCESS)
    |                                                              |
    |  LARGE_CONFIG_SET (Chunk 2, first_block=0, last_block=1)     |
    |  [Payload: final bytes]                                      |
    |------------------------------------------------------------->|  Commit full parameter blob
    |<-------------------------------------------------------------|  Reply (STATUS_SUCCESS)
    |                                                              |

Protocol API Subsystems#

The IPC4 API reference is organized into eight specialized functional subsystems:

1. Message Envelope & Protocol Handlers#

Defines the fundamental 64-bit message envelope, primary and extension register formats, global opcodes, status codes, and host-DSP message routing bridges.

group IPC4 Message Envelope & Dispatch

64-bit mailbox message envelope formats, primary/extension registers, command target routing, reply status, and compound message barriers.

Enums

enum ipc4_status#

IPC4 host-DSP status and error codes.

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).

Values:

enumerator IPC4_SUCCESS#: The operation was successful.

enumerator IPC4_ERROR_INVALID_PARAM#: Invalid parameter specified.

enumerator IPC4_UNKNOWN_MESSAGE_TYPE#: Unknown message type specified.

enumerator IPC4_OUT_OF_MEMORY#: Not enough space in the IPC reply buffer to complete the request.

enumerator IPC4_BUSY#: The system or resource is busy.

enumerator IPC4_BAD_STATE#: Replaced ADSP IPC PENDING (unused) - according to cAVS v0.5.

enumerator IPC4_FAILURE#: Unknown error while processing the request.

enumerator IPC4_INVALID_REQUEST#: Unsupported operation requested.

enumerator IPC4_INVALID_RESOURCE_ID#: Specified resource not found.

enumerator IPC4_RESOURCE_ID_EXISTS#: A resource’s ID requested to be created is already assigned.

enumerator IPC4_INVALID_RESOURCE_STATE#: Required resource is in invalid state.

enumerator IPC4_POWER_TRANSITION_FAILED#: Requested power transition failed to complete.

enumerator IPC4_INVALID_MANIFEST#: Manifest of the library being loaded is invalid.

enumerator IPC4_UNAVAILABLE#: Requested service or data is unavailable on the target platform.

enumerator IPC4_LOAD_ADDRESS_OUT_OF_RANGE#: Library target address is out of storage memory range.

enumerator IPC4_CSE_VALIDATION_FAILED#: Image verification by CSE failed.

enumerator IPC4_MOD_MGMT_ERROR#: General module management error.

enumerator IPC4_MOD_LOAD_CL_FAILED#: Module loading failed.

enumerator IPC4_MOD_LOAD_INVALID_HASH#: Integrity check of the loaded module content failed.

enumerator IPC4_MOD_INSTANCE_EXISTS#: Attempt to unload code of the module in use.

enumerator IPC4_MOD_NOT_INITIALIZED#: Other failure of module instance initialization request.

enumerator IPC4_MOD_INVALID_ID#: Invalid (out of range) module ID provided.

enumerator IPC4_MOD_INST_INVALID_ID#: Invalid module instance ID provided.

enumerator IPC4_QUEUE_INVALID_ID#: Invalid queue (pin) ID provided.

enumerator IPC4_QUEUE_DST_INVALID_ID#: Invalid destination queue (pin) ID provided.

enumerator IPC4_INVALID_CORE_ID#: Invalid target code ID provided.

enumerator IPC4_PROBE_DMA_INJECTION_BUFFER_TOO_SMALL#: Injection DMA buffer is too small for probing the input pin.

enumerator IPC4_PROBE_DMA_EXTRACTION_BUFFER_TOO_SMALL#: Extraction DMA buffer is too small for probing the output pin.

enumerator IPC4_INVALID_CONFIG_PARAM_ID#: Invalid ID of configuration item provided in TLV list.

enumerator IPC4_INVALID_CONFIG_DATA_LEN#: Invalid length of configuration item provided in TLV list.

enumerator IPC4_INVALID_CONFIG_DATA_STRUCT#: Invalid structure of configuration item provided.

enumerator IPC4_GATEWAY_NOT_INITIALIZED#: Initialization of DMA Gateway failed.

enumerator IPC4_GATEWAY_NOT_EXIST#: Invalid ID of gateway provided.

enumerator IPC4_GATEWAY_STATE_NOT_SET#: Setting state of DMA Gateway failed.

enumerator IPC4_GATEWAY_NOT_ALLOCATED#: DMA_CONTROL message targeting gateway not allocated yet.

enumerator IPC4_SCLK_ALREADY_RUNNING#: Attempt to configure SCLK while I2S port is running.

enumerator IPC4_MCLK_ALREADY_RUNNING#: Attempt to configure MCLK while I2S port is running.

enumerator IPC4_NO_RUNNING_SCLK#: Attempt to stop SCLK that is not running.

enumerator IPC4_NO_RUNNING_MCLK#: Attempt to stop MCLK that is not running.

enumerator IPC4_PIPELINE_STATE_NOT_SET#: Reverted for ULP purposes.

enumerator IPC4_INVALID_CHAIN_STATE_TRANSITION#: HDA chained gateways wrong state transition.

enumerator IPC4_MAX_STATUS#

enum ipc4_message_target#

Message target routing selector (msg_tgt bitfield in Primary DWORD).

Values:

enumerator SOF_IPC4_MESSAGE_TARGET_FW_GEN_MSG#: Global firmware message (dispatched to Base FW or global handler).

enumerator SOF_IPC4_MESSAGE_TARGET_MODULE_MSG#: Module-specific message (routed directly to module instance by module_id).

enum ipc4_message_direction#

Message direction indicator (rsp bitfield in Primary DWORD).

Values:

enumerator SOF_IPC4_MESSAGE_DIR_MSG_REQUEST#: Host-to-DSP command request, or unsolicited DSP-to-host notification.

enumerator SOF_IPC4_MESSAGE_DIR_MSG_REPLY#: Command completion response / reply.

enum ipc4_message_type#

Global IPC4 message types (5-bit opcode in Primary DWORD when msg_tgt == FW_GEN_MSG).

Values:

enumerator SOF_IPC4_GLB_BOOT_CONFIG#: Boot configuration handshake.

enumerator SOF_IPC4_GLB_ROM_CONTROL#: ROM control command (directed to ADSP ROM bootloader).

enumerator SOF_IPC4_GLB_IPCGATEWAY_CMD#: Execute IPC gateway command.

enumerator SOF_IPC4_GLB_PERF_MEASUREMENTS_CMD#: Execute performance measurement command.

enumerator SOF_IPC4_GLB_CHAIN_DMA#: DMA chain setup and configuration command.

enumerator SOF_IPC4_GLB_LOAD_MULTIPLE_MODULES#: Load multiple module binary images.

enumerator SOF_IPC4_GLB_UNLOAD_MULTIPLE_MODULES#: Unload multiple module binary images.

enumerator SOF_IPC4_GLB_CREATE_PIPELINE#: Create pipeline with specified ID, priority, and memory attributes.

enumerator SOF_IPC4_GLB_DELETE_PIPELINE#: Delete pipeline and associated module graph.

enumerator SOF_IPC4_GLB_SET_PIPELINE_STATE#: Transition pipeline state (RESET, PAUSED, RUNNING, EOS).

enumerator SOF_IPC4_GLB_GET_PIPELINE_STATE#: Retrieve current pipeline state.

enumerator SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE#: Query pipeline context memory size.

enumerator SOF_IPC4_GLB_SAVE_PIPELINE#: Save pipeline context to host memory before power gating.

enumerator SOF_IPC4_GLB_RESTORE_PIPELINE#: Restore pipeline context from host memory after wake.

enumerator SOF_IPC4_GLB_LOAD_LIBRARY#: Load dynamic library via HD-Audio DMA.

enumerator SOF_IPC4_GLB_LOAD_LIBRARY_PREPARE#: Prepare for dynamic library loading.

enumerator SOF_IPC4_GLB_INTERNAL_MESSAGE#: Internal firmware control message.

enumerator SOF_IPC4_GLB_NOTIFICATION#: Asynchronous notification event from DSP to host driver.

enumerator SOF_IPC4_GLB_ENTER_GDB#: Enter GDB debugging stub to wait for host debugger in memory window.

enumerator SOF_IPC4_GLB_MAX_IXC_MESSAGE_TYPE#: Maximum supported global message opcode count.

Functions

int ipc4_user_process_module_message(struct ipc4_message_request *ipc4, struct ipc_msg *reply)#

Processes an IPC4 userspace module message.

Parameters:

ipc4 – [in] IPC4 message request structure.
reply – [inout] IPC message reply structure populated upon return.

Returns:

IPC4_SUCCESS (0) on success, or negative/IPC4 status code on failure.

int ipc4_user_module_load(const struct comp_driver *drv, const struct ipc4_module_init_instance *mi)#

Load a dynamically loadable module instance into userspace memory.

Parameters:

drv – [in] Component driver operations structure.
mi – [in] IPC4 module initialization parameters (SOF_IPC4_MOD_INIT_INSTANCE).

Returns:

0 on success, or negative error code on allocation/loading failure.

int ipc4_process_module_config(struct ipc4_message_request *ipc4, bool set, uint32_t *reply_ext)#

Process MOD_CONFIG_GET or MOD_CONFIG_SET in any execution context.

Parameters:

ipc4 – [in] IPC4 message request structure.
set – [in] True for MOD_CONFIG_SET, false for MOD_CONFIG_GET.
reply_ext – [out] Receives extension DWORD value for CONFIG_GET (may be NULL).

Returns:

IPC4 status code (IPC4_SUCCESS on success).

int ipc4_process_large_config_set(struct ipc4_message_request *ipc4)#

Process MOD_LARGE_CONFIG_SET in any execution context.

Parameters:

ipc4 – [in] IPC4 message request structure containing block parameters and offset.

Returns:

IPC4 status code (IPC4_SUCCESS on success).

int ipc4_user_process_glb_message(struct ipc4_message_request *ipc4, struct ipc_msg *reply)#

Processes an IPC4 userspace global firmware message.

Parameters:

ipc4 – [in] IPC4 message request structure.
reply – [inout] IPC message reply structure.

Returns:

IPC4_SUCCESS on success, error code otherwise.

int ipc4_set_pipeline_state(struct ipc4_message_request *ipc4)#

Process SET_PIPELINE_STATE IPC4 message (prepare + trigger phases).

Parameters:

ipc4 – [in] IPC4 message request structure containing target state and pipeline ID.

Returns:

0 on success, or IPC4 error code on failure.

void ipc_compound_msg_done(uint32_t msg_id, int error)#

Complete an IPC compound message transaction and signal waiting threads.

Parameters:

msg_id – [in] Compound IPC message transaction identifier.
error – [in] Overall error code of the compound transaction.

int ipc4_comp_connect(struct ipc *ipc, const struct ipc4_module_bind_unbind *bu)#

Connect components together on a pipeline graph.

Parameters:

ipc – [in] The global IPC context pointer.
bu – [in] IPC4 bind-unbind configuration data.

Returns:

IPC4_SUCCESS on success, or IPC4 error code otherwise.

int ipc4_comp_disconnect(struct ipc *ipc, const struct ipc4_module_bind_unbind *bu)#

Disconnect components in a pipeline graph.

Parameters:

ipc – [in] The global IPC context pointer.
bu – [in] IPC4 bind-unbind configuration data.

Returns:

IPC4_SUCCESS on success, or IPC4 error code otherwise.

void ipc_compound_pre_start(int msg_id)#

Increment the IPC compound message pre-start barrier counter.

Parameters:

msg_id – [in] IPC message ID.

void ipc_compound_post_start(uint32_t msg_id, int ret, bool delayed)#

Decrement the IPC compound message pre-start barrier counter on return.

Parameters:

msg_id – [in] IPC message ID.
ret – [in] Return value of the IPC command.
delayed – [in] True if the reply is deferred/asynchronous.

int ipc_wait_for_compound_msg(void)#

Wait for active IPC compound message operations to complete.

Returns:: 0 on success, or negative error code on timeout.

struct ipc4_message_reply __attribute ((packed, aligned(4)))

struct ipc_cmd_hdr#

#include <src/include/ipc3/header.h>

Generic message header.

Generic raw 64-bit IPC4 message header registers.

IPC MAJOR 3 version. All IPC3 messages use this header as abstraction to platform specific calls.

All IPC4 messages are passed across the mailbox as a pair of 32-bit registers (Primary DWORD + Extension DWORD).

Public Members

uint32_t dat[2]#

uint32_t pri#: Primary 32-bit register value.

uint32_t ext#: Extension 32-bit register value.

struct ipc4_message_request#

#include <src/include/ipc4/header.h>

Standard 64-bit IPC4 message request envelope.

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.

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t rsvd0#: Command-specific payload, pipeline ID, or module/instance identifier.

uint32_t type#: 5-bit message opcode (enum ipc4_message_type or enum sof_ipc4_module_type).

uint32_t rsp#: Direction: 0 for request/notification (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST).

uint32_t msg_tgt#: Target selector: 0 for global firmware, 1 for module instance.

uint32_t _reserved_0#

Hardware reserved control bit.

Hardware reserved control bits.

struct ipc4_message_request r#

union ipc4_message_request primary#

uint32_t ext_data#: Command-specific extension payload, buffer offsets, or parameter flags.

struct ipc4_message_request r

union ipc4_message_request extension#

struct ipc4_message_reply#

#include <src/include/ipc4/header.h>

Standard 64-bit IPC4 message reply envelope.

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.

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t status#: Command processing status (one of enum ipc4_status).

uint32_t type#: Message type, symmetric to the incoming request.

uint32_t rsp#: Direction: 1 for reply (SOF_IPC4_MESSAGE_DIR_MSG_REPLY).

uint32_t msg_tgt#: Target: symmetric to request (FW_GEN_MSG or MODULE_MSG).

uint32_t _reserved_0#: Hardware control reserved bit.

struct ipc4_message_reply r#

union ipc4_message_reply primary#

uint32_t rsvd1#: Extension reply data, transfer length, or additional status information.

uint32_t _reserved_2#: Hardware control reserved bits.

struct ipc4_message_reply r

union ipc4_message_reply extension#

struct sof_ipc4_ctrl_value_chan#

#include <src/include/ipc4/header.h>

Generic per-channel control value mapping.

Public Members

uint32_t channel#: Logical audio channel ID (0 = Left, 1 = Right, etc.).

uint32_t value#: Control integer value (gain level, mute toggle, enum index).

struct sof_ipc4_control_msg_payload#

#include <src/include/ipc4/header.h>

IPC4 payload structure for ALSA kcontrol parameters.

Public Members

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.

struct sof_ipc4_ctrl_value_chan chanv[0]#: Channel ID and value array.

uint8_t data[0]#: Binary byte payload for raw controls.

union sof_ipc4_control_msg_payload

struct sof_ipc4_notify_module_data#

#include <src/include/ipc4/header.h>

Asynchronous notification payload originating from a module instance.

Public Members

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.

2. Audio Formats, Pins & Stream Descriptors#

Defines the binary serialization format for multi-channel audio streams, PCM sample representations, container bit depths, channel maps, and dynamic input/output pin formats.

Note

Sample type enumeration entries (such as IPC4_TYPE_MSB_INTEGER vs IPC4_TYPE_LSB_INTEGER) describe valid audio bit alignment within the sample container memory word (e.g. S24 valid bits aligned at bits [31:8] vs [23:0]) rather than byte endianness, remaining little-endian.

group IPC4 Audio Formats & Pin Contracts

Audio format specification bitfields, sampling rates, bit depths, channel configurations, and pin format descriptors.

Defines

ipc4_calc_base_module_cfg_ext_size(in_pins, out_pins)#: Helper macro to calculate serialized byte size of struct ipc4_base_module_cfg_ext.

Enums

enum ipc4_sampling_frequency#

Standard PCM and encoded audio sampling frequencies supported by IPC4.

Values:

enumerator IPC4_FS_8000HZ#: 8.0 kHz sampling rate.

enumerator IPC4_FS_11025HZ#: 11.025 kHz sampling rate.

enumerator IPC4_FS_12000HZ#: 12.0 kHz (MP3, AAC, SRC only).

enumerator IPC4_FS_16000HZ#: 16.0 kHz sampling rate (standard voice/telephony).

enumerator IPC4_FS_18900HZ#: 18.9 kHz (SRC only for 44.1 kHz fractional rates).

enumerator IPC4_FS_22050HZ#: 22.05 kHz sampling rate.

enumerator IPC4_FS_24000HZ#: 24.0 kHz (MP3, AAC, SRC only).

enumerator IPC4_FS_32000HZ#: 32.0 kHz sampling rate.

enumerator IPC4_FS_37800HZ#: 37.8 kHz (SRC only for 44.1 kHz fractional rates).

enumerator IPC4_FS_44100HZ#: 44.1 kHz CD audio sampling rate.

enumerator IPC4_FS_48000HZ#: 48.0 kHz standard DSP audio rate (Default).

enumerator IPC4_FS_64000HZ#: 64.0 kHz (AAC, SRC only).

enumerator IPC4_FS_88200HZ#: 88.2 kHz high-resolution audio.

enumerator IPC4_FS_96000HZ#: 96.0 kHz high-resolution audio.

enumerator IPC4_FS_176400HZ#: 176.4 kHz studio master rate.

enumerator IPC4_FS_192000HZ#: 192.0 kHz studio master rate.

enumerator IPC4_FS_INVALID#: Sentinel for invalid or uninitialized sampling rate.

enum ipc4_bit_depth#

Container bit depth for sample storage in memory.

Values:

enumerator IPC4_DEPTH_8BIT#: 8-bit sample container depth.

enumerator IPC4_DEPTH_16BIT#: 16-bit sample container depth.

enumerator IPC4_DEPTH_24BIT#: 24-bit sample container depth (Default).

enumerator IPC4_DEPTH_32BIT#: 32-bit sample container depth.

enumerator IPC4_DEPTH_64BIT#: 64-bit sample container depth.

enumerator IPC4_DEPTH_INVALID#: Sentinel for invalid bit depth.

enum ipc4_channel_config#

Audio channel configurations and speaker mappings.

Values:

enumerator IPC4_CHANNEL_CONFIG_MONO#: Single mono channel.

enumerator IPC4_CHANNEL_CONFIG_STEREO#: Standard stereo (Left & Right).

enumerator IPC4_CHANNEL_CONFIG_2_POINT_1#: 2.1 Audio: Left, Right & LFE (PCM only).

enumerator IPC4_CHANNEL_CONFIG_3_POINT_0#: 3.0 Audio: Left, Center & Right (MP3 & AAC only).

enumerator IPC4_CHANNEL_CONFIG_3_POINT_1#: 3.1 Audio: Left, Center, Right & LFE (PCM only).

enumerator IPC4_CHANNEL_CONFIG_QUATRO#: 4.0 Surround: Left, Right, Left Surround & Right Surround.

enumerator IPC4_CHANNEL_CONFIG_4_POINT_0#: 4.0 Cinema: Left, Center, Right & Center Surround.

enumerator IPC4_CHANNEL_CONFIG_5_POINT_0#: 5.0 Surround: Left, Center, Right, Left Surround & Right Surround.

enumerator IPC4_CHANNEL_CONFIG_5_POINT_1#: 5.1 Surround: Left, Center, Right, Left Surround, Right Surround & LFE.

enumerator IPC4_CHANNEL_CONFIG_DUAL_MONO#: Dual mono: single logical channel duplicated into two slots.

enumerator IPC4_CHANNEL_CONFIG_I2S_DUAL_STEREO_0#: Stereo (L,R) in 4 slots, 1st stream: [ L, R, -, - ].

enumerator IPC4_CHANNEL_CONFIG_I2S_DUAL_STEREO_1#: Stereo (L,R) in 4 slots, 2nd stream: [ -, -, L, R ].

enumerator IPC4_CHANNEL_CONFIG_7_POINT_1#: 7.1 Surround: L, C, R, Ls, Rs, LFE, Left Side & Right Side.

enumerator IPC4_CHANNEL_CONFIG_INVALID#: Sentinel for unsupported channel configuration.

enum ipc4_channel_index#

Logical channel position indices used in channel maps.

Values:

enumerator CHANNEL_LEFT#: Front Left channel.

enumerator CHANNEL_CENTER#: Front Center channel.

enumerator CHANNEL_RIGHT#: Front Right channel.

enumerator CHANNEL_LEFT_SURROUND#: Left Surround channel.

enumerator CHANNEL_CENTER_SURROUND#: Center Surround channel.

enumerator CHANNEL_RIGHT_SURROUND#: Right Surround channel.

enumerator CHANNEL_LEFT_SIDE#: Left Side Surround channel.

enumerator CHANNEL_RIGHT_SIDE#: Right Side Surround channel.

enumerator CHANNEL_LFE#: Low Frequency Effects (subwoofer) channel.

enumerator CHANNEL_INVALID#: Unmapped or inactive channel slot.

enum ipc4_interleaved_style#

Sample interleaving styles.

Values:

enumerator IPC4_CHANNELS_INTERLEAVED#: Channels interleaved sample-by-sample (L0, R0, L1, R1…).

enumerator IPC4_CHANNELS_NONINTERLEAVED#: Planar non-interleaved channels (all Left samples, then all Right).

enum ipc4_sample_type#

Audio sample representation and arithmetic type.

Values:

enumerator IPC4_TYPE_MSB_INTEGER#

Integer with valid bits MSB-aligned in container (e.g.

S24 in bits [31:8]).

enumerator IPC4_TYPE_LSB_INTEGER#

Integer with valid bits LSB-aligned in container (e.g.

S24 in bits [23:0]).

enumerator IPC4_TYPE_SIGNED_INTEGER#

Standard 2’s complement signed integer (e.g.

Q1.15, Q1.23, Q1.31).

enumerator IPC4_TYPE_UNSIGNED_INTEGER#: Unsigned integer PCM.

enumerator IPC4_TYPE_FLOAT#: 32-bit IEEE 754 floating point.

enumerator IPC4_TYPE_A_LAW#: ITU-T G.711 A-law companded audio.

enumerator IPC4_TYPE_MU_LAW#: ITU-T G.711 mu-law companded audio.

enum ipc4_stream_type#

Stream container encoding type.

Values:

enumerator IPC4_STREAM_PCM#: Linear Pulse Code Modulated (PCM) uncompressed audio.

enumerator IPC4_STREAM_MP3#: MPEG-1 Audio Layer III encoded bitstream.

enumerator IPC4_STREAM_AAC#: Advanced Audio Coding encoded bitstream.

enumerator IPC4_STREAM_COUNT#: Total count of defined stream types.

enumerator IPC4_STREAM_INVALID#: Sentinel for invalid stream type.

enum ipc4_base_module_params#

Common 16-bit parameter IDs supported across all IPC4 module instances.

Values:

enumerator IPC4_MOD_INST_PROPS#: Retrieve module instance runtime memory and queue properties via LargeConfigGet.

enumerator IPC4_MOD_INST_ENABLE#: Enable or disable module instance processing via ConfigSet (0 = disable, 1 = enable).

Functions

void ipc4_base_module_cfg_to_stream_params(const struct ipc4_base_module_cfg *base_cfg, struct sof_ipc_stream_params *params)#

Convert an IPC4 base module configuration structure to internal SOF stream parameters.

Parameters:

base_cfg – [in] Pointer to the IPC4 base module configuration.
params – [out] 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)#

Convert an IPC4 audio format descriptor to internal SOF stream parameters.

Parameters:

audio_fmt – [in] Pointer to the IPC4 audio format structure.
params – [out] Destination SOF stream parameters structure to populate.

void ipc4_update_buffer_format(struct comp_buffer *buf_c, const struct ipc4_audio_format *fmt)#

Apply an IPC4 audio format configuration to an intermediate component buffer.

Parameters:

buf_c – [inout] Component buffer whose stream format will be updated.
fmt – [in] IPC4 audio format specification to apply.

void ipc4_update_source_format(struct sof_source *source, const struct ipc4_audio_format *fmt)#

Apply an IPC4 audio format configuration to an audio streaming source endpoint.

Parameters:

source – [inout] Audio source interface to configure.
fmt – [in] IPC4 audio format specification to apply.

void ipc4_update_sink_format(struct sof_sink *sink, const struct ipc4_audio_format *fmt)#

Apply an IPC4 audio format configuration to an audio streaming sink endpoint.

Parameters:

sink – [inout] Audio sink interface to configure.
fmt – [in] IPC4 audio format specification to apply.

struct ipc4_audio_format#

#include <src/include/module/ipc4/base-config.h>

Standard audio format descriptor across all IPC4 modules and gateways.

Public Members

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#: Active channel count (1 to 8).

uint32_t valid_bit_depth#

Number of significant valid bits within container (e.g.

24).

uint32_t s_type#: Sample representation type (one of enum ipc4_sample_type).

uint32_t reserved#: Reserved padding bits; must be set to 0.

struct ipc4_base_module_cfg#

#include <src/include/module/ipc4/base-config.h>

Base module configuration parameters provided upon module instantiation.

Public Members

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.

struct ipc4_input_pin_format#

#include <src/include/module/ipc4/base-config.h>

Input pin format specification for multi-pin modules.

Public Members

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.

struct ipc4_output_pin_format#

#include <src/include/module/ipc4/base-config.h>

Output pin format specification for multi-pin modules.

Public Members

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.

struct ipc4_base_module_cfg_ext#

#include <src/include/module/ipc4/base-config.h>

Extended module configuration header describing dynamic input and output pins.

Public Members

uint16_t nb_input_pins#: Number of input pin format entries following in pin_formats[] (maximum 8).

uint16_t nb_output_pins#: Number of output pin format entries following in pin_formats[] (maximum 8).

uint8_t reserved[12]#: Reserved padding; must be set to 0.

uint8_t pin_formats[]#

Variable-length array of input pin formats followed immediately by output pin formats.

Formats are matched by pin_index rather than array index.

struct ipc4_base_module_extended_cfg#

#include <src/include/module/ipc4/base-config.h>

Combined base and extended module configuration payload for easy parsing.

Public Members

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.

struct ipc4_pin_props#

#include <src/include/module/ipc4/base-config.h>

Runtime properties of a module pin connection.

Public Members

uint32_t stream_type#: Stream type (one of enum ipc4_stream_type).

struct ipc4_audio_format format#: Active audio format of the stream (valid when stream_type == IPC4_STREAM_PCM).

uint32_t phys_queue_id#: Physical DMA queue ID connected to this pin (-1 if unassigned).

struct ipc4_pin_list_info#

#include <src/include/module/ipc4/base-config.h>

List of active pin properties for a module instance.

Public Members

uint32_t pin_count#: Number of active pin property descriptors.

struct ipc4_pin_props pin_info[1]#: Array of pin properties.

struct ipc4_module_instance_props#

#include <src/include/module/ipc4/base-config.h>

Detailed module instance runtime state, memory consumption, and queue alignment.

Returned in response to LargeConfigGet with parameter ID IPC4_MOD_INST_PROPS.

Public Members

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.

struct ipc4_in_out_gateway#

#include <src/include/module/ipc4/base-config.h>

Direct gateway attachment identifiers for a module instance.

Public Members

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).

union ipc4_cfg_param_id_data#

#include <src/include/module/ipc4/base-config.h>

16-bit small parameter register encoding for MOD_CONFIG_SET/GET.

Public Members

uint32_t dw#: Raw 32-bit register value.

uint32_t data16#: 16-bit parameter data payload.

uint32_t id#: 14-bit parameter identifier.

uint32_t _rsvd#: Reserved bits.

struct ipc4_cfg_param_id_data f#

3. Dynamic Modules & Configuration Handshake#

Governs audio module instantiation, deletion, dynamic binding/unbinding of module pins, D0ix power state switching, and small/large parameter configuration transactions. Target DSP core affinity (core_id) is platform-dependent, ranging from 0 up to CONFIG_CORE_COUNT - 1.

group IPC4 Module Architecture & Dynamic Binding

Module instantiation, dynamic queue/pin binding, small/large parameter configuration handshake, and module power transitions.

Enums

enum sof_ipc4_module_type#

Module message command opcodes (5-bit opcode in Primary DWORD when msg_tgt == MODULE_MSG).

Values:

enumerator SOF_IPC4_MOD_INIT_INSTANCE#: Instantiate a new module object and attach to a pipeline.

enumerator SOF_IPC4_MOD_CONFIG_GET#: Retrieve a short 16-bit module parameter packed in header.

enumerator SOF_IPC4_MOD_CONFIG_SET#: Set a short 16-bit module parameter packed in header.

enumerator SOF_IPC4_MOD_LARGE_CONFIG_GET#: Retrieve multi-block configuration or state data from module.

enumerator SOF_IPC4_MOD_LARGE_CONFIG_SET#: Send multi-block configuration or filter coefficients to module.

enumerator SOF_IPC4_MOD_BIND#: Connect a source pin of this module to a destination pin.

enumerator SOF_IPC4_MOD_UNBIND#: Disconnect a runtime binding between two module instances.

enumerator SOF_IPC4_MOD_SET_DX#: Request core power state transition (D0/D3).

enumerator SOF_IPC4_MOD_SET_D0IX#: Request Base FW or module to enter low-power D0ix state.

enumerator SOF_IPC4_MOD_ENTER_MODULE_RESTORE#: Notify module to prepare for context restoration after wake.

enumerator SOF_IPC4_MOD_EXIT_MODULE_RESTORE#: Signal completion of module state restoration.

enumerator SOF_IPC4_MOD_DELETE_INSTANCE#: Destroy module instance and release allocated memory.

enum ipc4_mod_init_data_glb_id#

Global object type identifiers for extended initialization payloads.

Values:

enumerator IPC4_MOD_INIT_DATA_ID_INVALID#: Invalid initialization object identifier.

enumerator IPC4_MOD_INIT_DATA_ID_DP_DATA#: Data Processing (DP) thread stack and heap requirements.

enumerator IPC4_MOD_INIT_DATA_ID_MODULE_DATA#: Module-specific bespoke initialization data.

enumerator IPC4_MOD_INIT_DATA_ID_MAX#: Maximum supported object identifier.

union ipc4_extended_param_id#

#include <src/include/ipc4/module.h>

Compound parameter identifier encoding type and instance index.

Public Members

uint32_t full#: Full 32-bit parameter identifier.

uint32_t parameter_type#: Parameter type identifier.

uint32_t parameter_instance#: Parameter instance index.

struct ipc4_extended_param_id part#

struct ipc4_vendor_error#

#include <src/include/ipc4/module.h>

Vendor error reporting payload structure.

Public Members

uint32_t param_idx#: Index of the failed parameter in vendor configuration list.

uint32_t err_code#: Vendor-specific or hardware error code.

struct ipc4_module_init_ext_object#

#include <src/include/ipc4/module.h>

Header for extended initialization data objects.

Public Members

uint32_t last_object#: Set to 1 if this is the terminating object in the array.

uint32_t object_id#: Unique object identifier (one of enum ipc4_mod_init_data_glb_id).

uint32_t object_words#: Payload size in 32-bit DWORDs following this header.

struct ipc4_module_init_ext_obj_dp_data#

#include <src/include/ipc4/module.h>

Memory requirements for Data Processing (DP) module threads.

Public Members

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.

struct ipc4_module_init_ext_init#

#include <src/include/ipc4/module.h>

Extended initialization flags and coprocessor requirements.

Public Members

uint32_t rtos_domain#: If set to 1, proc_domain is ignored and processing domain is RTOS scheduling.

uint32_t gna_used#: Indicates that GNA coprocessor is used by module and gna_config follows.

uint32_t data_obj_array#: 1 if followed by struct ipc4_module_init_ext_object array.

uint32_t rsvd_0#: Reserved bits.

uint32_t rsvd_1[2]#: Reserved padding words.

struct ipc4_module_init_ext_data#

#include <src/include/ipc4/module.h>

Extended module initialization container.

Public Members

struct ipc4_module_init_ext_init extended_init#: Extended flags.

uint32_t param_data[]#: Module configuration payload words.

struct ipc4_module_init_gna_config#

#include <src/include/ipc4/module.h>

Neural network accelerator (GNA) compute cycle configuration.

Public Members

uint32_t gna_cpc#: Number of GNA cycles required to process one input frame.

uint32_t rsvd#: Reserved padding.

struct ipc4_module_init_data#

#include <src/include/ipc4/module.h>

Module initialization payload buffer.

Public Members

uint32_t param_data[0]#: Configuration payload words (sized by param_block_size).

struct ipc4_module_init_instance#

#include <src/include/ipc4/module.h>

Module instance creation command structure (SOF_IPC4_MOD_INIT_INSTANCE).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t module_id#: Module class ID index from the FW manifest.

uint32_t instance_id#: Module instance ID unique within the module class (0..max_instances-1).

uint32_t type#: Opcode: SOF_IPC4_MOD_INIT_INSTANCE (0).

uint32_t rsp#: Direction: 0 for request (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST).

uint32_t msg_tgt#: Target: 1 for module message (SOF_IPC4_MESSAGE_TARGET_MODULE_MSG).

uint32_t _reserved_0#: Reserved hardware control bit.

struct ipc4_module_init_instance r#

union ipc4_module_init_instance primary#

uint32_t param_block_size#: Size of initialization payload in 32-bit DWORDs.

uint32_t ppl_instance_id#: ID of parent pipeline, or IPC4_INVALID_PIPELINE_ID.

uint32_t core_id#: Target DSP core ID on which this instance will execute (platform-dependent, 0..CONFIG_CORE_COUNT - 1).

uint32_t proc_domain#: Processing domain (0 = Low-Latency LL, 1 = Data Processing DP).

uint32_t extended_init#: 1 if extended initialization structures follow.

uint32_t _hw_reserved_2#: Reserved hardware bits.

struct ipc4_module_init_instance r

union ipc4_module_init_instance extension#

struct ipc4_module_bind_unbind#

#include <src/include/ipc4/module.h>

Module pin binding and unbinding command structure (SOF_IPC4_MOD_BIND / UNBIND).

Sent by host to connect two module instances across pins (queues), or sever an existing link.

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t module_id#: Source module class identifier.

uint32_t instance_id#: Source module instance identifier.

uint32_t type#: Opcode: SOF_IPC4_MOD_BIND (5) or SOF_IPC4_MOD_UNBIND (6).

uint32_t rsp#: Direction: 0 for request (SOF_IPC4_MESSAGE_DIR_MSG_REQUEST).

uint32_t msg_tgt#: Target: 1 for module message (SOF_IPC4_MESSAGE_TARGET_MODULE_MSG).

uint32_t _reserved_0#: Reserved hardware control bit.

struct ipc4_module_bind_unbind r#

union ipc4_module_bind_unbind primary#

uint32_t dst_module_id#: Destination module class identifier.

uint32_t dst_instance_id#: Destination module instance identifier.

uint32_t dst_queue#: Destination input queue/pin index (0..7).

uint32_t src_queue#: Source output queue/pin index (0..7).

uint32_t _reserved_2#: Reserved hardware control bits.

struct ipc4_module_bind_unbind r

union ipc4_module_bind_unbind extension#

struct ipc4_module_config#

#include <src/include/ipc4/module.h>

Small parameter configuration command structure (SOF_IPC4_MOD_CONFIG_GET / SET).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t module_id#: Target module class ID.

uint32_t instance_id#: Target module instance ID.

uint32_t type#: Opcode: SOF_IPC4_MOD_CONFIG_GET or SET.

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 1 for module message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_module_config r#

union ipc4_module_config primary#

uint32_t param_id_data#: Packed 16-bit parameter data and 14-bit parameter ID.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_module_config r

union ipc4_module_config extension#

struct ipc4_module_config_reply#

#include <src/include/ipc4/module.h>

Reply structure for small parameter query (SOF_IPC4_MOD_CONFIG_GET).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t status#: Command processing status (enum ipc4_status).

uint32_t type#: Opcode: SOF_IPC4_MOD_CONFIG_GET.

uint32_t rsp#: 1 for reply.

uint32_t msg_tgt#: 1 for module message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_module_config_reply r#

union ipc4_module_config_reply primary#

uint32_t param_id_data#: Returned parameter value if fitting in 30 bits.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_module_config_reply r

union ipc4_module_config_reply extension#

struct ipc4_module_large_config#

#include <src/include/ipc4/module.h>

Large configuration parameter transfer envelope (SOF_IPC4_MOD_LARGE_CONFIG_GET / SET).

Implements the multi-block fragmentation handshake for exchanging configuration payloads exceeding the mailbox window size (e.g. FIR coefficients, EQ curves, model blobs).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t module_id#: Target module class ID.

uint32_t instance_id#: Target module instance ID.

uint32_t type#: LARGE_CONFIG_GET (3) or LARGE_CONFIG_SET (4).

uint32_t rsp#: 0 for request, 1 for reply.

uint32_t msg_tgt#: 1 for module target.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_module_large_config r#

union ipc4_module_large_config primary#

uint32_t data_off_size#: Chunk byte size (single block) or cumulative byte offset (multi-block).

uint32_t large_param_id#: Parameter type identifier (module-specific or VENDOR_CONFIG_PARAM).

uint32_t final_block#: Set to 1 on the terminating chunk of a multi-block transfer.

uint32_t init_block#: Set to 1 on the initial chunk of a multi-block transfer.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_module_large_config r

union ipc4_module_large_config extension#

struct ipc4_module_large_config_reply#

#include <src/include/ipc4/module.h>

Reply structure for large configuration transfer.

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t status#: Processing status (enum ipc4_status).

uint32_t type#: Symmetric opcode.

uint32_t rsp#: 1 for reply.

uint32_t msg_tgt#: Symmetric target.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_module_large_config_reply r#

union ipc4_module_large_config_reply primary#

uint32_t data_off_size#: Processed byte size or offset.

uint32_t large_param_id#: Parameter type ID.

uint32_t final_block#: 1 if final block processed.

uint32_t init_block#: 1 if first block processed.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_module_large_config_reply r

union ipc4_module_large_config_reply extension#

struct ipc4_module_delete_instance#

#include <src/include/ipc4/module.h>

Module instance deletion command structure (SOF_IPC4_MOD_DELETE_INSTANCE).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t module_id#: Module class ID of instance to destroy.

uint32_t instance_id#: Instance ID to destroy.

uint32_t type#: Opcode: SOF_IPC4_MOD_DELETE_INSTANCE (11).

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 1 for module target.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_module_delete_instance r#

union ipc4_module_delete_instance primary#

uint32_t rsvd#: Reserved padding.

uint32_t _reserved_1#: Reserved bits.

struct ipc4_module_delete_instance r

union ipc4_module_delete_instance extension#

struct ipc4_module_set_d0ix#

#include <src/include/ipc4/module.h>

Module D0ix low-power state entry command (SOF_IPC4_MOD_SET_D0IX).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t module_id#: Module ID (must be 0 for Base FW).

uint32_t instance_id#: Instance ID (must be 0 for core 0).

uint32_t type#: Opcode: SOF_IPC4_MOD_SET_D0IX (8).

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 1 for module message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_module_set_d0ix r#

union ipc4_module_set_d0ix primary#

uint32_t wake#: Legacy wake type flag.

uint32_t streaming#: Active audio streaming indicator.

uint32_t prevent_power_gating#: Set to 1 to inhibit DSP core power gating.

uint32_t prevent_local_clock_gating#: Set to 1 to inhibit local clock gating.

uint32_t rsvd1#: Reserved padding.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_module_set_d0ix r

union ipc4_module_set_d0ix extension#

struct ipc4_dx_state_info#

#include <src/include/ipc4/module.h>

DSP core power state bitmask descriptor.

Public Members

uint32_t core_mask#: Bitmask indicating which DSP cores are subject to state change.

uint32_t dx_mask#: Target state bitmask: bit[core_id] = 0 -> put to D3, bit[core_id] = 1 -> put to D0.

struct ipc4_module_set_dx#

#include <src/include/ipc4/module.h>

Core DX power state transition command structure (SOF_IPC4_MOD_SET_DX).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t module_id#: Module ID (0 for Base FW).

uint32_t instance_id#: Instance ID (0 for Core 0).

uint32_t type#: Opcode: SOF_IPC4_MOD_SET_DX (7).

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 1 for module message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_module_set_dx r#

union ipc4_module_set_dx primary#

uint32_t rsvd#: Reserved padding.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_module_set_dx r

union ipc4_module_set_dx extension#

struct ipc4_module_load_library#

#include <src/include/ipc4/module.h>

Dynamic library loading command structure (SOF_IPC4_GLB_LOAD_LIBRARY).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t dma_id#: ID of Host Output DMA used to load code.

uint32_t rsvd0#: Reserved padding.

uint32_t lib_id#: Dynamic library container ID (0..15).

uint32_t rsvd1#: Reserved padding.

uint32_t type#: Opcode: SOF_IPC4_GLB_LOAD_LIBRARY (24).

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 0 for global firmware message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_module_load_library r#

union ipc4_module_load_library header#

uint32_t load_offset#: Load offset into host DMA buffer.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_module_load_library r

union ipc4_module_load_library data#

4. Audio Pipelines & Scheduling Priorities#

Covers audio pipeline graph allocation, scheduling domain priorities (Low Latency vs Data Processing), pipeline state transitions (Reset, Paused, Running), memory context queries, and direct DMA chaining.

group IPC4 Pipeline Lifecycle & State Machine

Pipeline creation, priority assignments, state machine transitions (RESET, PAUSED, RUNNING, EOS), multi-pipeline synchronization, and save/restore.

Enums

enum ipc4_pipeline_priority#

Pipeline execution scheduling priority levels.

Values:

enumerator SOF_IPC4_PIPELINE_PRIORITY_0#: Priority level 0 (highest priority, scheduled first).

enumerator SOF_IPC4_PIPELINE_PRIORITY_1#: Priority level 1.

enumerator SOF_IPC4_PIPELINE_PRIORITY_2#: Priority level 2.

enumerator SOF_IPC4_PIPELINE_PRIORITY_3#: Priority level 3.

enumerator SOF_IPC4_PIPELINE_PRIORITY_4#: Priority level 4.

enumerator SOF_IPC4_PIPELINE_PRIORITY_5#: Priority level 5.

enumerator SOF_IPC4_PIPELINE_PRIORITY_6#: Priority level 6.

enumerator SOF_IPC4_PIPELINE_PRIORITY_7#: Priority level 7 (lowest priority).

enumerator SOF_IPC4_MAX_PIPELINE_PRIORITY#: Maximum valid priority level.

enum ipc4_pipeline_state#

Pipeline operational state machine values.

Values:

enumerator SOF_IPC4_PIPELINE_STATE_INVALID#: Invalid or uninitialized pipeline state.

enumerator SOF_IPC4_PIPELINE_STATE_UNINITIALIZED#: Created but module initialization is incomplete.

enumerator SOF_IPC4_PIPELINE_STATE_RESET#: Reset state: buffers cleared, hardware inactive.

enumerator SOF_IPC4_PIPELINE_STATE_PAUSED#: Paused state: buffers pre-allocated, clocks armed.

enumerator SOF_IPC4_PIPELINE_STATE_RUNNING#: Running state: audio streaming actively scheduled.

enumerator SOF_IPC4_PIPELINE_STATE_EOS#: End Of Stream (EOS): draining final buffered audio.

enumerator SOF_IPC4_PIPELINE_STATE_ERROR_STOP#: Pipeline halted due to unrecoverable DSP error.

enumerator SOF_IPC4_PIPELINE_STATE_SAVED#: Pipeline context serialized to host memory for D3.

enum ipc4_pipeline_ext_obj_id#

Extended pipeline object type identifiers.

Values:

enumerator IPC4_GLB_PIPE_EXT_OBJ_ID_INVALID#: Invalid extension object identifier.

enumerator IPC4_GLB_PIPE_EXT_OBJ_ID_MEM_DATA#: Pipeline memory stack/heap allocation parameters.

enumerator IPC4_GLB_PIPE_EXT_OBJ_ID_MAX#: Maximum extension object ID.

struct ipc4_pipeline_ext_object#

#include <src/include/ipc4/pipeline.h>

Header for extended pipeline initialization objects.

Public Members

uint32_t last_object#: 1 if terminating object in array, 0 if another object follows.

uint32_t object_id#: Unique object identifier (enum ipc4_pipeline_ext_obj_id).

uint32_t object_words#: Payload size in 32-bit DWORDs following this header.

struct ipc4_pipeline_ext_obj_mem_data#

#include <src/include/ipc4/pipeline.h>

Memory allocation parameters for pipeline execution context.

Public Members

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.

struct ipc4_pipeline_ext_payload#

#include <src/include/ipc4/pipeline.h>

Container for extended pipeline creation payload.

Public Members

uint32_t payload_words#: Total payload size in 32-bit DWORDs.

uint32_t data_obj_array#: 1 if struct ipc4_pipeline_ext_object array follows.

uint32_t rsvd0#: Reserved bits.

uint32_t rsvd1#: Reserved word.

uint32_t rsvd2#: Reserved word.

struct ipc4_pipeline_create#

#include <src/include/ipc4/pipeline.h>

Pipeline creation command structure (SOF_IPC4_GLB_CREATE_PIPELINE).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t ppl_mem_size#: Number of 4KB memory pages allocated for pipeline.

uint32_t ppl_priority#: Scheduling priority (enum ipc4_pipeline_priority).

uint32_t instance_id#: Pipeline instance identifier (0..max_ppl-1).

uint32_t type#: Opcode: SOF_IPC4_GLB_CREATE_PIPELINE (17).

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 0 for global firmware message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_pipeline_create r#

union ipc4_pipeline_create primary#

uint32_t lp#: 1 = low power pipeline (kept running during D0i3).

uint32_t rsvd1#: Reserved bits.

uint32_t attributes#: Pipeline hardware attributes bitmask.

uint32_t core_id#: Target DSP core ID hosting this pipeline.

uint32_t rsvd2#: Reserved bits.

uint32_t payload#: 1 if struct ipc4_pipeline_ext_payload follows.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_pipeline_create r

union ipc4_pipeline_create extension#

struct ipc4_pipeline_delete#

#include <src/include/ipc4/pipeline.h>

Pipeline deletion command structure (SOF_IPC4_GLB_DELETE_PIPELINE).

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.

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t rsvd0#: Reserved padding.

uint32_t instance_id#: Pipeline instance identifier to delete.

uint32_t type#: Opcode: SOF_IPC4_GLB_DELETE_PIPELINE (18).

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 0 for global firmware message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_pipeline_delete r#

union ipc4_pipeline_delete primary#

uint32_t rsvd1#: Reserved padding.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_pipeline_delete r

union ipc4_pipeline_delete extension#

struct ipc4_pipeline_set_state_data#

#include <src/include/ipc4/pipeline.h>

Payload array containing pipeline IDs for multi-pipeline state transitions.

Host SW sends this message to set a pipeline to the specified state.

If there are multiple pipelines, from FW input to FW output, connected in a data processing stream, the driver should start them in reverse order, beginning with pipeline connected to the output gateway, in order to avoid overruns (FW protects the output gateway against underruns in this scenario).

If driver starts multiple pipelines using a single Set Pipeline State command, it should take care of the pipeline ID order in the command payload to follow the above rule.

sync_stop_start indicates whether all specified pipelines’ gateways should be started with a minimal delay possible. If this flag is set to 0 while multiple pipelines are specified, the target pipelines’ state is adjusted pipeline by pipeline meaning that internal propagation to all child modules may take more time between reaching state of attached gateways. Output and input gateways are grouped separately, and started/stopped separately.

NOTE: Task Creation/Registration is part of the first state transition. There is no other dedicated call for this.

Remark

hide_methods

Public Members

uint32_t pipelines_count#: Number of pipeline instance IDs in ppl_id[].

uint32_t ppl_id[]#: Array of pipeline instance identifiers.

struct ipc4_pipeline_set_state#

#include <src/include/ipc4/pipeline.h>

Pipeline state transition command structure (SOF_IPC4_GLB_SET_PIPELINE_STATE).

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.

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t ppl_state#: Target pipeline state (enum ipc4_pipeline_state).

uint32_t ppl_id#: Target pipeline ID (ignored if multi_ppl == 1).

uint32_t type#: Opcode: SOF_IPC4_GLB_SET_PIPELINE_STATE (19).

uint32_t rsp#: Direction: 0 for request.

uint32_t msg_tgt#: Target: 0 for global firmware message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_pipeline_set_state r#

union ipc4_pipeline_set_state primary#

uint32_t multi_ppl#: 1 if additional pipeline IDs are provided in s_data payload.

uint32_t sync_stop_start#: 1 if DSP should synchronize state transition across all pipelines.

uint32_t rsvd1#: Reserved padding.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_pipeline_set_state r

union ipc4_pipeline_set_state extension#

struct ipc4_pipeline_set_state_data s_data#: Optional multi-pipeline ID list.

struct ipc4_pipeline_set_state_reply#

#include <src/include/ipc4/pipeline.h>

Reply structure for pipeline state transition.

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t status#: Status code (enum ipc4_status).

uint32_t type#: Opcode: SOF_IPC4_GLB_SET_PIPELINE_STATE.

uint32_t rsp#: 1 for reply.

uint32_t msg_tgt#: 0 for global message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_pipeline_set_state_reply r#

union ipc4_pipeline_set_state_reply primary#

uint32_t ppl_id#: ID of failed pipeline on error.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_pipeline_set_state_reply r

union ipc4_pipeline_set_state_reply extension#

struct ipc4_pipeline_get_state#

#include <src/include/ipc4/pipeline.h>

Query pipeline current state command (SOF_IPC4_GLB_GET_PIPELINE_STATE).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t ppl_id#: Target pipeline instance identifier.

uint32_t rsvd#: Reserved padding.

uint32_t type#: Opcode: SOF_IPC4_GLB_GET_PIPELINE_STATE (20).

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 0 for global message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_pipeline_get_state r#

union ipc4_pipeline_get_state primary#

uint32_t rsvd1#: Reserved padding.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_pipeline_get_state r

union ipc4_pipeline_get_state extension#

struct ipc4_pipeline_get_state_reply#

#include <src/include/ipc4/pipeline.h>

Reply structure containing pipeline current operational state.

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t status#: Status code (enum ipc4_status).

uint32_t type#: Opcode: SOF_IPC4_GLB_GET_PIPELINE_STATE.

uint32_t rsp#: 1 for reply.

uint32_t msg_tgt#: 0 for global message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_pipeline_get_state_reply r#

union ipc4_pipeline_get_state_reply primary#

uint32_t state#: Current state (one of enum ipc4_pipeline_state).

uint32_t rsvd1#: Reserved padding.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_pipeline_get_state_reply r

union ipc4_pipeline_get_state_reply extension#

struct ipc4_pipeline_get_context_size#

#include <src/include/ipc4/pipeline.h>

Query memory context size required to serialize pipeline (SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t rsvd0#: Reserved padding.

uint32_t instance_id#: Target pipeline instance ID.

uint32_t type#: Opcode: SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE (21).

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 0 for global message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_pipeline_get_context_size r#

union ipc4_pipeline_get_context_size primary#

uint32_t rsvd1#: Reserved padding.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_pipeline_get_context_size r

union ipc4_pipeline_get_context_size extension#

struct ipc4_pipeline_get_context_size_reply#

#include <src/include/ipc4/pipeline.h>

Reply structure for pipeline context size query.

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t status#: Status code (enum ipc4_status).

uint32_t type#: Opcode: SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE.

uint32_t rsp#: 1 for reply.

uint32_t msg_tgt#: 0 for global message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_pipeline_get_context_size_reply r#

union ipc4_pipeline_get_context_size_reply primary#

uint32_t ctx_size#: Size of pipeline serialization context in 4KB memory pages.

uint32_t rsvd1#: Reserved padding.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_pipeline_get_context_size_reply r

union ipc4_pipeline_get_context_size_reply extension#

struct ipc4_chain_dma#

#include <src/include/ipc4/pipeline.h>

Direct DMA Chaining configuration command (SOF_IPC4_GLB_CHAIN_DMA).

Public Members

uint32_t dat#

Raw 32-bit Primary register value.

Raw 32-bit Extension register value.

uint32_t host_dma_id#: Host DMA channel identifier.

uint32_t rsvd4#: Reserved bits.

uint32_t link_dma_id#: Link DMA channel identifier.

uint32_t rsvd3#: Reserved bits.

uint32_t allocate#: Allocate FIFO buffer.

uint32_t enable#: Enable DMA chaining.

uint32_t scs#: Select stream context (SCS) bit in gateways.

uint32_t rsvd2#: Reserved bits.

uint32_t type#: Opcode: SOF_IPC4_GLB_CHAIN_DMA (14).

uint32_t rsp#: 0 for request.

uint32_t msg_tgt#: 0 for global message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_chain_dma r#

union ipc4_chain_dma primary#

uint32_t fifo_size#: Size of chaining FIFO buffer in bytes.

uint32_t rsvd1#: Reserved bits.

uint32_t _reserved_2#: Reserved bits.

struct ipc4_chain_dma r

union ipc4_chain_dma extension#

5. Base Firmware & ADSP Configuration#

Provides access to Core 0 Base Firmware system services, ADSP hardware properties, frequency steps, physical SRAM page allocation tables, power manager A-states, and system time.

group IPC4 Base Firmware & Global Configuration

Core 0 Base Firmware management, ADSP global properties, hardware capabilities, memory pools, power budget tables, and crash dump telemetry.

Enums

enum ipc4_basefw_params#

IPC4 Base Firmware configuration and query parameter IDs.

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).

Values:

enumerator IPC4_DSP_PROPERTIES#: Retrieve firmware properties as TLV structure with typeof AdspProperties via LARGE_CONFIG_GET.

enumerator IPC4_DSP_RESOURCE_STATE#: Retrieve DSP resource state via LARGE_CONFIG_GET.

enumerator IPC4_RESERVED#: Reserved parameter identifier.

enumerator IPC4_NOTIFICATION_MASK#

Enable or disable asynchronous notifications.

Used in debug mode to prevent flooding the host with underrun notifications during breakpoints.

enumerator IPC4_ASTATE_TABLE#

Configure available power states according to the underlying platform.

Driver sends A-State table data right after Base FW is up.

enumerator IPC4_DMA_CONTROL#

Initialize or modify DMA gateway configuration outside stream lifetime.

Starts with struct ipc4_dma_control followed by optional gateway-specific data.

enumerator IPC4_ENABLE_LOGS#: Configure firmware logging state (enable/disable per core, log level, aging timer, FIFO full timer).

enumerator IPC4_FW_CONFIG#: Discover or set firmware configuration in TLV format (read/write via LARGE_CONFIG_GET / LARGE_CONFIG_SET).

enumerator IPC4_HW_CONFIG_GET#: Discover underlying hardware configuration in TLV format via LARGE_CONFIG_GET.

enumerator IPC4_MODULES_INFO_GET#: Retrieve list of module entries loaded into firmware memory space (image manifest or library manifest) via LARGE_CONFIG_GET.

enumerator IPC4_PIPELINE_LIST_INFO_GET#: Retrieve list of instantiated pipeline IDs via LARGE_CONFIG_GET.

enumerator IPC4_PIPELINE_PROPS_GET#: Retrieve pipeline properties for a given pipeline ID via LARGE_CONFIG_GET.

enumerator IPC4_SCHEDULERS_INFO_GET#: Retrieve list of task schedulers and tasks running on a core via LARGE_CONFIG_GET.

enumerator IPC4_GATEWAYS_INFO_GET#: Retrieve gateway configuration information via LARGE_CONFIG_GET.

enumerator IPC4_MEMORY_STATE_INFO_GET#: Retrieve information about current DSP memory state via LARGE_CONFIG_GET.

enumerator IPC4_POWER_STATE_INFO_GET#: Retrieve information about current DSP power state via LARGE_CONFIG_GET.

enumerator IPC4_LIBRARIES_INFO_GET#: Retrieve information about external libraries loaded into DSP memory.

enumerator IPC4_PERF_MEASUREMENTS_STATE#: Control global performance measurement state (MCPS monitoring).

enumerator IPC4_GLOBAL_PERF_DATA#: Retrieve global performance data (KCPS sampled per tick/frame).

enumerator IPC4_L2_CACHE_INFO_GET#: Retrieve L2 cache state information.

enumerator IPC4_SYSTEM_TIME#: Pass down host system time in microseconds (UTC, epoch 1601-01-01T00:00:00Z) to synchronize log and trace timestamps.

enumerator IPC4_PERFORMANCE_CONFIGURATION#: Configure firmware for performance mode via LARGE_CONFIG_SET.

enumerator IPC4_REGISTER_KCPS#: Register KCPS into power manager service per core 0 (negative values allowed).

enumerator IPC4_RESOURCE_ALLOCATION_REQUEST#: Request additional resource allocation via LARGE_CONFIG_SET.

enumerator IPC4_IO_PERF_MEASUREMENTS_STATE#: Control I/O performance measurement state in firmware.

enumerator IPC4_IO_GLOBAL_PERF_DATA#: Retrieve I/O global performance statistics.

enumerator IPC4_GET_MODULE_ID#: Retrieve module ID for a specified module UUID.

enumerator IPC4_EXTENDED_SYSTEM_TIME#: Retrieve current UTC, RTC, and ART timestamps (requires SYSTEM_TIME set first).

enumerator IPC4_TELEMETRY_STATE#: Control telemetry collection process state and thresholds.

enumerator IPC4_TELEMETRY_DATA#: Read data from circular telemetry buffer.

enumerator IPC4_EXTENDED_GLOBAL_PERF_DATA#: Extended global performance data with per-module DSP cycle statistics.

enumerator IPC4_SDW_OWNERSHIP#: Configure SoundWire controller ownership via LARGE_CONFIG_SET.

enumerator IPC4_MIC_PRIVACY_HW_MANAGED_STATE_CHANGE#: Notify firmware of hardware-managed microphone privacy state change.

enumerator IPC4_SET_MIC_PRIVACY_FW_MANAGED_POLICY_MASK#: Set policy mask for microphone privacy in firmware-managed mode.

enum ipc4_fw_config_params#

Firmware configuration parameter TLV IDs returned by IPC4_FW_CONFIG.

Values:

enumerator IPC4_FW_VERSION_FW_CFG#: Firmware version.

enumerator IPC4_MEMORY_RECLAIMED_FW_CFG#: Indicates whether legacy DMA memory is managed by FW.

enumerator IPC4_SLOW_CLOCK_FREQ_HZ_FW_CFG#: Frequency of oscillator clock in Hz.

enumerator IPC4_FAST_CLOCK_FREQ_HZ_FW_CFG#: Frequency of PLL clock in Hz.

enumerator IPC4_DMA_BUFFER_CONFIG_FW_CFG#

List of static and dynamic DMA buffer sizes.

Host software may configure minimum and maximum size for each buffer.

enumerator IPC4_ALH_SUPPORT_LEVEL_FW_CFG#

Audio Hub Link (ALH) support level.

Lower 16 bits may indicate implementation revision.

enumerator IPC4_DL_MAILBOX_BYTES_FW_CFG#: Size of IPC downlink mailbox in bytes.

enumerator IPC4_UL_MAILBOX_BYTES_FW_CFG#: Size of IPC uplink mailbox in bytes.

enumerator IPC4_TRACE_LOG_BYTES_FW_CFG#: Size of trace log buffer in bytes.

enumerator IPC4_MAX_PPL_CNT_FW_CFG#: Maximum number of pipelines that may be instantiated simultaneously.

enumerator IPC4_MAX_ASTATE_COUNT_FW_CFG#

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.

enumerator IPC4_MAX_MODULE_PIN_COUNT_FW_CFG#: Maximum number of input or output pins supported by a module.

enumerator IPC4_MODULES_COUNT_FW_CFG#: Current total number of module entries loaded into the DSP.

enumerator IPC4_MAX_MOD_INST_COUNT_FW_CFG#: Maximum number of module instances supported by FW.

enumerator IPC4_MAX_LL_TASKS_PER_PRI_COUNT_FW_CFG#: Maximum number of LL tasks that may be allocated with the same priority (specified by parent pipeline priority).

enumerator IPC4_LL_PRI_COUNT#: Number of Low Latency (LL) scheduling priorities.

enumerator IPC4_MAX_DP_TASKS_COUNT_FW_CFG#: Maximum number of DP tasks that may be allocated on a single core.

enumerator IPC4_MAX_LIBS_COUNT_FW_CFG#: Maximum number of external libraries that can be loaded into ADSP memory.

enumerator IPC4_SCHEDULER_CONFIGURATION#: Configuration of system tick source and period.

enumerator IPC4_XTAL_FREQ_HZ_FW_CFG#: Frequency of XTAL oscillator clock in Hz.

enumerator IPC4_CLOCKS_CONFIGURATION#: Configuration of clocks.

enumerator IPC4_UAOL_SUPPORT#: USB Audio Offload (UAOL) support indicator.

enumerator IPC4_POWER_GATING_POLICY#: Configuration of Dynamic Power Gating Policy.

enumerator IPC4_ASSERT_MODE#

Configuration of assert mode.

Asserts use format “%passert”, ptr_to_assert_desc in .asserts_desc section.

enumerator IPC4_TELEMETRY_BUFFER_SIZE#: Size of telemetry circular buffer in bytes (default 4KB).

enumerator IPC4_BUS_HARDWARE_ID#: Hardware version and bus hardware identifier.

enumerator IPC4_DEBUG_WINDOW_SIZE#: Total memory size available in debug window.

enumerator IPC4_KPB_RT_SINK_COUNT#: Number of real-time Key Phrase Buffer (KPB) output sink pins.

enumerator IPC4_DMI_FORCE_L1_EXIT#: Manual control of DMI L1 state exit.

enumerator IPC4_FW_CONTEXT_SAVE#: Firmware context save on D3 power state entry.

enumerator IPC4_FW_MIN_HOST_BUFFER_PERIODS#: Minimum size of host buffer in milliseconds.

enumerator IPC4_FW_SOF_INFO#: SOF specific decoder/encoder codec information.

enumerator IPC4_FW_CFG_PARAMS_COUNT#: Total number of FW config parameters.

enumerator IPC4_MAX_FW_CFG_PARAM#: Maximum FW config parameter ID value.

enum ipc4_fw_sof_info_params#

Tuple-based parameters for SOF specific info under IPC4_FW_SOF_INFO.

Values:

enumerator IPC4_SOF_CODEC_INFO#: Decoder/encoder codec information.

enumerator IPC4_SOF_CFG_PARAMS_COUNT#: Total number of SOF config parameters.

enumerator IPC4_MAX_SOF_CFG_PARAM#: Maximum SOF config parameter ID value.

enum ipc4_hw_config_params#

Hardware configuration parameter TLV IDs returned by IPC4_HW_CONFIG_GET.

Values:

enumerator IPC4_CAVS_VER_HW_CFG#: Version of CAVS/ACE architecture implemented by FW (from ROMInfo).

enumerator IPC4_DSP_CORES_HW_CFG#: Number of DSP cores available in the audio subsystem.

enumerator IPC4_MEM_PAGE_BYTES_HW_CFG#: Size of a single memory page in bytes (typically 4096).

enumerator IPC4_TOTAL_PHYS_MEM_PAGES_HW_CFG#: Total number of physical memory pages available for allocation.

enumerator IPC4_I2S_CAPS_HW_CFG#

I2S controller capabilities.

Array count given by controller_count. Lower 16 bits may indicate implementation revision.

enumerator IPC4_GPDMA_CAPS_HW_CFG#: General Purpose DMA (GPDMA) controller capabilities.

enumerator IPC4_GATEWAY_COUNT_HW_CFG#: Total number of DMA gateways of all types.

enumerator IPC4_HP_EBB_COUNT_HW_CFG#: Number of High Power (HP) SRAM memory banks (EBBs) manageable by DSP.

enumerator IPC4_LP_EBB_COUNT_HW_CFG#: Number of Low Power (LP) SRAM memory banks (EBBs) manageable by DSP.

enumerator IPC4_EBB_SIZE_BYTES_HW_CFG#: Size of a single memory bank (EBB) in bytes.

enumerator IPC4_UAOL_CAPS_HW_CFG#: USB Audio Offload (UAOL) controller capabilities.

enumerator IPC4_INTEL_MIC_PRIVACY_CAPS_HW_CFG#: Microphone privacy hardware capabilities.

enum ipc4_memory_type#

SRAM power memory type.

Values:

enumerator IPC4_HP_SRAM_MEMORY#: High Power (HP) SRAM memory.

enumerator IPC4_LP_SRAM_MEMORY#: Low Power (LP) SRAM memory.

enum ipc4_resource_state_request#

DSP resource state request types.

Values:

enumerator IPC4_FREE_PHYS_MEM_PAGES#: Query free physical HP SRAM memory pages available.

enum ipc4_clock_src#

Hardware clock source selection.

Values:

enumerator IPC4_CLOCK_SRC_XTAL#: Low Power XTAL oscillator clock source.

enumerator IPC4_CLOCK_SRC_LP_RING_OSC#: Low Power Ring Oscillator (RO).

enumerator IPC4_CLOCK_SRC_HP_RING_OSC#: High Power Ring Oscillator (RO).

enumerator IPC4_CLOCK_SRC_WOV_XTAL#

Low Power Wake-on-Voice (WoV) XTAL oscillator.

Generated internal to IP for optimal low-power listening.

enumerator IPC4_CLOCK_SRC_INVALID#: Invalid clock source sentinel.

enumerator IPC4_CLOCK_SRC_MAX_IDX#: Maximum valid clock source index.

enum ipc4_perf_measurements_state_set#

Performance measurement process states.

Values:

enumerator IPC4_PERF_MEASUREMENTS_DISABLED#: Performance measurements disabled.

enumerator IPC4_PERF_MEASUREMENTS_STOPPED#: Performance measurements stopped.

enumerator IPC4_PERF_MEASUREMENTS_STARTED#: Performance measurements actively running.

enumerator IPC4_PERF_MEASUREMENTS_PAUSED#: Performance measurements paused.

enum ipc4_low_latency_interrupt_source#

Low latency interrupt source types.

Values:

enumerator IPC4_LOW_POWER_TIMER_INTERRUPT_SOURCE#: Low Power Timer interrupt.

enumerator IPC4_DMA_GATEWAY_INTERRUPT_SOURCE#: DMA Gateway completion interrupt.

enum ipc4_pipeline_attributes#

Pipeline attributes flags.

Values:

enumerator IPC4_ULTRA_LOW_POWER#: Pipeline contains modules with Ultra Low Power (ULP) capability.

enumerator IPC4_AUTONOMOUS_RESET#: Pipeline contains modules capable of autonomous reset reporting.

enum ipc4_resource_allocation_type#

Resource allocation request types.

Values:

enumerator IPC4_RAT_DSP_KCPS#: Allocate DSP processing capacity in KCPS.

enumerator IPC4_RAT_MEMORY#: Allocate physical SRAM memory.

enum ipc4_alh_version#

Audio Hub Link (ALH) interface versions.

Values:

enumerator IPC4_ALH_NO_SUPPORT#: ALH not supported.

enumerator IPC4_ALH_CAVS_1_8#: CAVS 1.8+ ALH implementation.

enum ipc4_power_state_type#

Power state query types.

Values:

enumerator IPC4_ACTIVE_CORES_MASK#: Query bitmask of currently active DSP cores.

enumerator IPC4_CORE_KCPS#: Query core clock KCPS settings.

Functions

struct ipc4_system_time_info *basefw_get_system_time_info(void)#

Get current DSP system time information for host-DSP clock synchronization.

Returns:: Pointer to struct ipc4_system_time_info containing current 64-bit timestamp.

struct ipc4_phys_mem_pages#

#include <src/include/ipc4/base_fw.h>

Free physical memory page descriptor.

Public Members

uint32_t mem_type#: Memory type (enum ipc4_memory_type).

uint32_t pages#: Number of free memory pages available.

struct ipc4_notification_mask_info#

#include <src/include/ipc4/base_fw.h>

Notification mask configuration structure (IPC4_NOTIFICATION_MASK).

Public Members

uint32_t ntfy_mask#: Bitmask indicating which notifications are being modified.

uint32_t enabled_mask#: Bitmask indicating enable (1) or disable (0) state for notifications selected in ntfy_mask.

struct ipc4_astate#

#include <src/include/ipc4/base_fw.h>

A-State frequency and load threshold entry.

Public Members

uint32_t kcps#

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.

enum ipc4_clock_src clock_src#: Clock source associated with kcps threshold (enum ipc4_clock_src).

struct ipc4_astate_table#

#include <src/include/ipc4/base_fw.h>

Power Manager A-State configuration table (IPC4_ASTATE_TABLE).

Public Members

uint32_t astates_count_#: Number of active entries in astates_ array.

struct ipc4_astate astates_[3]#: Array of power states.

struct ipc4_dma_control#

#include <src/include/ipc4/base_fw.h>

Direct DMA Gateway Control structure (IPC4_DMA_CONTROL).

Public Members

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).

struct ipc4_perf_data_item#

#include <src/include/ipc4/base_fw.h>

Single component performance measurement data item.

Public Members

uint32_t resource_id#: Resource ID: core ID or {module_id, instance_id}.

uint32_t power_mode#: Power mode: 0 = D0, 1 = D0i3.

uint32_t rsvd#: Reserved padding.

uint32_t is_removed#: 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.

struct ipc4_perf_data_item_mi#

#include <src/include/ipc4/base_fw.h>

Module instance performance data with internal iteration metrics.

Public Members

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.

struct ipc4_global_perf_data#

#include <src/include/ipc4/base_fw.h>

Global DSP performance report payload (IPC4_GLOBAL_PERF_DATA).

Public Members

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.

struct ipc4_scheduler_config#

#include <src/include/ipc4/base_fw.h>

Scheduler tick and timer configuration (IPC4_SCHEDULER_CONFIGURATION).

Public Members

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.

struct ipc4_system_time#

#include <src/include/ipc4/base_fw.h>

64-bit system timestamp split into lower and upper 32-bit words.

Public Members

uint32_t val_l#: Lower 32 bits of microsecond timestamp.

uint32_t val_u#: Upper 32 bits of microsecond timestamp.

struct ipc4_system_time_info#

#include <src/include/ipc4/base_fw.h>

Host and DSP system time pairing for clock synchronization.

Public Members

struct ipc4_system_time host_time#: Host CPU timestamp.

struct ipc4_system_time dsp_time#: Corresponding DSP timestamp.

struct ipc4_ext_system_time#

#include <src/include/ipc4/base_fw.h>

Extended host/DSP system time with RTC and ART timestamps.

Public Members

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).

struct ipc4_resource_kcps#

#include <src/include/ipc4/base_fw.h>

KCPS resource allocation descriptor.

Public Members

uint32_t core_id#: DSP core identifier.

int32_t kcps#: KCPS capacity to allocate or release (signed).

struct ipc4_resource_memory#

#include <src/include/ipc4/base_fw.h>

Memory resource allocation descriptor.

Public Members

uint32_t address#: Base physical address to allocate.

uint32_t size#: Size of memory allocation in bytes.

struct ipc4_resource_request#

#include <src/include/ipc4/base_fw.h>

Resource allocation request structure (IPC4_RESOURCE_ALLOCATION_REQUEST).

Public Members

uint32_t ra_type#: Resource allocation type (enum ipc4_resource_allocation_type).

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.

union ipc4_resource_request ra_data#: Resource payload union.

struct ipc4_sram_state_page_alloc#

#include <src/include/ipc4/base_fw.h>

SRAM page allocation bitmask array.

Public Members

uint32_t page_alloc_count#: Number of items in page_alloc array.

uint16_t page_alloc[1]#: Bit[i] indicates whether i-th memory page is allocated.

struct ipc4_sram_state_info#

#include <src/include/ipc4/base_fw.h>

Detailed SRAM state and power bank information (IPC4_MEMORY_STATE_INFO_GET).

Public Members

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.

uint32_t ebb_state[1]#: Bit[i] indicates whether i-th EBB bank is powered up (1) or off (0).

struct ipc4_sram_state_page_alloc page_alloc_struct#: Page allocation state.

struct ipc4_library_props#

#include <src/include/ipc4/base_fw.h>

Properties of a dynamic or preloaded external library.

Public Members

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.

struct ipc4_libraries_info#

#include <src/include/ipc4/base_fw.h>

Library information report payload (IPC4_LIBRARIES_INFO_GET).

Public Members

uint32_t library_count#: Number of libraries reported.

struct ipc4_library_props libraries[0]#: Array of library property structures.

struct ipc4_log_state_info#

#include <src/include/ipc4/base_fw.h>

Logging configuration and state control (IPC4_ENABLE_LOGS).

Public Members

uint32_t aging_timer_period#: Aging timer period in system ticks for log buffer flush notification.

uint32_t fifo_full_timer_period#: Latency in system ticks for logging dropped entries after buffer read.

uint32_t enable#: 1 to enable logging, 0 to disable.

uint32_t logs_mask[IPC4_MAX_LIBS_COUNT]#: Priority and component logging masks per library provider.

struct task_props#

#include <src/include/ipc4/base_fw.h>

Single task properties within scheduler information.

Public Members

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.

struct scheduler_props#

#include <src/include/ipc4/base_fw.h>

Core scheduler properties and scheduled tasks.

Public Members

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.

struct schedulers_info#

#include <src/include/ipc4/base_fw.h>

Complete scheduler topology report (IPC4_SCHEDULERS_INFO_GET).

Public Members

uint32_t scheduler_count#: Number of schedulers reported.

struct scheduler_props scheduler_info[]#: Array of scheduler properties.

struct perf_data_item#

#include <src/include/ipc4/base_fw.h>

FW component performance measurement item.

Public Members

uint32_t resource_id#: Component resource ID.

uint32_t power_mode#: Power mode: 0 = D0, 1 = D0i3.

uint32_t rsvd#: Reserved bits.

uint32_t is_removed#: 0 if component exists, 1 if deleted.

uint32_t peak_kcps#: Peak KCPS captured.

uint32_t avg_kcps#: Average KCPS measured.

struct ext_perf_data_item#

#include <src/include/ipc4/base_fw.h>

Extended component performance metrics with DSP cycle counts.

Public Members

uint32_t resource_id#: Component resource identifier.

uint32_t power_mode#: Power mode: 0 = D0, 1 = D0i3.

uint32_t rsvd#: Reserved bits.

uint32_t is_removed#: 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.

struct extended_global_perf_data#

#include <src/include/ipc4/base_fw.h>

Extended global performance data report (IPC4_EXTENDED_GLOBAL_PERF_DATA).

Public Members

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.

struct perf_data_item_comp#

#include <src/include/ipc4/base_fw.h>

Component performance data with wall clock cycle metrics.

Public Members

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.

struct global_perf_data#

#include <src/include/ipc4/base_fw.h>

Global DSP performance summary.

Public Members

uint32_t perf_item_count#: Number of items in perf_items array.

struct perf_data_item perf_items[0]#: Array of performance items.

6. Hardware Gateways & Peripherals#

Encodes hardware connector addressing (node IDs) and configuration blobs for Intel High Definition Audio (HDA), Audio Hub Link (ALH / SoundWire) aggregation, Digital Microphones (DMIC), and Synchronous Serial Ports (SSP / I2S).

group IPC4 Hardware Audio Gateways

Audio gateway addressing (HD-Audio host/link, SoundWire ALH aggregation, DMIC link, SSP/I2S), gateway attributes, and NHLT configuration blobs.

Enums

enum ipc4_connector_node_id_type#

Hardware and virtual audio gateway connector types.

Values:

enumerator ipc4_hda_host_output_class#: HD/A host output stream (Host to DSP playback).

enumerator ipc4_hda_host_input_class#: HD/A host input stream (DSP to Host capture).

enumerator ipc4_hda_host_inout_class#: HD/A host bidirectional stream (reserved for future use).

enumerator ipc4_hda_link_output_class#: HD/A link output (DSP to external codec playback).

enumerator ipc4_hda_link_input_class#: HD/A link input (external codec to DSP capture).

enumerator ipc4_hda_link_inout_class#: HD/A link bidirectional stream (reserved for future use).

enumerator ipc4_dmic_link_input_class#: Digital Microphone (DMIC) link input (microphones to DSP capture).

enumerator ipc4_i2s_link_output_class#: I2S/SSP link output (DSP to I2S codec playback).

enumerator ipc4_i2s_link_input_class#: I2S/SSP link input (I2S codec to DSP capture).

enumerator ipc4_alh_link_output_class#: ALH link output, legacy alias for SoundWire (DSP to SoundWire link).

enumerator ipc4_alh_link_input_class#: ALH link input, legacy alias for SoundWire (SoundWire link to DSP).

enumerator ipc4_alh_snd_wire_stream_link_output_class#: SoundWire link output stream (DSP to SoundWire codec playback).

enumerator ipc4_alh_snd_wire_stream_link_input_class#: SoundWire link input stream (SoundWire codec to DSP capture).

enumerator ipc4_alh_uaol_stream_link_output_class#: USB Audio Offload (UAOL) link output (DSP to UAOL controller).

enumerator ipc4_alh_uaol_stream_link_input_class#: USB Audio Offload (UAOL) link input (UAOL controller to DSP).

enumerator ipc4_ipc_output_class#: Inter-Processor Communication (IPC) output (DSP to host/peer).

enumerator ipc4_ipc_input_class#: Inter-Processor Communication (IPC) input (host/peer to DSP).

enumerator ipc4_i2s_multi_link_output_class#: I2S aggregated multi-gateway output.

enumerator ipc4_i2s_multi_link_input_class#: I2S aggregated multi-gateway input.

enumerator ipc4_gpio_class#: GPIO hardware gateway.

enumerator ipc4_spi_output_class#: SPI hardware gateway output.

enumerator ipc4_spi_input_class#: SPI hardware gateway input.

enumerator ipc4_max_connector_node_id_type#: Sentinel marking maximum connector node ID type.

enum ipc4_gateway_type#

Gateway peripheral category bitmask.

Values:

enumerator ipc4_gtw_none#: No gateway specified.

enumerator ipc4_gtw_host#: Host DMA gateway.

enumerator ipc4_gtw_dmic#: Digital microphone gateway.

enumerator ipc4_gtw_link#: HD/A link gateway.

enumerator ipc4_gtw_alh#: Audio Hub Link / SoundWire gateway.

enumerator ipc4_gtw_ssp#: SSP / I2S gateway.

enumerator ipc4_gtw_all#: Bitmask covering all gateway types.

enum ipc4_direction_type#

Audio data stream direction flags.

Values:

enumerator ipc4_playback#: Playback stream direction (host/memory to peripheral).

enumerator ipc4_capture#: Capture stream direction (peripheral to host/memory).

enumerator ipc4_bidirection#: Bidirectional stream direction.

Functions

static inline bool is_multi_gateway(const union ipc4_connector_node_id node_id)#

Check if an IPC4 connector node ID corresponds to an aggregated multi-gateway.

Parameters:

node_id – Gateway connector node ID.

Returns:

True if the node represents an aggregated multi-gateway, false otherwise.

static inline size_t get_alh_config_size(const struct sof_alh_configuration_blob *alh_blob)#

Calculate the serialized size of an ALH configuration blob.

Parameters:

alh_blob – Pointer to the ALH configuration structure.

Returns:

Size in bytes of the configuration blob.

struct ipc4_alh_multi_gtw_cfg#

#include <src/include/ipc4/alh.h>

Multi-gateway channel aggregation configuration.

Public Members

uint32_t count#: Number of single channels in mapping array.

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.

struct ipc4_alh_multi_gtw_cfg mapping[IPC4_ALH_MAX_NUMBER_OF_GTW]#

Single-to-multi aggregation mapping table.

Array of mapping items.

struct sof_alh_configuration_blob#

#include <src/include/ipc4/alh.h>

Full configuration blob for Audio Hub Link (ALH) gateways.

Public Members

union ipc4_gateway_attributes gtw_attributes#: Gateway memory placement attributes.

struct ipc4_alh_multi_gtw_cfg alh_cfg#: Multi-gateway channel aggregation mappings.

union dmic_global_cfg#

#include <src/include/ipc4/dmic.h>

Global hardware configuration for DMIC controller.

Public Members

uint32_t clock_on_delay#: Raw 32-bit clock on delay value.

uint32_t silence_period#: Specifies the period in milliseconds to override data with silence after DMA transfer is started.

uint32_t fade_in_period#: Specifies the period in milliseconds for fade-in to apply on input data (following silence_period if applied).

struct dmic_global_cfg ext_global_cfg#: Extended global configuration bitfields.

struct dmic_channel_cfg#

#include <src/include/ipc4/dmic.h>

Configuration parameters for a single DMIC channel.

Public Members

uint32_t out_control#: Output control register value.

struct dmic_fir_cfg#

#include <src/include/ipc4/dmic.h>

Finite Impulse Response (FIR) decimation filter configuration.

Public Members

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.

struct dmic_pdm_ctrl_cfg#

#include <src/include/ipc4/dmic.h>

Pulse Density Modulation (PDM) controller configuration for DMIC.

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.

Public Members

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).

struct dmic_config_blob#

#include <src/include/ipc4/dmic.h>

Complete configuration blob for Digital Microphone (DMIC) settings.

Contains time-slot mappings, global clock/ramp settings, channel routing, and per-PDM controller decimation parameters.

Public Members

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#: PDM channels to program from channel_cfg.

uint32_t clock_source#: Clock source selection for DMIC.

uint32_t rsvd#: 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.

struct dmic_config_data#

#include <src/include/ipc4/dmic.h>

Top-level DMIC configuration data container.

Public Members

union ipc4_gateway_attributes gtw_attributes#: Gateway memory allocation attributes.

struct dmic_config_blob dmic_blob#: Hardware DMIC configuration blob.

union ipc4_connector_node_id#

#include <src/include/ipc4/gateway.h>

Audio gateway addressing descriptor (connector node ID).

Encodes the gateway type and virtual DMA channel index for HDA, ALH, DMIC, and SSP gateways.

Public Members

uint32_t dw#: Raw 32-bit value of node ID.

uint32_t v_index#: Virtual DMA channel or FIFO index.

uint32_t dma_type#: Gateway type (enum ipc4_connector_node_id_type).

uint32_t _rsvd#: Reserved bits.

struct ipc4_connector_node_id f#: Bitfield access structure.

union ipc4_gateway_attributes#

#include <src/include/ipc4/gateway.h>

Gateway buffer allocation attributes.

Configures special memory placement for gateway FIFOs and DMA buffers.

Public Members

uint32_t dw#: Raw 32-bit attributes value.

uint32_t lp_buffer_alloc#: Allocate gateway buffers in Low Power (LP) SRAM.

uint32_t alloc_from_reg_file#: Allocate gateway structures from DSP register file.

uint32_t _rsvd#: Reserved bits.

struct ipc4_gateway_attributes bits#: Bitfield access structure.

struct ipc4_gateway_config_data#

#include <src/include/ipc4/gateway.h>

Generic gateway configuration blob container.

Public Members

union ipc4_gateway_attributes gtw_attributes#: Memory allocation attributes.

uint32_t config_blob[]#: Variable-length gateway-specific configuration payload.

struct ipc4_ipc_gateway_config_blob#

#include <src/include/ipc4/gateway.h>

Configuration parameters for IPC Host Gateway.

Public Members

uint32_t buffer_size#: Size of gateway circular buffer in bytes.

uint32_t notif_high#: Send notification when buffer exceeds high threshold.

uint32_t notif_low#: Send notification when buffer falls below low threshold.

uint32_t rsvd#: Reserved bits.

struct ipc4_ipc_gateway_config_blob f#: Bitfield access structure.

uint32_t flags_raw#: Raw 32-bit flags value.

union ipc4_ipc_gateway_config_blob 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.

struct ipc4_ssp_config#

#include <src/include/ipc4/ssp.h>

Hardware register configuration values for Intel SSP/I2S controller.

Public Members

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).

struct ipc4_ssp_mclk_config#

#include <src/include/ipc4/ssp.h>

Master Clock (MCLK) divider hardware configuration.

Public Members

uint32_t mdivc#: Master clock divider control register.

uint32_t mdivr#: Master clock divider ratio register.

struct ipc4_ssp_driver_config#

#include <src/include/ipc4/ssp.h>

Combined SSP hardware and clock configuration structure.

Public Members

struct ipc4_ssp_config i2s_config#: SSP controller register values.

struct ipc4_ssp_mclk_config mclk_config#: Master clock generator configuration.

struct ipc4_ssp_start_control#

#include <src/include/ipc4/ssp.h>

SSP interface clock start control parameters.

Public Members

uint32_t clock_warm_up#

Delay in milliseconds between enabling interface (when Copier is attached) and actual interface start.

Value of 0 means no delay.

uint32_t mclk#: Target clock: 1 for MCLK, 0 for SCLK.

uint32_t warm_up_ovr#: 1 means start clock immediately even if no Copier is attached.

uint32_t rsvd0#: Reserved padding.

struct ipc4_ssp_stop_control#

#include <src/include/ipc4/ssp.h>

SSP interface clock stop control parameters.

Public Members

uint32_t clock_stop_delay#

Delay in milliseconds between stopping interface (when Copier detaches) and stopping interface clocks.

0 means no delay.

uint32_t keep_running#: 1 means keep clock running continuously after Copier detaches.

uint32_t clock_stop_ovr#: 1 means stop clock immediately upon detachment.

uint32_t rsvd1#: Reserved padding.

union ipc4_ssp_dma_control#

#include <src/include/ipc4/ssp.h>

SSP dynamic DMA and clock control union.

Public Members

struct ipc4_ssp_dma_control.ipc4_ssp_control control_data#: Clock lifecycle controls.

struct ipc4_ssp_dma_control.ipc4_mn_div_config mndiv_control_data#: M/N divider ratio.

struct ipc4_mn_div_config#

#include <src/include/ipc4/ssp.h>

Fractional M/N clock divider settings.

Public Members

uint32_t mval#: M numerator value.

uint32_t nval#: N denominator value.

struct ipc4_ssp_control#

#include <src/include/ipc4/ssp.h>

Start and stop clock delay controls.

Public Members

struct ipc4_ssp_start_control start_control#: Clock warm-up parameters.

struct ipc4_ssp_stop_control stop_control#: Clock stop delay parameters.

struct ipc4_ssp_configuration_blob#

#include <src/include/ipc4/ssp.h>

Full SSP/I2S gateway configuration blob structure.

Public Members

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.

7. Asynchronous Notifications & Mailbox Registers#

Details unsolicited DSP-to-host event notifications (underrun/overrun alarms, budget violations, voice activity wake words), and Mailbox Window 0 telemetry register layouts. Unsolicited notifications use opcode SOF_IPC4_GLB_NOTIFICATION (opcode 27 / 0x1B). Notification dispatch functions return true when the notification is either queued or suppressed by the notification mask, and false if the notification pool is temporarily exhausted, indicating that the caller should retry.

group IPC4 Asynchronous Notifications & Telemetry Registers

Unsolicited DSP-to-host notifications, resource event reports, keyword detection events, watchdog alerts, and Mailbox Window 0 status registers.

Typedefs

typedef uint32_t ipc4_last_error#: Last error code reported by ROM or Base FW.

Enums

enum sof_ipc4_notification_type#

Unsolicited DSP-to-host asynchronous notification types.

Values:

enumerator SOF_IPC4_NOTIFY_PHRASE_DETECTED#: Key phrase detected by wake-on-voice engine.

enumerator SOF_IPC4_NOTIFY_RESOURCE_EVENT#: Resource event (underrun, overrun, budget violation).

enumerator SOF_IPC4_NOTIFY_LOG_BUFFER_STATUS#: Trace log buffer half-full or aging timer expired.

enumerator SOF_IPC4_NOTIFY_TIMESTAMP_CAPTURED#: Audio wallclock timestamp captured.

enumerator SOF_IPC4_NOTIFY_FW_READY#: Firmware initialization complete and ready for IPC.

enumerator SOF_IPC4_FW_AUD_CLASS_RESULT#: Audio classifier / acoustic event result.

enumerator SOF_IPC4_EXCEPTION_CAUGHT#: Critical DSP exception or panic caught.

enumerator SOF_IPC4_MODULE_NOTIFICATION#: Generic module-specific event notification.

enumerator SOF_IPC4_UAOL_EVENT#: USB Audio Offload event notification.

enumerator SOF_IPC4_PROBE_DATA_AVAILABLE#: Probe extraction buffer contains recorded audio.

enumerator SOF_IPC4_WATCHDOG_TIMEOUT#: Watchdog timer timeout interrupt on DSP core.

enumerator SOF_IPC4_MANAGEMENT_SERVICE#: System management service event notification.

enum sof_ipc4_resource_event_type#

Specific resource event types reported by identifiable FW entities.

Values:

enumerator SOF_IPC4_BUDGET_VIOLATION#: MCPS budget for module or core exceeded.

enumerator SOF_IPC4_MIXER_UNDERRUN_DETECTED#: Underrun detected by mixer/mixin component.

enumerator SOF_IPC4_STREAM_DATA_SEGMENT#: Stream data segment completed by gateway.

enumerator SOF_IPC4_PROCESS_DATA_ERROR#: Error caught during audio processing.

enumerator SOF_IPC4_STACK_OVERFLOW#: Stack overflow detected in module or thread.

enumerator SOF_IPC4_BUFFERING_MODE_CHANGED#: Key Phrase Buffer (KPB) buffering mode changed.

enumerator SOF_IPC4_GATEWAY_UNDERRUN_DETECTED#: Underrun detected at peripheral DMA gateway.

enumerator SOF_IPC4_GATEWAY_OVERRUN_DETECTED#: Overrun detected at peripheral DMA gateway.

enumerator SOF_IPC4_EDF_DOMAIN_UNSTABLE#: Data-processing EDF task missed its deadline.

enumerator SOF_IPC4_WATCHDOG_EVENT#: Watchdog expiration event.

enumerator SOF_IPC4_GATEWAY_HIGH_THRES#: IPC gateway reached high watermark threshold.

enumerator SOF_IPC4_GATEWAY_LOW_THRES#: IPC gateway reached low watermark threshold.

enumerator SOF_IPC4_I2S_BCE_DETECTED#: Bit Count Error detected on I2S/SSP port.

enumerator SOF_IPC4_I2S_CLK_STATE_CHANGED#: Clock state change (detected/lost) on I2S port.

enumerator SOF_IPC4_I2S_SINK_MODE_CHANGED#: I2S sink mode change (started/stopped dropping).

enumerator SOF_IPC4_I2S_SOURCE_MODE_CHANGED#: I2S source mode change (started/stopped zero-fill).

enumerator SOF_IPC4_SRE_DRIFT_TOO_HIGH#: Sample Rate Estimator frequency drift exceeded limit.

enumerator SOF_IPC4_TELEMETRY_DATA_STATUS#: Telemetry buffer exceeded threshold or aged.

enumerator SOF_IPC4_SNDW_DEBUG_INFO#

SoundWire debug notification (e.g.

external VAD).

enumerator SOF_IPC4_INVALID_RESOURCE_EVENT_TYPE#: Invalid resource event sentinel.

enum sof_ipc4_resource_type#

Originator resource category firing a resource event.

Values:

enumerator SOF_IPC4_MODULE_INSTANCE#: Event originated from a module instance.

enumerator SOF_IPC4_PIPELINE#: Event originated from a pipeline.

enumerator SOF_IPC4_GATEWAY#: Event originated from a DMA gateway.

enumerator SOF_IPC4_EDF_TASK#: Event originated from an EDF DP task.

enumerator SOF_IPC4_INVALID_RESOURCE_TYPE#: Invalid resource type sentinel.

Functions

static inline void ipc4_notification_watchdog_init(struct ipc4_watchdog_timeout_notification *notif, uint32_t core_id, bool first_timeout)#

Helper to initialize watchdog timeout notification structure.

Parameters:

notif – Pointer to watchdog timeout notification structure to initialize.
core_id – DSP core ID that timed out.
first_timeout – True if this is the first timeout event.

void send_process_data_error_notif_msg(uint32_t resource_id, uint32_t error_code)#

Send process data error notification message to host.

Parameters:

resource_id – ID of module instance encountering error.
error_code – Module-specific error code.

bool send_copier_gateway_xrun_notif_msg(uint32_t pipeline_id, enum sof_ipc_stream_direction dir)#

Send Copier gateway xrun (underrun/overrun) notification to host.

Parameters:

pipeline_id – Target pipeline identifier.
dir – Stream direction (playback underrun or capture overrun).

Returns:

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)#

Send DMA gateway xrun notification to host.

Parameters:

resource_id – Gateway connector node ID.
dir – Stream direction.

Returns:

True if dispatched or suppressed by notification mask; false if notification pool was exhausted and caller should retry.

void send_mixer_underrun_notif_msg(uint32_t resource_id, uint32_t eos_flag, uint32_t data_mixed, uint32_t expected_data_mixed)#

Send mixer underrun notification message to host.

Parameters:

resource_id – Target mixer pipeline identifier.
eos_flag – End of stream flag.
data_mixed – Actual bytes mixed.
expected_data_mixed – Expected bytes mixed.

void ipc4_update_notification_mask(uint32_t ntfy_mask, uint32_t enabled_mask)#

Update host notification enable/disable bitmasks.

Parameters:

ntfy_mask – Bitmask of notifications to update.
enabled_mask – Target state (1 = enable, 0 = disable) for selected bits.

bool send_resource_notif(uint32_t resource_id, uint32_t event_type, uint32_t resource_type, void *data, uint32_t data_size)#

Send generic resource event notification.

Parameters:

resource_id – ID of originator resource.
event_type – Event type (enum sof_ipc4_resource_event_type).
resource_type – Resource category (enum sof_ipc4_resource_type).
data – Pointer to event payload.
data_size – Size of event payload in bytes.

Returns:

True if dispatched or suppressed by notification mask; false if notification pool was exhausted and caller should retry.

struct ipc4_fw_status_reg#

#include <src/include/ipc4/fw_reg.h>

Firmware Status Register (FSR) located at offset 0x0 in Mailbox Window 0.

Public Members

uint32_t state#: Current firmware execution / boot state.

uint32_t: Last module ID that updated FSR.

uint32_t running#: DSP core active execution flag (1 = running).

struct ipc4_fw_pwr_status#

#include <src/include/ipc4/fw_reg.h>

Firmware power and clock status register (offset 0x8 in Mailbox Window 0).

Public Members

uint32_t curr_astate#: Currently active A-state index.

uint32_t cached_imr_usage_status#: Cached IMR usage status from previous D0i3.

uint32_t curr_fstate#: Currently active F-state index.

uint32_t wake_tick_period#: Wake tick period configuration.

uint32_t active_pipelines_count#: Number of currently active pipelines.

uint32_t rsvd0#: Reserved padding bits.

struct ipc4_pipeline_registers#

#include <src/include/ipc4/fw_reg.h>

Pipeline DMA tracking registers in Mailbox Window 0.

Public Members

uint64_t stream_start_offset#

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_end_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. In number of bytes.

struct ipc4_peak_volume_regs#

#include <src/include/ipc4/fw_reg.h>

Peak volume and meter registers for low-latency host inspection.

Public Members

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.

struct ipc4_llp_reading#

#include <src/include/ipc4/fw_reg.h>

Link Linear Position (LLP) and wallclock snapshot.

Public Members

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.

struct ipc4_llp_reading_extended#

#include <src/include/ipc4/fw_reg.h>

Extended Link Linear Position reading with total processed data bytes.

Public Members

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.

struct ipc4_llp_reading_slot#

#include <src/include/ipc4/fw_reg.h>

Mailbox Window 0 reading slot for a single gateway.

Public Members

uint32_t node_id#: Audio gateway connector node ID.

struct ipc4_llp_reading reading#: Corresponding LLP position reading.

union ipc4_rom_info#

#include <src/include/ipc4/fw_reg.h>

ROM build, version, and load capability information.

Public Members

uint32_t fuse_values#: Hardware fuse configuration values.

uint32_t load_method#: Image loading method (DMA or memory).

uint32_t downlink_IPC_use_DMA#: 1 if downlink IPC uses DMA buffer.

uint32_t load_method_reserved#: Reserved load bits.

uint32_t implementation_revision_min#: Minor implementation revision.

uint32_t implementation_revision_maj#: Major implementation revision.

uint32_t implementation_version_min#: Minor implementation version.

uint32_t implementation_version_maj#: Major implementation version.

uint32_t reserved#: Reserved padding bits.

struct ipc4_rom_info bits#: Bitfield layout.

uint32_t rsvd1#: Reserved bits.

uint32_t type#: Platform architecture type identifier.

uint32_t rsvd2#: Reserved bits.

struct ipc4_rom_info platform#: Platform interpretation.

struct ipc4_fw_registers#

#include <src/include/ipc4/fw_reg.h>

Mailbox Window 0 firmware register layout exposed to host driver.

Public Members

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.

union ipc4_notification_header#

#include <src/include/ipc4/notification.h>

Standard 32-bit IPC4 notification primary header word.

Public Members

uint32_t dat#: Raw 32-bit register value.

uint32_t rsvd0#: Reserved bits.

uint32_t notif_type#: Notification type (enum sof_ipc4_notification_type).

uint32_t type#: Opcode: SOF_IPC4_GLB_NOTIFICATION (27).

uint32_t rsp#: Message direction: 0 for request/notification.

uint32_t msg_tgt#: Message target: 0 for global message.

uint32_t _reserved_0#: Reserved bit.

struct ipc4_notification_header r#: Bitfield layout.

struct ipc4_watchdog_timeout_notification#

#include <src/include/ipc4/notification.h>

Watchdog timeout notification structure (SOF_IPC4_WATCHDOG_TIMEOUT).

Reported by Base FW when a DSP core encounters a watchdog timeout interrupt.

Public Members

uint32_t dat#: Raw 32-bit register value.

uint32_t core_id#: ID of core that timed out.

uint32_t first_timeout#: 1 if initial timeout and crash dump was taken.

uint32_t rsvd#: Reserved padding.

uint32_t notif_type#: SOF_IPC4_WATCHDOG_TIMEOUT.

uint32_t type#: SOF_IPC4_GLB_NOTIFICATION.

uint32_t rsp#: 0 for notification.

uint32_t msg_tgt#: 0 for global message.

uint32_t _hw_rsvd_0#: Hardware reserved bit.

struct ipc4_watchdog_timeout_notification r#: Primary bitfield layout.

union ipc4_watchdog_timeout_notification primary#: Primary register value.

uint32_t rsvd1#: Reserved padding.

uint32_t _hw_rsvd_2#: Hardware reserved bits.

struct ipc4_watchdog_timeout_notification r: Extension bitfield layout.

union ipc4_watchdog_timeout_notification extension#: Extension register value.

struct ipc4_process_data_error_event_data#

#include <src/include/ipc4/notification.h>

Data payload for process data error event (SOF_IPC4_PROCESS_DATA_ERROR).

Public Members

uint32_t error_code#: Native error code returned by processing function.

struct ipc4_mixer_underrun_event_data#

#include <src/include/ipc4/notification.h>

Data payload for mixer underrun event (SOF_IPC4_MIXER_UNDERRUN_DETECTED).

Public Members

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.

union ipc4_resource_event_data#

#include <src/include/ipc4/notification.h>

Polymorphic payload for generic resource event notification.

Public Members

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.

struct ipc4_resource_event_data_notification#

#include <src/include/ipc4/notification.h>

Full resource event notification structure sent in Mailbox Window 0.

Public Members

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.

8. Telemetry, Probes & Logging#

Covers real-time host audio probe injection and extraction points, DMA probe streams, trace logging configuration, and mtrace memory buffers. Callers specify the DMA stream tag for injection probe points, whereas for extraction probes firmware automatically binds the probe point to the active extraction DMA channel.

group IPC4 Telemetry, Logging & Audio Probes

Host DMA trace logging control, audio probe injection and extraction data streams, and module-specific configuration payloads.

Enums

enum sof_ipc4_aec_config_params#

Parameter IDs for AEC module LargeConfigSet/Get.

Values:

enumerator IPC4_AEC_SET_EXT_FMT#: Configure extended reference and output formats.

enum ipc4_detect_test_module_config_params#

Parameter IDs for Keyword Detector test module LargeConfigSet/Get.

Values:

enumerator IPC4_DETECT_TEST_SET_MODEL_BLOB#: Send neural network keyword detection model binary blob via LargeConfigSet.

enumerator IPC4_DETECT_TEST_SET_CONFIG#: Configure Keyword Detector operational thresholds and parameters via LargeConfigSet.

enumerator IPC4_DETECT_TEST_GET_CONFIG#: Query current Keyword Detector operational configuration via LargeConfigGet.

enum ipc4_kpb_module_config_params#

Parameter IDs for KPB module LargeConfigSet/Get.

Values:

enumerator KP_BUF_CFG_FM_MODULE#: Configure module IDs that execute within Fast Mode (FM) draining tasks.

enumerator KP_BUF_CLIENT_MIC_SELECT#: Real-time sink microphone channel selector ID.

Functions

int ipc4_logging_enable_logs(bool first_block, bool last_block, uint32_t data_offset_or_size, const char *data)#

Configure and enable firmware logging requested by the host via IPC4.

Parameters:

first_block – True if this buffer is the first chunk of logging configuration.
last_block – True if this buffer is the final chunk of logging configuration.
data_offset_or_size – Byte offset or payload size of the configuration block.
data – Pointer to configuration payload buffer.

Returns:

0 on success, negative error code on failure.

int ipc4_logging_shutdown(void)#

Shutdown active IPC4 firmware logging and flush remaining trace buffers.

Returns:: 0 on success, negative error code on failure.

struct sof_ipc4_aec_config#

#include <src/include/ipc4/aec.h>

AEC module configuration payload.

Public Members

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.

struct ipc4_kpb_module_cfg#

#include <src/include/ipc4/kpb.h>

KPB module instance base configuration structure.

Public Members

struct ipc4_base_module_cfg base_cfg#: Standard base module configuration.

struct probe_dma#

#include <src/include/ipc3/probe.h>

Host DMA channel descriptor allocated for audio probes.

Probe DMA channel descriptor.

Public Members

uint32_t stream_tag#

Stream tag associated with this DMA channel.

Node ID / stream tag associated with this DMA.

uint32_t dma_buffer_size#

Size of host DMA buffer in bytes.

Size of buffer in bytes associated with this DMA.

union probe_point_id_t#

#include <src/include/ipc3/probe.h>

Packed identifier identifying target audio buffer for probe attachment.

Unique identifier for a probe attachment point.

Public Members

uint32_t full_id#

Packed buffer identifier.

Raw 32-bit probe point identifier.

uint32_t module_id#: Target module ID.

uint32_t instance_id#: Target module instance ID.

uint32_t type#: Probe point type (PROBE_TYPE_xxx).

uint32_t index#: Pin / queue index inside target module.

struct probe_point_id_t fields#: Bitfield access structure.

struct probe_point#

#include <src/include/ipc3/probe.h>

Probe tap point descriptor binding a pipeline buffer to a probe purpose.

Probe point attachment descriptor.

Public Members

probe_point_id_t buffer_id#

ID of pipeline buffer to which probe is attached.

ID of module buffer/pin to which probe is attached.

uint32_t purpose#

Probe role (PROBE_PURPOSE_*)

Extraction or injection (PROBE_PURPOSE_xxx).

uint32_t stream_tag#

Stream tag of DMA for injection; ignored on extraction request and populated on reply.

Stream tag of DMA providing injection data (for injection probes); ignored for extraction where firmware automatically binds the configured extraction DMA tag.

struct sof_ipc_probe_info_params#

#include <src/include/ipc3/probe.h>

Reply to INFO queries (SOF_IPC_PROBE_DMA_INFO, SOF_IPC_PROBE_POINT_INFO).

Discovery response listing active probe points or DMA channels.

Public Members

struct sof_ipc_reply rhdr#: Header.

uint32_t num_elems#

Count of elements in array.

Count of elements in payload array.

struct probe_dma probe_dma[0]#

DMA info.

Array of active DMA descriptors.

struct probe_point probe_point[0]#

Probe Point info.

Array of active probe point descriptors.

union sof_ipc_probe_info_params

union sof_ipc_probe_info_params

struct ipc4_probe_module_cfg#

#include <src/include/ipc4/probe.h>

Probe module configuration structure.

Public Members

struct ipc4_base_module_cfg base_cfg#: Base module configuration parameters.

struct probe_dma gtw_cfg#: Associated probe gateway DMA configuration.