1 =========================
2 Audio Stream in SoundWire
3 =========================
4
5 An audio stream is a logical or virtual connec
6
7 (1) System memory buffer(s) and Codec(s)
8
9 (2) DSP memory buffer(s) and Codec(s)
10
11 (3) FIFO(s) and Codec(s)
12
13 (4) Codec(s) and Codec(s)
14
15 which is typically driven by a DMA(s) channel
16 audio stream contains one or more channels of
17 stream must have same sample rate and same sam
18
19 Assume a stream with two channels (Left & Righ
20 interface. Below are some ways a stream can be
21
22 Stream Sample in memory (System memory, DSP me
23
24 -------------------------
25 | L | R | L | R | L | R |
26 -------------------------
27
28 Example 1: Stereo Stream with L and R channels
29 Slave. Both Master and Slave is using single p
30
31 +---------------+ C
32 | Master +---------------------
33 | Interface |
34 | |
35 | |
36 | L + R +---------------------
37 | (Data) | Data Direction
38 +---------------+ +------------------
39
40
41 Example 2: Stereo Stream with L and R channels
42 Master. Both Master and Slave is using single
43
44
45 +---------------+ C
46 | Master +---------------------
47 | Interface |
48 | |
49 | |
50 | L + R +---------------------
51 | (Data) | Data Direction
52 +---------------+ <------------------
53
54
55 Example 3: Stereo Stream with L and R channels
56 of the L and R channel is received by two diff
57 Slaves are using single port. ::
58
59 +---------------+ C
60 | Master +---------+-----------
61 | Interface | |
62 | | |
63 | | |
64 | L + R +---+-----------------
65 | (Data) | | | Data Di
66 +---------------+ | | +-------
67 | |
68 | |
69 | |
70 | +-----------
71 |
72 |
73 |
74 +-----------------
75
76
77
78 Example 4: Stereo Stream with L and R channels
79 Master. Both of the L and R channels are recei
80 Slaves. Master and both Slaves are using singl
81 L+R. Each Slave device processes the L + R dat
82 based on static configuration or dynamic orien
83 one or more speakers. ::
84
85 +---------------+ C
86 | Master +---------+-----------
87 | Interface | |
88 | | |
89 | | |
90 | L + R +---+-----------------
91 | (Data) | | | Data Di
92 +---------------+ | | +-------
93 | |
94 | |
95 | |
96 | +-----------
97 |
98 |
99 |
100 +-----------------
101
102
103
104 Example 5: Stereo Stream with L and R channel
105 Ports of the Master and is received by only si
106 interface. ::
107
108 +--------------------+
109 | |
110 | +--------------+
111 | | ||
112 | | Data Port || L Channel
113 | | 1 |------------+
114 | | L Channel || |
115 | | (Data) || | L
116 | Master +----------+ | +--
117 | Interface | |
118 | +--------------+ |
119 | | || |
120 | | Data Port |------------+
121 | | 2 || R Channel
122 | | R Channel ||
123 | | (Data) ||
124 | +--------------+ Clock S
125 | +----------------
126 +--------------------+
127
128
129 Example 6: Stereo Stream with L and R channel
130 rendering one channel, and is received by two
131 receiving one channel. Both Masters and both S
132
133 +---------------+ C
134 | Master +---------------------
135 | Interface |
136 | 1 |
137 | |
138 | L +---------------------
139 | (Data) | Data Direction
140 +---------------+ +------------------
141
142 +---------------+ C
143 | Master +---------------------
144 | Interface |
145 | 2 |
146 | |
147 | R +---------------------
148 | (Data) | Data Direction
149 +---------------+ +------------------
150
151 Example 7: Stereo Stream with L and R channel
152 Masters, each rendering both channels. Each Sl
153 is the same application as Example 4 but with
154 separate links. ::
155
156 +---------------+ C
157 | Master +---------------------
158 | Interface |
159 | 1 |
160 | |
161 | L + R +---------------------
162 | (Data) | Data Direction
163 +---------------+ +------------------
164
165 +---------------+ C
166 | Master +---------------------
167 | Interface |
168 | 2 |
169 | |
170 | L + R +---------------------
171 | (Data) | Data Direction
172 +---------------+ +------------------
173
174 Example 8: 4-channel Stream is rendered by 2 M
175 2 channels. Each Slave receives 2 channels. ::
176
177 +---------------+ C
178 | Master +---------------------
179 | Interface |
180 | 1 |
181 | |
182 | L1 + R1 +---------------------
183 | (Data) | Data Direction
184 +---------------+ +------------------
185
186 +---------------+ C
187 | Master +---------------------
188 | Interface |
189 | 2 |
190 | |
191 | L2 + R2 +---------------------
192 | (Data) | Data Direction
193 +---------------+ +------------------
194
195 Note1: In multi-link cases like above, to lock
196 lock and then go on locking bus instances. But
197 framework(ASoC DPCM) guarantees that stream op
198 always serialized. So, there is no race condit
199 global lock.
200
201 Note2: A Slave device may be configured to rec
202 transmitted on a link for a given Stream (Exam
203 of the data (Example 3). The configuration of
204 handled by a SoundWire subsystem API, but inst
205 snd_soc_dai_set_tdm_slot() API. The platform o
206 typically configure which of the slots are use
207 same slots would be used by all Devices, while
208 Device1 would use e.g. Slot 0 and Slave device
209
210 Note3: Multiple Sink ports can extract the sam
211 same bitSlots in the SoundWire frame, however
212 shall be configured with different bitSlot con
213 same limitation as with I2S/PCM TDM usages.
214
215 SoundWire Stream Management flow
216 ================================
217
218 Stream definitions
219 ------------------
220
221 (1) Current stream: This is classified as th
222 to be performed like prepare, enable, di
223
224 (2) Active stream: This is classified as the
225 on Bus other than current stream. There
226 on the Bus.
227
228 SoundWire Bus manages stream operations for ea
229 rendered/captured on the SoundWire Bus. This s
230 done for each of the stream allocated/released
231 stream states maintained by the Bus for each o
232
233
234 SoundWire stream states
235 -----------------------
236
237 Below shows the SoundWire stream states and st
238
239 +-----------+ +------------+ +
240 | ALLOCATED +---->| CONFIGURED +---->|
241 | STATE | | STATE | |
242 +-----------+ +------------+ +
243
244
245
246
247
248 +----------+ +-----
249 | RELEASED |<----------+ DEPR
250 | STATE | | ST
251 +----------+ +-----
252
253 NOTE: State transitions between ``SDW_STREAM_E
254 ``SDW_STREAM_DISABLED`` are only relevant when
255 supported at the ALSA/ASoC level. Likewise the
256 ``SDW_DISABLED_STATE`` and ``SDW_PREPARED_STAT
257 INFO_RESUME flag.
258
259 NOTE2: The framework implements basic state tr
260 does not e.g. check if a transition from DISAB
261 on a specific platform. Such tests need to be
262 level.
263
264 Stream State Operations
265 -----------------------
266
267 Below section explains the operations done by
268 Slave(s) as part of stream state transitions.
269
270 SDW_STREAM_ALLOCATED
271 ~~~~~~~~~~~~~~~~~~~~
272
273 Allocation state for stream. This is the entry
274 of the stream. Operations performed before ent
275
276 (1) A stream runtime is allocated for the st
277 runtime is used as a reference for all t
278 on the stream.
279
280 (2) The resources required for holding strea
281 allocated and initialized. This holds al
282 such as stream type (PCM/PDM) and parame
283 interface associated with the stream, st
284
285 After all above operations are successful, str
286 ``SDW_STREAM_ALLOCATED``.
287
288 Bus implements below API for allocate a stream
289 per stream. From ASoC DPCM framework, this str
290 .startup() operation.
291
292 .. code-block:: c
293
294 int sdw_alloc_stream(char * stream_name);
295
296 The SoundWire core provides a sdw_startup_stre
297 typically called during a dailink .startup() c
298 stream allocation and sets the stream pointer
299 connected to a stream.
300
301 SDW_STREAM_CONFIGURED
302 ~~~~~~~~~~~~~~~~~~~~~
303
304 Configuration state of stream. Operations perf
305 this state:
306
307 (1) The resources allocated for stream infor
308 state are updated here. This includes st
309 and Slave(s) runtime information associa
310
311 (2) All the Master(s) and Slave(s) associate
312 the port information to Bus which includ
313 Master(s) and Slave(s) for current strea
314
315 After all above operations are successful, str
316 ``SDW_STREAM_CONFIGURED``.
317
318 Bus implements below APIs for CONFIG state whi
319 the respective Master(s) and Slave(s) associat
320 only be invoked once by respective Master(s) a
321 framework, this stream state is linked to .hw_
322
323 .. code-block:: c
324
325 int sdw_stream_add_master(struct sdw_bus * b
326 struct sdw_stream_config * str
327 const struct sdw_ports_config
328 struct sdw_stream_runtime * st
329
330 int sdw_stream_add_slave(struct sdw_slave *
331 struct sdw_stream_config * str
332 const struct sdw_ports_config
333 struct sdw_stream_runtime * st
334
335
336 SDW_STREAM_PREPARED
337 ~~~~~~~~~~~~~~~~~~~
338
339 Prepare state of stream. Operations performed
340
341 (0) Steps 1 and 2 are omitted in the case of
342 where the bus bandwidth is known.
343
344 (1) Bus parameters such as bandwidth, frame
345 are computed based on current stream as
346 stream(s) on Bus. Re-computation is requ
347 stream on the Bus.
348
349 (2) Transport and port parameters of all Mas
350 computed for the current as well as alre
351 shape and clock frequency computed in st
352
353 (3) Computed Bus and transport parameters ar
354 Slave(s) registers. The banked registers
355 alternate bank (bank currently unused).
356 already active stream(s) on the alternat
357 This is done in order to not disrupt alr
358
359 (4) Once all the values are programmed, Bus
360 bank where all new values programmed get
361
362 (5) Ports of Master(s) and Slave(s) for curr
363 programming PrepareCtrl register.
364
365 After all above operations are successful, str
366 ``SDW_STREAM_PREPARED``.
367
368 Bus implements below API for PREPARE state whi
369 once per stream. From ASoC DPCM framework, thi
370 to .prepare() operation. Since the .trigger()
371 follow the .prepare(), a direct transition fro
372 ``SDW_STREAM_PREPARED`` to ``SDW_STREAM_DEPREP
373
374 .. code-block:: c
375
376 int sdw_prepare_stream(struct sdw_stream_run
377
378
379 SDW_STREAM_ENABLED
380 ~~~~~~~~~~~~~~~~~~
381
382 Enable state of stream. The data port(s) are e
383 Operations performed before entering in this s
384
385 (1) All the values computed in SDW_STREAM_PR
386 in alternate bank (bank currently unused
387 already active stream(s) as well.
388
389 (2) All the Master(s) and Slave(s) port(s) f
390 enabled on alternate bank (bank currentl
391 ChannelEn register.
392
393 (3) Once all the values are programmed, Bus
394 bank where all new values programmed get
395 associated with current stream are enabl
396
397 After all above operations are successful, str
398 ``SDW_STREAM_ENABLED``.
399
400 Bus implements below API for ENABLE state whic
401 stream. From ASoC DPCM framework, this stream
402 .trigger() start operation.
403
404 .. code-block:: c
405
406 int sdw_enable_stream(struct sdw_stream_runt
407
408 SDW_STREAM_DISABLED
409 ~~~~~~~~~~~~~~~~~~~
410
411 Disable state of stream. The data port(s) are
412 Operations performed before entering in this s
413
414 (1) All the Master(s) and Slave(s) port(s) f
415 disabled on alternate bank (bank current
416 ChannelEn register.
417
418 (2) All the current configuration of Bus and
419 into alternate bank (bank currently unus
420
421 (3) Once all the values are programmed, Bus
422 bank where all new values programmed get
423 with current stream are disabled.
424
425 After all above operations are successful, str
426 ``SDW_STREAM_DISABLED``.
427
428 Bus implements below API for DISABLED state wh
429 per stream. From ASoC DPCM framework, this str
430 .trigger() stop operation.
431
432 When the INFO_PAUSE flag is supported, a direc
433 ``SDW_STREAM_ENABLED`` is allowed.
434
435 For resume operations where ASoC will use the
436 stream can transition from ``SDW_STREAM_DISABL
437 ``SDW_STREAM_PREPARED``, with all required set
438 without updating the bandwidth and bit allocat
439
440 .. code-block:: c
441
442 int sdw_disable_stream(struct sdw_stream_run
443
444
445 SDW_STREAM_DEPREPARED
446 ~~~~~~~~~~~~~~~~~~~~~
447
448 De-prepare state of stream. Operations perform
449 state:
450
451 (1) All the port(s) of Master(s) and Slave(s
452 de-prepared by programming PrepareCtrl r
453
454 (2) The payload bandwidth of current stream
455 bandwidth requirement of bus and new par
456 applied by performing bank switch etc.
457
458 After all above operations are successful, str
459 ``SDW_STREAM_DEPREPARED``.
460
461 Bus implements below API for DEPREPARED state
462 once per stream. ALSA/ASoC do not have a conce
463 the mapping from this stream state to ALSA/ASo
464 implementation specific.
465
466 When the INFO_PAUSE flag is supported, the str
467 the .hw_free() operation - the stream is not d
468 TRIGGER_STOP.
469
470 Other implementations may transition to the ``
471 state on TRIGGER_STOP, should they require a t
472 ``SDW_STREAM_PREPARED`` state.
473
474 .. code-block:: c
475
476 int sdw_deprepare_stream(struct sdw_stream_r
477
478
479 SDW_STREAM_RELEASED
480 ~~~~~~~~~~~~~~~~~~~
481
482 Release state of stream. Operations performed
483
484 (1) Release port resources for all Master(s)
485 associated with current stream.
486
487 (2) Release Master(s) and Slave(s) runtime r
488 current stream.
489
490 (3) Release stream runtime resources associa
491
492 After all above operations are successful, str
493 ``SDW_STREAM_RELEASED``.
494
495 Bus implements below APIs for RELEASE state wh
496 all the Master(s) and Slave(s) associated with
497 framework, this stream state is linked to .hw_
498
499 .. code-block:: c
500
501 int sdw_stream_remove_master(struct sdw_bus
502 struct sdw_stream_runtime * st
503 int sdw_stream_remove_slave(struct sdw_slave
504 struct sdw_stream_runtime * st
505
506
507 The .shutdown() ASoC DPCM operation calls belo
508 stream assigned as part of ALLOCATED state.
509
510 In .shutdown() the data structure maintaining
511
512 .. code-block:: c
513
514 void sdw_release_stream(struct sdw_stream_ru
515
516 The SoundWire core provides a sdw_shutdown_str
517 typically called during a dailink .shutdown()
518 the stream pointer for all DAIS connected to a
519 memory allocated for the stream.
520
521 Not Supported
522 =============
523
524 1. A single port with multiple channels suppor
525 streams or across stream. For example a por
526 to handle 2 independent stereo streams even
527 in SoundWire.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.