uAPI¶
- group sof_uapi
SOF uAPI specification.
Overview
The SOF Audio DSP firmware defines an Inter-Process Communication (IPC) interface to facilitate communication with the host.
The SOF IPC is bi-directional. Messages can be initiated by the host and acknowledged by the DSP. Similarly, they can be initiated by the DSP and acknowledged by the host.
IPC messages are divided into several groups: global, topology, power management, component, stream, DAI, trace, and a separate “firmware ready” message. Multiple messages can also be grouped into a message that belong to a compound group. Most messages are sent by the host to the DSP; only the following messages are sent by the DSP to the host:
firmware ready: sent only once during initialization
trace: optional, contains firmware trace data
position update: only used if position data cannot be transferred in a memory window or if forced by the kernel configuration
Message encoding
All multi-byte protocol fields are encoded with little-endian byte-order.
Message structure
IPC messages have a fixed header and variable length payload.
The header contains size of the IPC message and a 32bit Command identifier with following structure:0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Size | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
0xGCCCNNNN is little-endian value where
G is the Global Type (4 bits)
C is the Command Type (12 bits)
N is the ID Number (16 bits) - monotonic and overflows
The Global and Command Types together define the structure of the payload. E.g. for topology IPC message COMP_NEW structure is (ABI 3.17.0 example):
Reply Messages0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Size (Total size including Extended Data) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command (G=TPLG_MSG, C=COMP_NEW) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Component ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Pipeline ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Core | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Extended Data size | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type specific payload, size varies based on Component ID. | | Ends at: Total size - Extended Data size | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | extended data, including e.g. UUID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
See also
sof_ipc_comp
Reply messages are defined per Command. The response IPC messages have a common layout, but some Commands have extended fields defined. The common format is:
IPC ABI version compatibility rules0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Size | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command (G=REPLY, C=0) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Error | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
See also
FW binaries will only support one MAJOR ABI version which is advertised to host at FW boot.
Host drivers will support the current and older MAJOR ABI versions of the IPC ABI (up to a certain age to be determined by market information).
MINOR and PATCH ABI versions can differ between host and FW but must be backwards compatible on both host and FW.
IPC messages sizes can be different for sender and receiver if MINOR or PATCH ABI versions differ as new fields can be added to the end of messages.
i) SenderVersion > ReceiverVersion: Receiver only copies its own ABI structure size.
ii) ReceiverVersion > SenderVersion: Receiver copies its own ABI size and zero pads new fields. i.e. new structure fields must be non zero to be activated.
Guidelines for extending ABI compatible messages :-
i) Use reserved fields.
ii) Grow structure at the end.
iii) Iff (i) and (ii) are not possible then MAJOR ABI is bumped.
Global Message - Generic
-
SOF_GLB_TYPE_SHIFT¶
Shift-left bits to extract the global cmd type.
-
SOF_GLB_TYPE_MASK¶
-
SOF_GLB_TYPE(x)¶
Command Message - Generic
-
SOF_CMD_TYPE_SHIFT¶
Shift-left bits to extract the command type.
-
SOF_CMD_TYPE_MASK¶
-
SOF_CMD_TYPE(x)¶
Global Message Types
-
SOF_IPC_GLB_REPLY¶
-
SOF_IPC_GLB_COMPOUND¶
-
SOF_IPC_GLB_TPLG_MSG¶
-
SOF_IPC_GLB_PM_MSG¶
-
SOF_IPC_GLB_COMP_MSG¶
-
SOF_IPC_GLB_STREAM_MSG¶
-
SOF_IPC_FW_READY¶
-
SOF_IPC_GLB_DAI_MSG¶
-
SOF_IPC_GLB_TRACE_MSG¶
-
SOF_IPC_GLB_GDB_DEBUG¶
-
SOF_IPC_GLB_TEST¶
-
SOF_IPC_GLB_PROBE¶
-
SOF_IPC_GLB_DEBUG¶
DSP Command: Topology
-
SOF_IPC_TPLG_COMP_NEW¶
-
SOF_IPC_TPLG_COMP_FREE¶
-
SOF_IPC_TPLG_COMP_CONNECT¶
-
SOF_IPC_TPLG_PIPE_NEW¶
-
SOF_IPC_TPLG_PIPE_FREE¶
-
SOF_IPC_TPLG_PIPE_CONNECT¶
-
SOF_IPC_TPLG_PIPE_COMPLETE¶
-
SOF_IPC_TPLG_BUFFER_NEW¶
-
SOF_IPC_TPLG_BUFFER_FREE¶
DSP Command: PM
-
SOF_IPC_PM_CTX_SAVE¶
-
SOF_IPC_PM_CTX_RESTORE¶
-
SOF_IPC_PM_CTX_SIZE¶
-
SOF_IPC_PM_CLK_SET¶
-
SOF_IPC_PM_CLK_GET¶
-
SOF_IPC_PM_CLK_REQ¶
-
SOF_IPC_PM_CORE_ENABLE¶
-
SOF_IPC_PM_GATE¶
DSP Command: Component runtime config - multiple different types
-
SOF_IPC_COMP_SET_VALUE¶
-
SOF_IPC_COMP_GET_VALUE¶
-
SOF_IPC_COMP_SET_DATA¶
-
SOF_IPC_COMP_GET_DATA¶
-
SOF_IPC_COMP_NOTIFICATION¶
DSP Command: Stream
-
SOF_IPC_STREAM_PCM_PARAMS¶
-
SOF_IPC_STREAM_PCM_PARAMS_REPLY¶
-
SOF_IPC_STREAM_PCM_FREE¶
-
SOF_IPC_STREAM_TRIG_START¶
-
SOF_IPC_STREAM_TRIG_STOP¶
-
SOF_IPC_STREAM_TRIG_PAUSE¶
-
SOF_IPC_STREAM_TRIG_RELEASE¶
-
SOF_IPC_STREAM_TRIG_DRAIN¶
-
SOF_IPC_STREAM_TRIG_XRUN¶
-
SOF_IPC_STREAM_POSITION¶
-
SOF_IPC_STREAM_VORBIS_PARAMS¶
-
SOF_IPC_STREAM_VORBIS_FREE¶
DSP Command: Trace and debug
-
SOF_IPC_TRACE_DMA_PARAMS¶
-
SOF_IPC_TRACE_DMA_POSITION¶
-
SOF_IPC_TRACE_DMA_PARAMS_EXT¶
-
SOF_IPC_TRACE_FILTER_UPDATE¶
ABI3.17.
-
SOF_IPC_TRACE_DMA_FREE¶
ABI3.20.
DSP Command: Probes
-
SOF_IPC_PROBE_INIT¶
-
SOF_IPC_PROBE_DEINIT¶
-
SOF_IPC_PROBE_DMA_ADD¶
-
SOF_IPC_PROBE_DMA_INFO¶
-
SOF_IPC_PROBE_DMA_REMOVE¶
-
SOF_IPC_PROBE_POINT_ADD¶
-
SOF_IPC_PROBE_POINT_INFO¶
-
SOF_IPC_PROBE_POINT_REMOVE¶
DSP Command: Debug - additional services
-
SOF_IPC_DEBUG_MEM_USAGE¶
DSP Command: Test - Debug build only
-
SOF_IPC_TEST_IPC_FLOOD¶
IPC Message Definitions
-
SOF_IPC_MESSAGE_ID(x)¶
Get message component id.
-
SOF_IPC_MSG_MAX_SIZE¶
Maximum message size for mailbox Tx/Rx.
-
struct sof_ipc_hdr¶
- #include <header.h>
Structure Header - Header for all IPC structures except command structs.
The size can be greater than the structure size and that means there is extended bespoke data beyond the end of the structure including variable arrays.
Public Members
-
uint32_t size¶
size of structure
-
uint32_t size¶
-
struct sof_ipc_cmd_hdr¶
- #include <header.h>
Command Header - Header for all IPC commands.
Identifies IPC message. The size can be greater than the structure size and that means there is extended bespoke data beyond the end of the structure including variable arrays.
-
struct sof_ipc_reply¶
- #include <header.h>
Generic reply message.
Some commands override this with their own reply types that must include this at start.
-
struct sof_ipc_compound_hdr¶
- #include <header.h>
Compound commands - SOF_IPC_GLB_COMPOUND.
Compound commands are sent to the DSP as a single IPC operation. The commands are split into blocks and each block has a header. This header identifies the command type and the number of commands before the next header.
Public Members
-
struct sof_ipc_cmd_hdr hdr¶
-
uint32_t count¶
count of 0 means end of compound sequence
-
struct sof_ipc_cmd_hdr hdr¶
-
struct sof_ipc_dsp_oops_arch_hdr¶
- #include <header.h>
OOPS header architecture specific data.
-
struct sof_ipc_dsp_oops_plat_hdr¶
- #include <header.h>
OOPS header platform specific data.