IPC4 Message Envelope & Dispatch

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

Collaboration diagram for IPC4 Message Envelope & Dispatch:

Files
file	ams_helpers.h
	Audio Management System (AMS) message producer and consumer helpers.
file	error_status.h
	IPC4 status codes, error codes, and IXC return values.
file	handler.h
	IPC4 message handlers, userspace bridge, and compound message synchronization.
file	header.h
	IPC4 global message headers, envelope formats, and command types.

Data Structures
struct	ipc_cmd_hdr
	Generic message header. More...
struct	ipc4_message_request
	Standard 64-bit IPC4 message request envelope. More...
struct	ipc4_message_reply
	Standard 64-bit IPC4 message reply envelope. More...
struct	sof_ipc4_ctrl_value_chan
	Generic per-channel control value mapping. More...
struct	sof_ipc4_control_msg_payload
	IPC4 payload structure for ALSA kcontrol parameters. More...
struct	sof_ipc4_notify_module_data
	Asynchronous notification payload originating from a module instance. More...

Enumerations
enum	ipc4_status {   IPC4_SUCCESS = 0 , IPC4_ERROR_INVALID_PARAM = 1 , IPC4_UNKNOWN_MESSAGE_TYPE = 2 , IPC4_OUT_OF_MEMORY = 3 ,   IPC4_BUSY = 4 , IPC4_BAD_STATE = 5 , IPC4_FAILURE = 6 , IPC4_INVALID_REQUEST = 7 ,   IPC4_INVALID_RESOURCE_ID = 9 , IPC4_RESOURCE_ID_EXISTS = 10 , IPC4_INVALID_RESOURCE_STATE = 12 , IPC4_POWER_TRANSITION_FAILED = 13 ,   IPC4_INVALID_MANIFEST = 14 , IPC4_UNAVAILABLE = 15 , IPC4_LOAD_ADDRESS_OUT_OF_RANGE = 42 , IPC4_CSE_VALIDATION_FAILED = 44 ,   IPC4_MOD_MGMT_ERROR = 100 , IPC4_MOD_LOAD_CL_FAILED = 101 , IPC4_MOD_LOAD_INVALID_HASH = 102 , IPC4_MOD_INSTANCE_EXISTS = 103 ,   IPC4_MOD_NOT_INITIALIZED = 104 , IPC4_MOD_INVALID_ID = 110 , IPC4_MOD_INST_INVALID_ID = 111 , IPC4_QUEUE_INVALID_ID = 112 ,   IPC4_QUEUE_DST_INVALID_ID = 113 , IPC4_INVALID_CORE_ID = 116 , IPC4_PROBE_DMA_INJECTION_BUFFER_TOO_SMALL = 117 , IPC4_PROBE_DMA_EXTRACTION_BUFFER_TOO_SMALL = 118 ,   IPC4_INVALID_CONFIG_PARAM_ID = 120 , IPC4_INVALID_CONFIG_DATA_LEN = 121 , IPC4_INVALID_CONFIG_DATA_STRUCT = 122 , IPC4_GATEWAY_NOT_INITIALIZED = 140 ,   IPC4_GATEWAY_NOT_EXIST = 141 , IPC4_GATEWAY_STATE_NOT_SET = 142 , IPC4_GATEWAY_NOT_ALLOCATED = 143 , IPC4_SCLK_ALREADY_RUNNING = 150 ,   IPC4_MCLK_ALREADY_RUNNING = 151 , IPC4_NO_RUNNING_SCLK = 152 , IPC4_NO_RUNNING_MCLK = 153 , IPC4_PIPELINE_STATE_NOT_SET = 164 ,   IPC4_INVALID_CHAIN_STATE_TRANSITION = 3018 , IPC4_MAX_STATUS = ((1 << IPC4_IXC_STATUS_BITS) - 1) }
	IPC4 host-DSP status and error codes. More...
enum	ipc4_message_target { SOF_IPC4_MESSAGE_TARGET_FW_GEN_MSG = 0 , SOF_IPC4_MESSAGE_TARGET_MODULE_MSG = 1 }
	Message target routing selector (msg_tgt bitfield in Primary DWORD). More...
enum	ipc4_message_direction { SOF_IPC4_MESSAGE_DIR_MSG_REQUEST = 0 , SOF_IPC4_MESSAGE_DIR_MSG_REPLY = 1 }
	Message direction indicator (rsp bitfield in Primary DWORD). More...
enum	ipc4_message_type {   SOF_IPC4_GLB_BOOT_CONFIG = 0 , SOF_IPC4_GLB_ROM_CONTROL = 1 , SOF_IPC4_GLB_IPCGATEWAY_CMD = 2 , SOF_IPC4_GLB_PERF_MEASUREMENTS_CMD = 13 ,   SOF_IPC4_GLB_CHAIN_DMA = 14 , SOF_IPC4_GLB_LOAD_MULTIPLE_MODULES = 15 , SOF_IPC4_GLB_UNLOAD_MULTIPLE_MODULES = 16 , SOF_IPC4_GLB_CREATE_PIPELINE = 17 ,   SOF_IPC4_GLB_DELETE_PIPELINE = 18 , SOF_IPC4_GLB_SET_PIPELINE_STATE = 19 , SOF_IPC4_GLB_GET_PIPELINE_STATE = 20 , SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE = 21 ,   SOF_IPC4_GLB_SAVE_PIPELINE = 22 , SOF_IPC4_GLB_RESTORE_PIPELINE = 23 , SOF_IPC4_GLB_LOAD_LIBRARY = 24 , SOF_IPC4_GLB_LOAD_LIBRARY_PREPARE = 25 ,   SOF_IPC4_GLB_INTERNAL_MESSAGE = 26 , SOF_IPC4_GLB_NOTIFICATION = 27 , SOF_IPC4_GLB_ENTER_GDB = 31 , SOF_IPC4_GLB_MAX_IXC_MESSAGE_TYPE = 32 }
	Global IPC4 message types (5-bit opcode in Primary DWORD when msg_tgt == FW_GEN_MSG). More...

Functions
int	ipc4_user_process_module_message (struct ipc4_message_request *ipc4, struct ipc_msg *reply)
	Processes an IPC4 userspace module message.
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.
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.
int	ipc4_process_large_config_set (struct ipc4_message_request *ipc4)
	Process MOD_LARGE_CONFIG_SET in any execution context.
int	ipc4_user_process_glb_message (struct ipc4_message_request *ipc4, struct ipc_msg *reply)
	Processes an IPC4 userspace global firmware message.
int	ipc4_set_pipeline_state (struct ipc4_message_request *ipc4)
	Process SET_PIPELINE_STATE IPC4 message (prepare + trigger phases).
void	ipc_compound_msg_done (uint32_t msg_id, int error)
	Complete an IPC compound message transaction and signal waiting threads.
int	ipc4_comp_connect (struct ipc *ipc, const struct ipc4_module_bind_unbind *bu)
	Connect components together on a pipeline graph.
int	ipc4_comp_disconnect (struct ipc *ipc, const struct ipc4_module_bind_unbind *bu)
	Disconnect components in a pipeline graph.
void	ipc_compound_pre_start (int msg_id)
	Increment the IPC compound message pre-start barrier counter.
void	ipc_compound_post_start (uint32_t msg_id, int ret, bool delayed)
	Decrement the IPC compound message pre-start barrier counter on return.
int	ipc_wait_for_compound_msg (void)
	Wait for active IPC compound message operations to complete.
struct ipc4_message_reply	__attribute ((packed, aligned(4)))

Detailed Description

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

Enumeration Type Documentation

ipc4_message_direction

enum ipc4_message_direction

Message direction indicator (rsp bitfield in Primary DWORD).

Enumerator
SOF_IPC4_MESSAGE_DIR_MSG_REQUEST	Host-to-DSP command request, or unsolicited DSP-to-host notification.
SOF_IPC4_MESSAGE_DIR_MSG_REPLY	Command completion response / reply.

ipc4_message_target

enum ipc4_message_target

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

Enumerator
SOF_IPC4_MESSAGE_TARGET_FW_GEN_MSG	Global firmware message (dispatched to Base FW or global handler).
SOF_IPC4_MESSAGE_TARGET_MODULE_MSG	Module-specific message (routed directly to module instance by module_id).

ipc4_message_type

enum ipc4_message_type

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

Enumerator
SOF_IPC4_GLB_BOOT_CONFIG	Boot configuration handshake.
SOF_IPC4_GLB_ROM_CONTROL	ROM control command (directed to ADSP ROM bootloader).
SOF_IPC4_GLB_IPCGATEWAY_CMD	Execute IPC gateway command.
SOF_IPC4_GLB_PERF_MEASUREMENTS_CMD	Execute performance measurement command.
SOF_IPC4_GLB_CHAIN_DMA	DMA chain setup and configuration command.
SOF_IPC4_GLB_LOAD_MULTIPLE_MODULES	Load multiple module binary images.
SOF_IPC4_GLB_UNLOAD_MULTIPLE_MODULES	Unload multiple module binary images.
SOF_IPC4_GLB_CREATE_PIPELINE	Create pipeline with specified ID, priority, and memory attributes.
SOF_IPC4_GLB_DELETE_PIPELINE	Delete pipeline and associated module graph.
SOF_IPC4_GLB_SET_PIPELINE_STATE	Transition pipeline state (RESET, PAUSED, RUNNING, EOS).
SOF_IPC4_GLB_GET_PIPELINE_STATE	Retrieve current pipeline state.
SOF_IPC4_GLB_GET_PIPELINE_CONTEXT_SIZE	Query pipeline context memory size.
SOF_IPC4_GLB_SAVE_PIPELINE	Save pipeline context to host memory before power gating.
SOF_IPC4_GLB_RESTORE_PIPELINE	Restore pipeline context from host memory after wake.
SOF_IPC4_GLB_LOAD_LIBRARY	Load dynamic library via HD-Audio DMA.
SOF_IPC4_GLB_LOAD_LIBRARY_PREPARE	Prepare for dynamic library loading.
SOF_IPC4_GLB_INTERNAL_MESSAGE	Internal firmware control message.
SOF_IPC4_GLB_NOTIFICATION	Asynchronous notification event from DSP to host driver.
SOF_IPC4_GLB_ENTER_GDB	Enter GDB debugging stub to wait for host debugger in memory window.
SOF_IPC4_GLB_MAX_IXC_MESSAGE_TYPE	Maximum supported global message opcode count.

ipc4_status

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

Enumerator
IPC4_SUCCESS	The operation was successful.
IPC4_ERROR_INVALID_PARAM	Invalid parameter specified.
IPC4_UNKNOWN_MESSAGE_TYPE	Unknown message type specified.
IPC4_OUT_OF_MEMORY	Not enough space in the IPC reply buffer to complete the request.
IPC4_BUSY	The system or resource is busy.
IPC4_BAD_STATE	Replaced ADSP IPC PENDING (unused) - according to cAVS v0.5.
IPC4_FAILURE	Unknown error while processing the request.
IPC4_INVALID_REQUEST	Unsupported operation requested.
IPC4_INVALID_RESOURCE_ID	Specified resource not found.
IPC4_RESOURCE_ID_EXISTS	A resource's ID requested to be created is already assigned.
IPC4_INVALID_RESOURCE_STATE	Required resource is in invalid state.
IPC4_POWER_TRANSITION_FAILED	Requested power transition failed to complete.
IPC4_INVALID_MANIFEST	Manifest of the library being loaded is invalid.
IPC4_UNAVAILABLE	Requested service or data is unavailable on the target platform.
IPC4_LOAD_ADDRESS_OUT_OF_RANGE	Library target address is out of storage memory range.
IPC4_CSE_VALIDATION_FAILED	Image verification by CSE failed.
IPC4_MOD_MGMT_ERROR	General module management error.
IPC4_MOD_LOAD_CL_FAILED	Module loading failed.
IPC4_MOD_LOAD_INVALID_HASH	Integrity check of the loaded module content failed.
IPC4_MOD_INSTANCE_EXISTS	Attempt to unload code of the module in use.
IPC4_MOD_NOT_INITIALIZED	Other failure of module instance initialization request.
IPC4_MOD_INVALID_ID	Invalid (out of range) module ID provided.
IPC4_MOD_INST_INVALID_ID	Invalid module instance ID provided.
IPC4_QUEUE_INVALID_ID	Invalid queue (pin) ID provided.
IPC4_QUEUE_DST_INVALID_ID	Invalid destination queue (pin) ID provided.
IPC4_INVALID_CORE_ID	Invalid target code ID provided.
IPC4_PROBE_DMA_INJECTION_BUFFER_TOO_SMALL	Injection DMA buffer is too small for probing the input pin.
IPC4_PROBE_DMA_EXTRACTION_BUFFER_TOO_SMALL	Extraction DMA buffer is too small for probing the output pin.
IPC4_INVALID_CONFIG_PARAM_ID	Invalid ID of configuration item provided in TLV list.
IPC4_INVALID_CONFIG_DATA_LEN	Invalid length of configuration item provided in TLV list.
IPC4_INVALID_CONFIG_DATA_STRUCT	Invalid structure of configuration item provided.
IPC4_GATEWAY_NOT_INITIALIZED	Initialization of DMA Gateway failed.
IPC4_GATEWAY_NOT_EXIST	Invalid ID of gateway provided.
IPC4_GATEWAY_STATE_NOT_SET	Setting state of DMA Gateway failed.
IPC4_GATEWAY_NOT_ALLOCATED	DMA_CONTROL message targeting gateway not allocated yet.
IPC4_SCLK_ALREADY_RUNNING	Attempt to configure SCLK while I2S port is running.
IPC4_MCLK_ALREADY_RUNNING	Attempt to configure MCLK while I2S port is running.
IPC4_NO_RUNNING_SCLK	Attempt to stop SCLK that is not running.
IPC4_NO_RUNNING_MCLK	Attempt to stop MCLK that is not running.
IPC4_PIPELINE_STATE_NOT_SET	Reverted for ULP purposes.
IPC4_INVALID_CHAIN_STATE_TRANSITION	HDA chained gateways wrong state transition.
IPC4_MAX_STATUS

Function Documentation

__attribute()

struct sof_ipc4_notify_module_data __attribute

(

(packed, aligned(4))

)

ipc4_comp_connect()

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

Connect components together on a pipeline graph.

Parameters

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

Returns

IPC4_SUCCESS on success, or IPC4 error code otherwise.

ipc4_comp_disconnect()

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

Disconnect components in a pipeline graph.

Parameters

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

Returns

IPC4_SUCCESS on success, or IPC4 error code otherwise.

ipc4_process_large_config_set()

int ipc4_process_large_config_set

(

struct ipc4_message_request *

ipc4

)

Process MOD_LARGE_CONFIG_SET in any execution context.

Parameters

[in]

ipc4

IPC4 message request structure containing block parameters and offset.

Returns

IPC4 status code (IPC4_SUCCESS on success).

ipc4_process_module_config()

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

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

Returns

IPC4 status code (IPC4_SUCCESS on success).

ipc4_set_pipeline_state()

int ipc4_set_pipeline_state

(

struct ipc4_message_request *

ipc4

)

Process SET_PIPELINE_STATE IPC4 message (prepare + trigger phases).

Parameters

[in]

ipc4

IPC4 message request structure containing target state and pipeline ID.

Returns

0 on success, or IPC4 error code on failure.

ipc4_user_module_load()

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

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

Returns

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

ipc4_user_process_glb_message()

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

Processes an IPC4 userspace global firmware message.

Parameters

[in]	ipc4	IPC4 message request structure.
[in,out]	reply	IPC message reply structure.

Returns

IPC4_SUCCESS on success, error code otherwise.

ipc4_user_process_module_message()

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

Processes an IPC4 userspace module message.

Parameters

[in]	ipc4	IPC4 message request structure.
[in,out]	reply	IPC message reply structure populated upon return.

Returns

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

ipc_compound_msg_done()

void ipc_compound_msg_done	(	uint32_t	msg_id,
		int	error
	)

Complete an IPC compound message transaction and signal waiting threads.

Parameters

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

ipc_compound_post_start()

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

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

ipc_compound_pre_start()

void ipc_compound_pre_start

(

int

msg_id

)

Increment the IPC compound message pre-start barrier counter.

Parameters

[in]

msg_id

IPC message ID.

ipc_wait_for_compound_msg()

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.