Skip to content

Commit 7dcdd8d

Browse files
lrgirdwolrgirdwo
committed
doc: api: ipc4: document protocol architecture and integrate all 8 IPC4 subgroups
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
1 parent 69f37d4 commit 7dcdd8d

1 file changed

Lines changed: 248 additions & 4 deletions

File tree

‎api/ipc4.rst‎

Lines changed: 248 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,253 @@
33
IPC4 Host-DSP Protocol API
44
##########################
55

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

10-
.. doxygengroup:: ipc4_api
13+
Architecture & Protocol Overview
14+
********************************
15+
16+
The IPC4 protocol is built upon hardware doorbells, shared SRAM mailbox windows, and a uniform
17+
64-bit message envelope.
18+
19+
1. Shared Memory Mailbox Windows
20+
================================
21+
22+
Host and DSP exchange control messages and telemetry through memory-mapped SRAM windows:
23+
24+
* **Mailbox Window 0 (Control & Status)**:
25+
26+
* **Offset 0x0000 - 0x0FFF (Firmware Status & Telemetry Registers)**:
27+
Exposes the 32-bit Firmware Status Register (``fsr``), Last Error Code (``lec``),
28+
Power Status (``fps``), ROM information, pipeline LPIB positions, real-time PeakVol meters,
29+
and Link Linear Position (LLP) wallclock readings (:c:struct:`ipc4_fw_registers`).
30+
* **Offset 0x1000 - 0x1FFF (Downlink Mailbox)**:
31+
Host writes request payloads (e.g. module initialization blobs, pipeline configs).
32+
* **Offset 0x2000 - 0x2FFF (Uplink Mailbox)**:
33+
DSP writes reply payloads and unsolicited asynchronous notification structures.
34+
35+
* **Mailbox Window 1 (Probes & Bulk Data)**:
36+
Dedicated memory window for audio extraction/injection probes, trace DMA streams, and
37+
bulk configuration buffers.
38+
39+
2. 64-bit Message Envelope
40+
==========================
41+
42+
Every IPC4 communication consists of two 32-bit hardware registers: the **Primary Register**
43+
and the **Extension Register**.
44+
45+
.. code-block:: text
46+
47+
+-----------------------------------------------------------------------------------------------+
48+
| IPC4 Primary Header (DWORD 0) |
49+
+---------------+---------+--------+--------------------+---------------------------------------+
50+
| Bit 31 (RSVD) | 30 (TGT)| 29(RSP)| Bits 28:24 (TYPE) | Bits 23:0 (Type-Specific Parameters) |
51+
+---------------+---------+--------+--------------------+---------------------------------------+
52+
| Reserved (0) | 0=GLB | 0=REQ | Opcode (0..31) | Module Instance / Pipeline ID / |
53+
| | 1=MOD | 1=RSP | | Status Code (in replies) |
54+
+---------------+---------+--------+--------------------+---------------------------------------+
55+
56+
+-----------------------------------------------------------------------------------------------+
57+
| IPC4 Extension Header (DWORD 1) |
58+
+---------------------------------------+---------------+---------------------------------------+
59+
| Bits 31:30 (Reserved) | Bit 29..24 | Bits 23:0 (Extension-Specific Data) |
60+
+---------------------------------------+---------------+---------------------------------------+
61+
| Reserved bits | Large Config | Param ID / Data Offset & Size / |
62+
| | Flags (FB/LB) | Pipeline Context Pages |
63+
+---------------------------------------+---------------+---------------------------------------+
64+
65+
* **Target Bit (``msg_tgt``)**:
66+
67+
* ``0`` (**Global Message**): Targets firmware core services (pipelines, base firmware, gateway control).
68+
* ``1`` (**Module Message**): Addressed to a specific module instance identified by its 16-bit Module ID
69+
and 8-bit Instance ID.
70+
71+
* **Response Bit (``rsp``)**:
72+
73+
* ``0``: Request from sender (or unsolicited DSP-to-host notification).
74+
* ``1``: Reply to a previous request, returning status code in bits 23:0 of Primary.
75+
76+
3. Doorbell Handshake Flow
77+
==========================
78+
79+
Command exchange follows a strict, non-reentrant hardware doorbell handshake:
80+
81+
.. code-block:: text
82+
83+
Host Driver DSP Firmware
84+
| |
85+
| 1. Write payload to Downlink Mailbox (Window 0) |
86+
| 2. Write Primary & Extension registers |
87+
| 3. Set Host-to-DSP Doorbell (BUSY = 1) |
88+
|------------------------------------------------------------->| (Interrupt)
89+
| |
90+
| | 4. Read Primary & Ext
91+
| | 5. Dispatch command
92+
| | 6. Write reply payload
93+
| | to Uplink Mailbox
94+
| | 7. Write status to Primary
95+
| | 8. Clear DSP BUSY &
96+
| (Interrupt) | Set DSP-to-Host DONE
97+
|<-------------------------------------------------------------|
98+
| |
99+
| 9. Read reply status and Uplink payload |
100+
| 10. Clear DONE bit (handshake complete) |
101+
| |
102+
103+
4. Audio Pipeline Construction & State Machine
104+
==============================================
105+
106+
Audio processing graphs are built and controlled dynamically by the host driver:
107+
108+
.. code-block:: text
109+
110+
Host Driver DSP Firmware
111+
| |
112+
| SOF_IPC4_GLB_CREATE_PIPELINE (ppl_id, priority, memory) |
113+
|------------------------------------------------------------->| Create pipeline container
114+
|<-------------------------------------------------------------| Reply (STATUS_SUCCESS)
115+
| |
116+
| SOF_IPC4_MOD_INIT_INSTANCE (mod_id, inst_id, base_cfg) |
117+
|------------------------------------------------------------->| Instantiate module in pipeline
118+
|<-------------------------------------------------------------| Reply (STATUS_SUCCESS)
119+
| |
120+
| SOF_IPC4_MOD_BIND (src_mod, src_pin -> dst_mod, dst_pin) |
121+
|------------------------------------------------------------->| Connect inter-module queue
122+
|<-------------------------------------------------------------| Reply (STATUS_SUCCESS)
123+
| |
124+
| SOF_IPC4_GLB_SET_PIPELINE_STATE (PAUSED) |
125+
|------------------------------------------------------------->| Allocate buffers & gateways
126+
|<-------------------------------------------------------------| Reply (STATUS_SUCCESS)
127+
| |
128+
| SOF_IPC4_GLB_SET_PIPELINE_STATE (RUNNING) |
129+
|------------------------------------------------------------->| Start processing tasks (LL/DP)
130+
|<-------------------------------------------------------------| Reply (STATUS_SUCCESS)
131+
| |
132+
133+
State transitions adhere to strict ordering:
134+
135+
* **Forward Transitions** (RESET -> PAUSED -> RUNNING):
136+
Processed from source modules to sink modules.
137+
* **Reverse Transitions** (RUNNING -> PAUSED -> RESET):
138+
Processed in **strict reverse order** (sink modules to source modules) to guarantee clean drain without FIFO underflow.
139+
140+
5. Large Configuration Multi-Chunk Protocol
141+
===========================================
142+
143+
When parameter data exceeds the mailbox capacity (4KB), the IPC4 protocol utilizes fragmented
144+
multi-chunk transactions:
145+
146+
.. code-block:: text
147+
148+
Host Driver DSP Firmware
149+
| |
150+
| LARGE_CONFIG_SET (Chunk 0, first_block=1, last_block=0) |
151+
| [Payload: bytes 0 .. 4095] |
152+
|------------------------------------------------------------->| Accumulate into staging buffer
153+
|<-------------------------------------------------------------| Reply (STATUS_SUCCESS)
154+
| |
155+
| LARGE_CONFIG_SET (Chunk 1, first_block=0, last_block=0) |
156+
| [Payload: bytes 4096 .. 8191] |
157+
|------------------------------------------------------------->| Accumulate
158+
|<-------------------------------------------------------------| Reply (STATUS_SUCCESS)
159+
| |
160+
| LARGE_CONFIG_SET (Chunk 2, first_block=0, last_block=1) |
161+
| [Payload: final bytes] |
162+
|------------------------------------------------------------->| Commit full parameter blob
163+
|<-------------------------------------------------------------| Reply (STATUS_SUCCESS)
164+
| |
165+
166+
Protocol API Subsystems
167+
***********************
168+
169+
The IPC4 API reference is organized into eight specialized functional subsystems:
170+
171+
1. Message Envelope & Protocol Handlers
172+
=======================================
173+
174+
Defines the fundamental 64-bit message envelope, primary and extension register formats,
175+
global opcodes, status codes, and host-DSP message routing bridges.
176+
177+
.. doxygengroup:: ipc4_envelope_api
178+
:project: SOF Project
179+
180+
2. Audio Formats, Pins & Stream Descriptors
181+
===========================================
182+
183+
Defines the binary serialization format for multi-channel audio streams, PCM sample
184+
representations, container bit depths, channel maps, and dynamic input/output pin formats.
185+
186+
.. note::
187+
Sample type enumeration entries (such as ``IPC4_TYPE_MSB_INTEGER`` vs ``IPC4_TYPE_LSB_INTEGER``)
188+
describe valid audio bit alignment within the sample container memory word (e.g. S24 valid bits
189+
aligned at bits ``[31:8]`` vs ``[23:0]``) rather than byte endianness, remaining little-endian.
190+
191+
.. doxygengroup:: ipc4_format_api
192+
:project: SOF Project
193+
194+
3. Dynamic Modules & Configuration Handshake
195+
============================================
196+
197+
Governs audio module instantiation, deletion, dynamic binding/unbinding of module pins,
198+
D0ix power state switching, and small/large parameter configuration transactions.
199+
Target DSP core affinity (``core_id``) is platform-dependent, ranging from 0 up to
200+
``CONFIG_CORE_COUNT - 1``.
201+
202+
.. doxygengroup:: ipc4_module_api
203+
:project: SOF Project
204+
205+
4. Audio Pipelines & Scheduling Priorities
206+
==========================================
207+
208+
Covers audio pipeline graph allocation, scheduling domain priorities (Low Latency vs Data
209+
Processing), pipeline state transitions (Reset, Paused, Running), memory context queries,
210+
and direct DMA chaining.
211+
212+
.. doxygengroup:: ipc4_pipeline_api
213+
:project: SOF Project
214+
215+
5. Base Firmware & ADSP Configuration
216+
=====================================
217+
218+
Provides access to Core 0 Base Firmware system services, ADSP hardware properties,
219+
frequency steps, physical SRAM page allocation tables, power manager A-states, and system time.
220+
221+
.. doxygengroup:: ipc4_base_fw_api
222+
:project: SOF Project
223+
224+
6. Hardware Gateways & Peripherals
225+
==================================
226+
227+
Encodes hardware connector addressing (node IDs) and configuration blobs for Intel High
228+
Definition Audio (HDA), Audio Hub Link (ALH / SoundWire) aggregation, Digital Microphones (DMIC),
229+
and Synchronous Serial Ports (SSP / I2S).
230+
231+
.. doxygengroup:: ipc4_gateway_api
232+
:project: SOF Project
233+
234+
7. Asynchronous Notifications & Mailbox Registers
235+
=================================================
236+
237+
Details unsolicited DSP-to-host event notifications (underrun/overrun alarms, budget violations,
238+
voice activity wake words), and Mailbox Window 0 telemetry register layouts. Unsolicited notifications
239+
use opcode ``SOF_IPC4_GLB_NOTIFICATION`` (opcode 27 / 0x1B). Notification dispatch functions return
240+
``true`` when the notification is either queued or suppressed by the notification mask, and ``false``
241+
if the notification pool is temporarily exhausted, indicating that the caller should retry.
242+
243+
.. doxygengroup:: ipc4_notification_api
244+
:project: SOF Project
245+
246+
8. Telemetry, Probes & Logging
247+
==============================
248+
249+
Covers real-time host audio probe injection and extraction points, DMA probe streams,
250+
trace logging configuration, and mtrace memory buffers. Callers specify the DMA stream tag
251+
for injection probe points, whereas for extraction probes firmware automatically binds the probe
252+
point to the active extraction DMA channel.
253+
254+
.. doxygengroup:: ipc4_telemetry_probe_api
11255
:project: SOF Project

0 commit comments

Comments
 (0)