SOF uAPI specification
More...
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.
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The header contains size of the IPC message and a 32bit Command identifier with following structure:
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):
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 (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
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:
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 (G=REPLY, C=0) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Error |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- See also
- sof_ipc_reply
IPC ABI version compatibility rules
- 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.
◆ SOF_CMD_TYPE
| #define SOF_CMD_TYPE |
( |
| x | ) |
|
Value:
#define SOF_CMD_TYPE_SHIFT
Shift-left bits to extract the command type.
Definition header.h:185
◆ SOF_CMD_TYPE_MASK
◆ SOF_CMD_TYPE_SHIFT
| #define SOF_CMD_TYPE_SHIFT 16 |
Shift-left bits to extract the command type.
◆ SOF_GLB_TYPE
| #define SOF_GLB_TYPE |
( |
| x | ) |
|
Value:
#define SOF_GLB_TYPE_SHIFT
Shift-left bits to extract the global cmd type.
Definition header.h:174
◆ SOF_GLB_TYPE_MASK
◆ SOF_GLB_TYPE_SHIFT
| #define SOF_GLB_TYPE_SHIFT 28 |
Shift-left bits to extract the global cmd type.
◆ SOF_IPC_COMP_GET_DATA
◆ SOF_IPC_COMP_GET_VALUE
◆ SOF_IPC_COMP_NOTIFICATION
◆ SOF_IPC_COMP_SET_DATA
◆ SOF_IPC_COMP_SET_VALUE
◆ SOF_IPC_DAI_CONFIG
◆ SOF_IPC_DAI_LOOPBACK
◆ SOF_IPC_DEBUG_MEM_USAGE
◆ SOF_IPC_FW_READY
◆ SOF_IPC_GLB_COMP_MSG
◆ SOF_IPC_GLB_COMPOUND
◆ SOF_IPC_GLB_DAI_MSG
◆ SOF_IPC_GLB_DEBUG
◆ SOF_IPC_GLB_GDB_DEBUG
◆ SOF_IPC_GLB_PM_MSG
◆ SOF_IPC_GLB_PROBE
◆ SOF_IPC_GLB_REPLY
◆ SOF_IPC_GLB_STREAM_MSG
◆ SOF_IPC_GLB_TEST
◆ SOF_IPC_GLB_TPLG_MSG
◆ SOF_IPC_GLB_TRACE_MSG
◆ SOF_IPC_MESSAGE_ID
| #define SOF_IPC_MESSAGE_ID |
( |
| x | ) |
|
Value:
Get message component id.
◆ SOF_IPC_MSG_MAX_SIZE
| #define SOF_IPC_MSG_MAX_SIZE 384 |
Maximum message size for mailbox Tx/Rx.
◆ SOF_IPC_PM_CLK_GET
◆ SOF_IPC_PM_CLK_REQ
◆ SOF_IPC_PM_CLK_SET
◆ SOF_IPC_PM_CORE_ENABLE
◆ SOF_IPC_PM_CTX_RESTORE
◆ SOF_IPC_PM_CTX_SAVE
◆ SOF_IPC_PM_CTX_SIZE
◆ SOF_IPC_PM_GATE
◆ SOF_IPC_PROBE_DEINIT
◆ SOF_IPC_PROBE_DMA_ADD
◆ SOF_IPC_PROBE_DMA_INFO
◆ SOF_IPC_PROBE_DMA_REMOVE
◆ SOF_IPC_PROBE_INIT
◆ SOF_IPC_PROBE_POINT_ADD
◆ SOF_IPC_PROBE_POINT_INFO
◆ SOF_IPC_PROBE_POINT_REMOVE
◆ SOF_IPC_STREAM_PCM_FREE
◆ SOF_IPC_STREAM_PCM_PARAMS
◆ SOF_IPC_STREAM_PCM_PARAMS_REPLY
◆ SOF_IPC_STREAM_POSITION
◆ SOF_IPC_STREAM_TRIG_DRAIN
◆ SOF_IPC_STREAM_TRIG_PAUSE
◆ SOF_IPC_STREAM_TRIG_RELEASE
◆ SOF_IPC_STREAM_TRIG_START
◆ SOF_IPC_STREAM_TRIG_STOP
◆ SOF_IPC_STREAM_TRIG_XRUN
◆ SOF_IPC_STREAM_VORBIS_FREE
◆ SOF_IPC_STREAM_VORBIS_PARAMS
◆ SOF_IPC_TEST_IPC_FLOOD
◆ SOF_IPC_TPLG_BUFFER_FREE
◆ SOF_IPC_TPLG_BUFFER_NEW
◆ SOF_IPC_TPLG_COMP_CONNECT
◆ SOF_IPC_TPLG_COMP_FREE
◆ SOF_IPC_TPLG_COMP_NEW
◆ SOF_IPC_TPLG_PIPE_COMPLETE
◆ SOF_IPC_TPLG_PIPE_CONNECT
◆ SOF_IPC_TPLG_PIPE_FREE
◆ SOF_IPC_TPLG_PIPE_NEW
◆ SOF_IPC_TRACE_DMA_FREE
◆ SOF_IPC_TRACE_DMA_PARAMS
◆ SOF_IPC_TRACE_DMA_PARAMS_EXT
◆ SOF_IPC_TRACE_DMA_POSITION
◆ SOF_IPC_TRACE_FILTER_UPDATE