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.

 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                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Reply Messages

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:

 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                                                         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
IPC ABI version compatibility rules

See also

sof_ipc_reply

  1. FW binaries will only support one MAJOR ABI version which is advertised to host at FW boot.

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

  3. 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: DAI messages

SOF_IPC_DAI_CONFIG
SOF_IPC_DAI_LOOPBACK

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

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.

Public Members

uint32_t size

size of structure

uint32_t cmd

SOF_IPC_GLB_ + cmd.

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.

Public Members

struct sof_ipc_cmd_hdr hdr
int32_t error

negative error numbers

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_dsp_oops_arch_hdr
#include <header.h>

OOPS header architecture specific data.

Public Members

uint32_t arch
uint32_t totalsize
struct sof_ipc_dsp_oops_plat_hdr
#include <header.h>

OOPS header platform specific data.

Public Members

uint32_t configidhi
uint32_t configidlo
uint32_t numaregs
uint32_t stackoffset
uint32_t stackptr