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