0001 =========================
0002 Audio Stream in SoundWire
0003 =========================
0004
0005 An audio stream is a logical or virtual connection created between
0006
0007 (1) System memory buffer(s) and Codec(s)
0008
0009 (2) DSP memory buffer(s) and Codec(s)
0010
0011 (3) FIFO(s) and Codec(s)
0012
0013 (4) Codec(s) and Codec(s)
0014
0015 which is typically driven by a DMA(s) channel through the data link. An
0016 audio stream contains one or more channels of data. All channels within
0017 stream must have same sample rate and same sample size.
0018
0019 Assume a stream with two channels (Left & Right) is opened using SoundWire
0020 interface. Below are some ways a stream can be represented in SoundWire.
0021
0022 Stream Sample in memory (System memory, DSP memory or FIFOs) ::
0023
0024 -------------------------
0025 | L | R | L | R | L | R |
0026 -------------------------
0027
0028 Example 1: Stereo Stream with L and R channels is rendered from Master to
0029 Slave. Both Master and Slave is using single port. ::
0030
0031 +---------------+ Clock Signal +---------------+
0032 | Master +----------------------------------+ Slave |
0033 | Interface | | Interface |
0034 | | | 1 |
0035 | | Data Signal | |
0036 | L + R +----------------------------------+ L + R |
0037 | (Data) | Data Direction | (Data) |
0038 +---------------+ +-----------------------> +---------------+
0039
0040
0041 Example 2: Stereo Stream with L and R channels is captured from Slave to
0042 Master. Both Master and Slave is using single port. ::
0043
0044
0045 +---------------+ Clock Signal +---------------+
0046 | Master +----------------------------------+ Slave |
0047 | Interface | | Interface |
0048 | | | 1 |
0049 | | Data Signal | |
0050 | L + R +----------------------------------+ L + R |
0051 | (Data) | Data Direction | (Data) |
0052 +---------------+ <-----------------------+ +---------------+
0053
0054
0055 Example 3: Stereo Stream with L and R channels is rendered by Master. Each
0056 of the L and R channel is received by two different Slaves. Master and both
0057 Slaves are using single port. ::
0058
0059 +---------------+ Clock Signal +---------------+
0060 | Master +---------+------------------------+ Slave |
0061 | Interface | | | Interface |
0062 | | | | 1 |
0063 | | | Data Signal | |
0064 | L + R +---+------------------------------+ L |
0065 | (Data) | | | Data Direction | (Data) |
0066 +---------------+ | | +-------------> +---------------+
0067 | |
0068 | |
0069 | | +---------------+
0070 | +----------------------> | Slave |
0071 | | Interface |
0072 | | 2 |
0073 | | |
0074 +----------------------------> | R |
0075 | (Data) |
0076 +---------------+
0077
0078 Example 4: Stereo Stream with L and R channels is rendered by
0079 Master. Both of the L and R channels are received by two different
0080 Slaves. Master and both Slaves are using single port handling
0081 L+R. Each Slave device processes the L + R data locally, typically
0082 based on static configuration or dynamic orientation, and may drive
0083 one or more speakers. ::
0084
0085 +---------------+ Clock Signal +---------------+
0086 | Master +---------+------------------------+ Slave |
0087 | Interface | | | Interface |
0088 | | | | 1 |
0089 | | | Data Signal | |
0090 | L + R +---+------------------------------+ L + R |
0091 | (Data) | | | Data Direction | (Data) |
0092 +---------------+ | | +-------------> +---------------+
0093 | |
0094 | |
0095 | | +---------------+
0096 | +----------------------> | Slave |
0097 | | Interface |
0098 | | 2 |
0099 | | |
0100 +----------------------------> | L + R |
0101 | (Data) |
0102 +---------------+
0103
0104 Example 5: Stereo Stream with L and R channel is rendered by two different
0105 Ports of the Master and is received by only single Port of the Slave
0106 interface. ::
0107
0108 +--------------------+
0109 | |
0110 | +--------------+ +----------------+
0111 | | || | |
0112 | | Data Port || L Channel | |
0113 | | 1 |------------+ | |
0114 | | L Channel || | +-----+----+ |
0115 | | (Data) || | L + R Channel || Data | |
0116 | Master +----------+ | +---+---------> || Port | |
0117 | Interface | | || 1 | |
0118 | +--------------+ | || | |
0119 | | || | +----------+ |
0120 | | Data Port |------------+ | |
0121 | | 2 || R Channel | Slave |
0122 | | R Channel || | Interface |
0123 | | (Data) || | 1 |
0124 | +--------------+ Clock Signal | L + R |
0125 | +---------------------------> | (Data) |
0126 +--------------------+ | |
0127 +----------------+
0128
0129 Example 6: Stereo Stream with L and R channel is rendered by 2 Masters, each
0130 rendering one channel, and is received by two different Slaves, each
0131 receiving one channel. Both Masters and both Slaves are using single port. ::
0132
0133 +---------------+ Clock Signal +---------------+
0134 | Master +----------------------------------+ Slave |
0135 | Interface | | Interface |
0136 | 1 | | 1 |
0137 | | Data Signal | |
0138 | L +----------------------------------+ L |
0139 | (Data) | Data Direction | (Data) |
0140 +---------------+ +-----------------------> +---------------+
0141
0142 +---------------+ Clock Signal +---------------+
0143 | Master +----------------------------------+ Slave |
0144 | Interface | | Interface |
0145 | 2 | | 2 |
0146 | | Data Signal | |
0147 | R +----------------------------------+ R |
0148 | (Data) | Data Direction | (Data) |
0149 +---------------+ +-----------------------> +---------------+
0150
0151 Example 7: Stereo Stream with L and R channel is rendered by 2
0152 Masters, each rendering both channels. Each Slave receives L + R. This
0153 is the same application as Example 4 but with Slaves placed on
0154 separate links. ::
0155
0156 +---------------+ Clock Signal +---------------+
0157 | Master +----------------------------------+ Slave |
0158 | Interface | | Interface |
0159 | 1 | | 1 |
0160 | | Data Signal | |
0161 | L + R +----------------------------------+ L + R |
0162 | (Data) | Data Direction | (Data) |
0163 +---------------+ +-----------------------> +---------------+
0164
0165 +---------------+ Clock Signal +---------------+
0166 | Master +----------------------------------+ Slave |
0167 | Interface | | Interface |
0168 | 2 | | 2 |
0169 | | Data Signal | |
0170 | L + R +----------------------------------+ L + R |
0171 | (Data) | Data Direction | (Data) |
0172 +---------------+ +-----------------------> +---------------+
0173
0174 Example 8: 4-channel Stream is rendered by 2 Masters, each rendering a
0175 2 channels. Each Slave receives 2 channels. ::
0176
0177 +---------------+ Clock Signal +---------------+
0178 | Master +----------------------------------+ Slave |
0179 | Interface | | Interface |
0180 | 1 | | 1 |
0181 | | Data Signal | |
0182 | L1 + R1 +----------------------------------+ L1 + R1 |
0183 | (Data) | Data Direction | (Data) |
0184 +---------------+ +-----------------------> +---------------+
0185
0186 +---------------+ Clock Signal +---------------+
0187 | Master +----------------------------------+ Slave |
0188 | Interface | | Interface |
0189 | 2 | | 2 |
0190 | | Data Signal | |
0191 | L2 + R2 +----------------------------------+ L2 + R2 |
0192 | (Data) | Data Direction | (Data) |
0193 +---------------+ +-----------------------> +---------------+
0194
0195 Note1: In multi-link cases like above, to lock, one would acquire a global
0196 lock and then go on locking bus instances. But, in this case the caller
0197 framework(ASoC DPCM) guarantees that stream operations on a card are
0198 always serialized. So, there is no race condition and hence no need for
0199 global lock.
0200
0201 Note2: A Slave device may be configured to receive all channels
0202 transmitted on a link for a given Stream (Example 4) or just a subset
0203 of the data (Example 3). The configuration of the Slave device is not
0204 handled by a SoundWire subsystem API, but instead by the
0205 snd_soc_dai_set_tdm_slot() API. The platform or machine driver will
0206 typically configure which of the slots are used. For Example 4, the
0207 same slots would be used by all Devices, while for Example 3 the Slave
0208 Device1 would use e.g. Slot 0 and Slave device2 slot 1.
0209
0210 Note3: Multiple Sink ports can extract the same information for the
0211 same bitSlots in the SoundWire frame, however multiple Source ports
0212 shall be configured with different bitSlot configurations. This is the
0213 same limitation as with I2S/PCM TDM usages.
0214
0215 SoundWire Stream Management flow
0216 ================================
0217
0218 Stream definitions
0219 ------------------
0220
0221 (1) Current stream: This is classified as the stream on which operation has
0222 to be performed like prepare, enable, disable, de-prepare etc.
0223
0224 (2) Active stream: This is classified as the stream which is already active
0225 on Bus other than current stream. There can be multiple active streams
0226 on the Bus.
0227
0228 SoundWire Bus manages stream operations for each stream getting
0229 rendered/captured on the SoundWire Bus. This section explains Bus operations
0230 done for each of the stream allocated/released on Bus. Following are the
0231 stream states maintained by the Bus for each of the audio stream.
0232
0233
0234 SoundWire stream states
0235 -----------------------
0236
0237 Below shows the SoundWire stream states and state transition diagram. ::
0238
0239 +-----------+ +------------+ +----------+ +----------+
0240 | ALLOCATED +---->| CONFIGURED +---->| PREPARED +---->| ENABLED |
0241 | STATE | | STATE | | STATE | | STATE |
0242 +-----------+ +------------+ +---+--+---+ +----+-----+
0243 ^ ^ ^
0244 | | |
0245 __| |___________ |
0246 | | |
0247 v | v
0248 +----------+ +-----+------+ +-+--+-----+
0249 | RELEASED |<----------+ DEPREPARED |<-------+ DISABLED |
0250 | STATE | | STATE | | STATE |
0251 +----------+ +------------+ +----------+
0252
0253 NOTE: State transitions between ``SDW_STREAM_ENABLED`` and
0254 ``SDW_STREAM_DISABLED`` are only relevant when then INFO_PAUSE flag is
0255 supported at the ALSA/ASoC level. Likewise the transition between
0256 ``SDW_DISABLED_STATE`` and ``SDW_PREPARED_STATE`` depends on the
0257 INFO_RESUME flag.
0258
0259 NOTE2: The framework implements basic state transition checks, but
0260 does not e.g. check if a transition from DISABLED to ENABLED is valid
0261 on a specific platform. Such tests need to be added at the ALSA/ASoC
0262 level.
0263
0264 Stream State Operations
0265 -----------------------
0266
0267 Below section explains the operations done by the Bus on Master(s) and
0268 Slave(s) as part of stream state transitions.
0269
0270 SDW_STREAM_ALLOCATED
0271 ~~~~~~~~~~~~~~~~~~~~
0272
0273 Allocation state for stream. This is the entry state
0274 of the stream. Operations performed before entering in this state:
0275
0276 (1) A stream runtime is allocated for the stream. This stream
0277 runtime is used as a reference for all the operations performed
0278 on the stream.
0279
0280 (2) The resources required for holding stream runtime information are
0281 allocated and initialized. This holds all stream related information
0282 such as stream type (PCM/PDM) and parameters, Master and Slave
0283 interface associated with the stream, stream state etc.
0284
0285 After all above operations are successful, stream state is set to
0286 ``SDW_STREAM_ALLOCATED``.
0287
0288 Bus implements below API for allocate a stream which needs to be called once
0289 per stream. From ASoC DPCM framework, this stream state maybe linked to
0290 .startup() operation.
0291
0292 .. code-block:: c
0293
0294 int sdw_alloc_stream(char * stream_name);
0295
0296 The SoundWire core provides a sdw_startup_stream() helper function,
0297 typically called during a dailink .startup() callback, which performs
0298 stream allocation and sets the stream pointer for all DAIs
0299 connected to a stream.
0300
0301 SDW_STREAM_CONFIGURED
0302 ~~~~~~~~~~~~~~~~~~~~~
0303
0304 Configuration state of stream. Operations performed before entering in
0305 this state:
0306
0307 (1) The resources allocated for stream information in SDW_STREAM_ALLOCATED
0308 state are updated here. This includes stream parameters, Master(s)
0309 and Slave(s) runtime information associated with current stream.
0310
0311 (2) All the Master(s) and Slave(s) associated with current stream provide
0312 the port information to Bus which includes port numbers allocated by
0313 Master(s) and Slave(s) for current stream and their channel mask.
0314
0315 After all above operations are successful, stream state is set to
0316 ``SDW_STREAM_CONFIGURED``.
0317
0318 Bus implements below APIs for CONFIG state which needs to be called by
0319 the respective Master(s) and Slave(s) associated with stream. These APIs can
0320 only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM
0321 framework, this stream state is linked to .hw_params() operation.
0322
0323 .. code-block:: c
0324
0325 int sdw_stream_add_master(struct sdw_bus * bus,
0326 struct sdw_stream_config * stream_config,
0327 struct sdw_ports_config * ports_config,
0328 struct sdw_stream_runtime * stream);
0329
0330 int sdw_stream_add_slave(struct sdw_slave * slave,
0331 struct sdw_stream_config * stream_config,
0332 struct sdw_ports_config * ports_config,
0333 struct sdw_stream_runtime * stream);
0334
0335
0336 SDW_STREAM_PREPARED
0337 ~~~~~~~~~~~~~~~~~~~
0338
0339 Prepare state of stream. Operations performed before entering in this state:
0340
0341 (0) Steps 1 and 2 are omitted in the case of a resume operation,
0342 where the bus bandwidth is known.
0343
0344 (1) Bus parameters such as bandwidth, frame shape, clock frequency,
0345 are computed based on current stream as well as already active
0346 stream(s) on Bus. Re-computation is required to accommodate current
0347 stream on the Bus.
0348
0349 (2) Transport and port parameters of all Master(s) and Slave(s) port(s) are
0350 computed for the current as well as already active stream based on frame
0351 shape and clock frequency computed in step 1.
0352
0353 (3) Computed Bus and transport parameters are programmed in Master(s) and
0354 Slave(s) registers. The banked registers programming is done on the
0355 alternate bank (bank currently unused). Port(s) are enabled for the
0356 already active stream(s) on the alternate bank (bank currently unused).
0357 This is done in order to not disrupt already active stream(s).
0358
0359 (4) Once all the values are programmed, Bus initiates switch to alternate
0360 bank where all new values programmed gets into effect.
0361
0362 (5) Ports of Master(s) and Slave(s) for current stream are prepared by
0363 programming PrepareCtrl register.
0364
0365 After all above operations are successful, stream state is set to
0366 ``SDW_STREAM_PREPARED``.
0367
0368 Bus implements below API for PREPARE state which needs to be called
0369 once per stream. From ASoC DPCM framework, this stream state is linked
0370 to .prepare() operation. Since the .trigger() operations may not
0371 follow the .prepare(), a direct transition from
0372 ``SDW_STREAM_PREPARED`` to ``SDW_STREAM_DEPREPARED`` is allowed.
0373
0374 .. code-block:: c
0375
0376 int sdw_prepare_stream(struct sdw_stream_runtime * stream);
0377
0378
0379 SDW_STREAM_ENABLED
0380 ~~~~~~~~~~~~~~~~~~
0381
0382 Enable state of stream. The data port(s) are enabled upon entering this state.
0383 Operations performed before entering in this state:
0384
0385 (1) All the values computed in SDW_STREAM_PREPARED state are programmed
0386 in alternate bank (bank currently unused). It includes programming of
0387 already active stream(s) as well.
0388
0389 (2) All the Master(s) and Slave(s) port(s) for the current stream are
0390 enabled on alternate bank (bank currently unused) by programming
0391 ChannelEn register.
0392
0393 (3) Once all the values are programmed, Bus initiates switch to alternate
0394 bank where all new values programmed gets into effect and port(s)
0395 associated with current stream are enabled.
0396
0397 After all above operations are successful, stream state is set to
0398 ``SDW_STREAM_ENABLED``.
0399
0400 Bus implements below API for ENABLE state which needs to be called once per
0401 stream. From ASoC DPCM framework, this stream state is linked to
0402 .trigger() start operation.
0403
0404 .. code-block:: c
0405
0406 int sdw_enable_stream(struct sdw_stream_runtime * stream);
0407
0408 SDW_STREAM_DISABLED
0409 ~~~~~~~~~~~~~~~~~~~
0410
0411 Disable state of stream. The data port(s) are disabled upon exiting this state.
0412 Operations performed before entering in this state:
0413
0414 (1) All the Master(s) and Slave(s) port(s) for the current stream are
0415 disabled on alternate bank (bank currently unused) by programming
0416 ChannelEn register.
0417
0418 (2) All the current configuration of Bus and active stream(s) are programmed
0419 into alternate bank (bank currently unused).
0420
0421 (3) Once all the values are programmed, Bus initiates switch to alternate
0422 bank where all new values programmed gets into effect and port(s) associated
0423 with current stream are disabled.
0424
0425 After all above operations are successful, stream state is set to
0426 ``SDW_STREAM_DISABLED``.
0427
0428 Bus implements below API for DISABLED state which needs to be called once
0429 per stream. From ASoC DPCM framework, this stream state is linked to
0430 .trigger() stop operation.
0431
0432 When the INFO_PAUSE flag is supported, a direct transition to
0433 ``SDW_STREAM_ENABLED`` is allowed.
0434
0435 For resume operations where ASoC will use the .prepare() callback, the
0436 stream can transition from ``SDW_STREAM_DISABLED`` to
0437 ``SDW_STREAM_PREPARED``, with all required settings restored but
0438 without updating the bandwidth and bit allocation.
0439
0440 .. code-block:: c
0441
0442 int sdw_disable_stream(struct sdw_stream_runtime * stream);
0443
0444
0445 SDW_STREAM_DEPREPARED
0446 ~~~~~~~~~~~~~~~~~~~~~
0447
0448 De-prepare state of stream. Operations performed before entering in this
0449 state:
0450
0451 (1) All the port(s) of Master(s) and Slave(s) for current stream are
0452 de-prepared by programming PrepareCtrl register.
0453
0454 (2) The payload bandwidth of current stream is reduced from the total
0455 bandwidth requirement of bus and new parameters calculated and
0456 applied by performing bank switch etc.
0457
0458 After all above operations are successful, stream state is set to
0459 ``SDW_STREAM_DEPREPARED``.
0460
0461 Bus implements below API for DEPREPARED state which needs to be called
0462 once per stream. ALSA/ASoC do not have a concept of 'deprepare', and
0463 the mapping from this stream state to ALSA/ASoC operation may be
0464 implementation specific.
0465
0466 When the INFO_PAUSE flag is supported, the stream state is linked to
0467 the .hw_free() operation - the stream is not deprepared on a
0468 TRIGGER_STOP.
0469
0470 Other implementations may transition to the ``SDW_STREAM_DEPREPARED``
0471 state on TRIGGER_STOP, should they require a transition through the
0472 ``SDW_STREAM_PREPARED`` state.
0473
0474 .. code-block:: c
0475
0476 int sdw_deprepare_stream(struct sdw_stream_runtime * stream);
0477
0478
0479 SDW_STREAM_RELEASED
0480 ~~~~~~~~~~~~~~~~~~~
0481
0482 Release state of stream. Operations performed before entering in this state:
0483
0484 (1) Release port resources for all Master(s) and Slave(s) port(s)
0485 associated with current stream.
0486
0487 (2) Release Master(s) and Slave(s) runtime resources associated with
0488 current stream.
0489
0490 (3) Release stream runtime resources associated with current stream.
0491
0492 After all above operations are successful, stream state is set to
0493 ``SDW_STREAM_RELEASED``.
0494
0495 Bus implements below APIs for RELEASE state which needs to be called by
0496 all the Master(s) and Slave(s) associated with stream. From ASoC DPCM
0497 framework, this stream state is linked to .hw_free() operation.
0498
0499 .. code-block:: c
0500
0501 int sdw_stream_remove_master(struct sdw_bus * bus,
0502 struct sdw_stream_runtime * stream);
0503 int sdw_stream_remove_slave(struct sdw_slave * slave,
0504 struct sdw_stream_runtime * stream);
0505
0506
0507 The .shutdown() ASoC DPCM operation calls below Bus API to release
0508 stream assigned as part of ALLOCATED state.
0509
0510 In .shutdown() the data structure maintaining stream state are freed up.
0511
0512 .. code-block:: c
0513
0514 void sdw_release_stream(struct sdw_stream_runtime * stream);
0515
0516 The SoundWire core provides a sdw_shutdown_stream() helper function,
0517 typically called during a dailink .shutdown() callback, which clears
0518 the stream pointer for all DAIS connected to a stream and releases the
0519 memory allocated for the stream.
0520
0521 Not Supported
0522 =============
0523
0524 1. A single port with multiple channels supported cannot be used between two
0525 streams or across stream. For example a port with 4 channels cannot be used
0526 to handle 2 independent stereo streams even though it's possible in theory
0527 in SoundWire.
