1=========================
2Audio Stream in SoundWire
3=========================
4
5An audio stream is a logical or virtual connection created between
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
15which is typically driven by a DMA(s) channel through the data link. An
16audio stream contains one or more channels of data. All channels within
17stream must have same sample rate and same sample size.
18
19Assume a stream with two channels (Left & Right) is opened using SoundWire
20interface. Below are some ways a stream can be represented in SoundWire.
21
22Stream Sample in memory (System memory, DSP memory or FIFOs) ::
23
24	-------------------------
25	| L | R | L | R | L | R |
26	-------------------------
27
28Example 1: Stereo Stream with L and R channels is rendered from Master to
29Slave. Both Master and Slave is using single port. ::
30
31	+---------------+                    Clock Signal  +---------------+
32	|    Master     +----------------------------------+     Slave     |
33	|   Interface   |                                  |   Interface   |
34	|               |                                  |       1       |
35	|               |                     Data Signal  |               |
36	|    L  +  R    +----------------------------------+    L  +  R    |
37	|     (Data)    |     Data Direction               |     (Data)    |
38	+---------------+  +----------------------->       +---------------+
39
40
41Example 2: Stereo Stream with L and R channels is captured from Slave to
42Master. Both Master and Slave is using single port. ::
43
44
45	+---------------+                    Clock Signal  +---------------+
46	|    Master     +----------------------------------+     Slave     |
47	|   Interface   |                                  |   Interface   |
48	|               |                                  |       1       |
49	|               |                     Data Signal  |               |
50	|    L  +  R    +----------------------------------+    L  +  R    |
51	|     (Data)    |     Data Direction               |     (Data)    |
52	+---------------+  <-----------------------+       +---------------+
53
54
55Example 3: Stereo Stream with L and R channels is rendered by Master. Each
56of the L and R channel is received by two different Slaves. Master and both
57Slaves are using single port. ::
58
59	+---------------+                    Clock Signal  +---------------+
60	|    Master     +---------+------------------------+     Slave     |
61	|   Interface   |         |                        |   Interface   |
62	|               |         |                        |       1       |
63	|               |         |           Data Signal  |               |
64	|    L  +  R    +---+------------------------------+       L       |
65	|     (Data)    |   |     |    Data Direction      |     (Data)    |
66	+---------------+   |     |   +------------->      +---------------+
67	                    |     |
68	                    |     |
69	                    |     |                        +---------------+
70	                    |     +----------------------> |     Slave     |
71	                    |                              |   Interface   |
72	                    |                              |       2       |
73	                    |                              |               |
74	                    +----------------------------> |       R       |
75	                                                   |     (Data)    |
76	                                                   +---------------+
77
78
79Example 4: Stereo Stream with L and R channel is rendered by two different
80Ports of the Master and is received by only single Port of the Slave
81interface. ::
82
83	+--------------------+
84	|                    |
85	|     +--------------+                             +----------------+
86	|     |             ||                             |                |
87	|     |  Data Port  ||  L Channel                  |                |
88	|     |      1      |------------+                 |                |
89	|     |  L Channel  ||           |                 +-----+----+     |
90	|     |   (Data)    ||           |   L + R Channel ||    Data |     |
91	| Master  +----------+           | +---+---------> ||    Port |     |
92	| Interface          |           |                 ||     1   |     |
93	|     +--------------+           |                 ||         |     |
94	|     |             ||           |                 +----------+     |
95	|     |  Data Port  |------------+                 |                |
96	|     |      2      ||  R Channel                  |     Slave      |
97	|     |  R Channel  ||                             |   Interface    |
98	|     |   (Data)    ||                             |       1        |
99	|     +--------------+         Clock Signal        |     L  +  R    |
100	|                    +---------------------------> |      (Data)    |
101	+--------------------+                             |                |
102							   +----------------+
103
104Example 5: Stereo Stream with L and R channel is rendered by 2 Masters, each
105rendering one channel, and is received by two different Slaves, each
106receiving one channel. Both Masters and both Slaves are using single port. ::
107
108	+---------------+                    Clock Signal  +---------------+
109	|    Master     +----------------------------------+     Slave     |
110	|   Interface   |                                  |   Interface   |
111	|       1       |                                  |       1       |
112	|               |                     Data Signal  |               |
113	|       L       +----------------------------------+       L       |
114	|     (Data)    |     Data Direction               |     (Data)    |
115	+---------------+  +----------------------->       +---------------+
116
117	+---------------+                    Clock Signal  +---------------+
118	|    Master     +----------------------------------+     Slave     |
119	|   Interface   |                                  |   Interface   |
120	|       2       |                                  |       2       |
121	|               |                     Data Signal  |               |
122	|       R       +----------------------------------+       R       |
123	|     (Data)    |     Data Direction               |     (Data)    |
124	+---------------+  +----------------------->       +---------------+
125
126Note: In multi-link cases like above, to lock, one would acquire a global
127lock and then go on locking bus instances. But, in this case the caller
128framework(ASoC DPCM) guarantees that stream operations on a card are
129always serialized. So, there is no race condition and hence no need for
130global lock.
131
132SoundWire Stream Management flow
133================================
134
135Stream definitions
136------------------
137
138  (1) Current stream: This is classified as the stream on which operation has
139      to be performed like prepare, enable, disable, de-prepare etc.
140
141  (2) Active stream: This is classified as the stream which is already active
142      on Bus other than current stream. There can be multiple active streams
143      on the Bus.
144
145SoundWire Bus manages stream operations for each stream getting
146rendered/captured on the SoundWire Bus. This section explains Bus operations
147done for each of the stream allocated/released on Bus. Following are the
148stream states maintained by the Bus for each of the audio stream.
149
150
151SoundWire stream states
152-----------------------
153
154Below shows the SoundWire stream states and state transition diagram. ::
155
156	+-----------+     +------------+     +----------+     +----------+
157	| ALLOCATED +---->| CONFIGURED +---->| PREPARED +---->| ENABLED  |
158	|   STATE   |     |    STATE   |     |  STATE   |     |  STATE   |
159	+-----------+     +------------+     +----------+     +----+-----+
160	                                                           ^
161	                                                           |
162	                                                           |
163	                                                           v
164	         +----------+           +------------+        +----+-----+
165	         | RELEASED |<----------+ DEPREPARED |<-------+ DISABLED |
166	         |  STATE   |           |   STATE    |        |  STATE   |
167	         +----------+           +------------+        +----------+
168
169NOTE: State transition between prepare and deprepare is supported in Spec
170but not in the software (subsystem)
171
172NOTE2: Stream state transition checks need to be handled by caller
173framework, for example ALSA/ASoC. No checks for stream transition exist in
174SoundWire subsystem.
175
176Stream State Operations
177-----------------------
178
179Below section explains the operations done by the Bus on Master(s) and
180Slave(s) as part of stream state transitions.
181
182SDW_STREAM_ALLOCATED
183~~~~~~~~~~~~~~~~~~~~
184
185Allocation state for stream. This is the entry state
186of the stream. Operations performed before entering in this state:
187
188  (1) A stream runtime is allocated for the stream. This stream
189      runtime is used as a reference for all the operations performed
190      on the stream.
191
192  (2) The resources required for holding stream runtime information are
193      allocated and initialized. This holds all stream related information
194      such as stream type (PCM/PDM) and parameters, Master and Slave
195      interface associated with the stream, stream state etc.
196
197After all above operations are successful, stream state is set to
198``SDW_STREAM_ALLOCATED``.
199
200Bus implements below API for allocate a stream which needs to be called once
201per stream. From ASoC DPCM framework, this stream state maybe linked to
202.startup() operation.
203
204  .. code-block:: c
205
206  int sdw_alloc_stream(char * stream_name);
207
208
209SDW_STREAM_CONFIGURED
210~~~~~~~~~~~~~~~~~~~~~
211
212Configuration state of stream. Operations performed before entering in
213this state:
214
215  (1) The resources allocated for stream information in SDW_STREAM_ALLOCATED
216      state are updated here. This includes stream parameters, Master(s)
217      and Slave(s) runtime information associated with current stream.
218
219  (2) All the Master(s) and Slave(s) associated with current stream provide
220      the port information to Bus which includes port numbers allocated by
221      Master(s) and Slave(s) for current stream and their channel mask.
222
223After all above operations are successful, stream state is set to
224``SDW_STREAM_CONFIGURED``.
225
226Bus implements below APIs for CONFIG state which needs to be called by
227the respective Master(s) and Slave(s) associated with stream. These APIs can
228only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM
229framework, this stream state is linked to .hw_params() operation.
230
231  .. code-block:: c
232
233  int sdw_stream_add_master(struct sdw_bus * bus,
234		struct sdw_stream_config * stream_config,
235		struct sdw_ports_config * ports_config,
236		struct sdw_stream_runtime * stream);
237
238  int sdw_stream_add_slave(struct sdw_slave * slave,
239		struct sdw_stream_config * stream_config,
240		struct sdw_ports_config * ports_config,
241		struct sdw_stream_runtime * stream);
242
243
244SDW_STREAM_PREPARED
245~~~~~~~~~~~~~~~~~~~
246
247Prepare state of stream. Operations performed before entering in this state:
248
249  (1) Bus parameters such as bandwidth, frame shape, clock frequency,
250      are computed based on current stream as well as already active
251      stream(s) on Bus. Re-computation is required to accommodate current
252      stream on the Bus.
253
254  (2) Transport and port parameters of all Master(s) and Slave(s) port(s) are
255      computed for the current as well as already active stream based on frame
256      shape and clock frequency computed in step 1.
257
258  (3) Computed Bus and transport parameters are programmed in Master(s) and
259      Slave(s) registers. The banked registers programming is done on the
260      alternate bank (bank currently unused). Port(s) are enabled for the
261      already active stream(s) on the alternate bank (bank currently unused).
262      This is done in order to not disrupt already active stream(s).
263
264  (4) Once all the values are programmed, Bus initiates switch to alternate
265      bank where all new values programmed gets into effect.
266
267  (5) Ports of Master(s) and Slave(s) for current stream are prepared by
268      programming PrepareCtrl register.
269
270After all above operations are successful, stream state is set to
271``SDW_STREAM_PREPARED``.
272
273Bus implements below API for PREPARE state which needs to be called once per
274stream. From ASoC DPCM framework, this stream state is linked to
275.prepare() operation.
276
277  .. code-block:: c
278
279  int sdw_prepare_stream(struct sdw_stream_runtime * stream);
280
281
282SDW_STREAM_ENABLED
283~~~~~~~~~~~~~~~~~~
284
285Enable state of stream. The data port(s) are enabled upon entering this state.
286Operations performed before entering in this state:
287
288  (1) All the values computed in SDW_STREAM_PREPARED state are programmed
289      in alternate bank (bank currently unused). It includes programming of
290      already active stream(s) as well.
291
292  (2) All the Master(s) and Slave(s) port(s) for the current stream are
293      enabled on alternate bank (bank currently unused) by programming
294      ChannelEn register.
295
296  (3) Once all the values are programmed, Bus initiates switch to alternate
297      bank where all new values programmed gets into effect and port(s)
298      associated with current stream are enabled.
299
300After all above operations are successful, stream state is set to
301``SDW_STREAM_ENABLED``.
302
303Bus implements below API for ENABLE state which needs to be called once per
304stream. From ASoC DPCM framework, this stream state is linked to
305.trigger() start operation.
306
307  .. code-block:: c
308
309  int sdw_enable_stream(struct sdw_stream_runtime * stream);
310
311SDW_STREAM_DISABLED
312~~~~~~~~~~~~~~~~~~~
313
314Disable state of stream. The data port(s) are disabled upon exiting this state.
315Operations performed before entering in this state:
316
317  (1) All the Master(s) and Slave(s) port(s) for the current stream are
318      disabled on alternate bank (bank currently unused) by programming
319      ChannelEn register.
320
321  (2) All the current configuration of Bus and active stream(s) are programmed
322      into alternate bank (bank currently unused).
323
324  (3) Once all the values are programmed, Bus initiates switch to alternate
325      bank where all new values programmed gets into effect and port(s) associated
326      with current stream are disabled.
327
328After all above operations are successful, stream state is set to
329``SDW_STREAM_DISABLED``.
330
331Bus implements below API for DISABLED state which needs to be called once
332per stream. From ASoC DPCM framework, this stream state is linked to
333.trigger() stop operation.
334
335  .. code-block:: c
336
337  int sdw_disable_stream(struct sdw_stream_runtime * stream);
338
339
340SDW_STREAM_DEPREPARED
341~~~~~~~~~~~~~~~~~~~~~
342
343De-prepare state of stream. Operations performed before entering in this
344state:
345
346  (1) All the port(s) of Master(s) and Slave(s) for current stream are
347      de-prepared by programming PrepareCtrl register.
348
349  (2) The payload bandwidth of current stream is reduced from the total
350      bandwidth requirement of bus and new parameters calculated and
351      applied by performing bank switch etc.
352
353After all above operations are successful, stream state is set to
354``SDW_STREAM_DEPREPARED``.
355
356Bus implements below API for DEPREPARED state which needs to be called once
357per stream. From ASoC DPCM framework, this stream state is linked to
358.trigger() stop operation.
359
360  .. code-block:: c
361
362  int sdw_deprepare_stream(struct sdw_stream_runtime * stream);
363
364
365SDW_STREAM_RELEASED
366~~~~~~~~~~~~~~~~~~~
367
368Release state of stream. Operations performed before entering in this state:
369
370  (1) Release port resources for all Master(s) and Slave(s) port(s)
371      associated with current stream.
372
373  (2) Release Master(s) and Slave(s) runtime resources associated with
374      current stream.
375
376  (3) Release stream runtime resources associated with current stream.
377
378After all above operations are successful, stream state is set to
379``SDW_STREAM_RELEASED``.
380
381Bus implements below APIs for RELEASE state which needs to be called by
382all the Master(s) and Slave(s) associated with stream. From ASoC DPCM
383framework, this stream state is linked to .hw_free() operation.
384
385  .. code-block:: c
386
387  int sdw_stream_remove_master(struct sdw_bus * bus,
388		struct sdw_stream_runtime * stream);
389  int sdw_stream_remove_slave(struct sdw_slave * slave,
390		struct sdw_stream_runtime * stream);
391
392
393The .shutdown() ASoC DPCM operation calls below Bus API to release
394stream assigned as part of ALLOCATED state.
395
396In .shutdown() the data structure maintaining stream state are freed up.
397
398  .. code-block:: c
399
400  void sdw_release_stream(struct sdw_stream_runtime * stream);
401
402Not Supported
403=============
404
4051. A single port with multiple channels supported cannot be used between two
406streams or across stream. For example a port with 4 channels cannot be used
407to handle 2 independent stereo streams even though it's possible in theory
408in SoundWire.
409