Documentation/driver-api/soundwire/stream.rst

   1 =========================
   2 Audio Stream in SoundWire
   3 =========================
   4
   5 An 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
  15 which is typically driven by a DMA(s) channel through the data link. An
  16 audio stream contains one or more channels of data. All channels within
  17 stream must have same sample rate and same sample size.
  18
  19 Assume a stream with two channels (Left & Right) is opened using SoundWire
  20 interface. Below are some ways a stream can be represented in SoundWire.
  21
  22 Stream Sample in memory (System memory, DSP memory or FIFOs) ::
  23
  24         -------------------------
  25         | L | R | L | R | L | R |
  26         -------------------------
  27
  28 Example 1: Stereo Stream with L and R channels is rendered from Master to
  29 Slave. 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
  41 Example 2: Stereo Stream with L and R channels is captured from Slave to
  42 Master. 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
  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 different Slaves. Master and both
  57 Slaves 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
  79 Example 4: Stereo Stream with L and R channel is rendered by two different
  80 Ports of the Master and is received by only single Port of the Slave
  81 interface. ::
  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
 104 Example 5: Stereo Stream with L and R channel is rendered by 2 Masters, each
 105 rendering one channel, and is received by two different Slaves, each
 106 receiving 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
 126 Note: In multi-link cases like above, to lock, one would acquire a global
 127 lock and then go on locking bus instances. But, in this case the caller
 128 framework(ASoC DPCM) guarantees that stream operations on a card are
 129 always serialized. So, there is no race condition and hence no need for
 130 global lock.
 131
 132 SoundWire Stream Management flow
 133 ================================
 134
 135 Stream 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
 145 SoundWire Bus manages stream operations for each stream getting
 146 rendered/captured on the SoundWire Bus. This section explains Bus operations
 147 done for each of the stream allocated/released on Bus. Following are the
 148 stream states maintained by the Bus for each of the audio stream.
 149
 150
 151 SoundWire stream states
 152 -----------------------
 153
 154 Below 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
 169 NOTE: State transition between prepare and deprepare is supported in Spec
 170 but not in the software (subsystem)
 171
 172 NOTE2: Stream state transition checks need to be handled by caller
 173 framework, for example ALSA/ASoC. No checks for stream transition exist in
 174 SoundWire subsystem.
 175
 176 Stream State Operations
 177 -----------------------
 178
 179 Below section explains the operations done by the Bus on Master(s) and
 180 Slave(s) as part of stream state transitions.
 181
 182 SDW_STREAM_ALLOCATED
 183 ~~~~~~~~~~~~~~~~~~~~
 184
 185 Allocation state for stream. This is the entry state
 186 of 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
 197 After all above operations are successful, stream state is set to
 198 ``SDW_STREAM_ALLOCATED``.
 199
 200 Bus implements below API for allocate a stream which needs to be called once
 201 per 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
 209 SDW_STREAM_CONFIGURED
 210 ~~~~~~~~~~~~~~~~~~~~~
 211
 212 Configuration state of stream. Operations performed before entering in
 213 this 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
 223 After all above operations are successful, stream state is set to
 224 ``SDW_STREAM_CONFIGURED``.
 225
 226 Bus implements below APIs for CONFIG state which needs to be called by
 227 the respective Master(s) and Slave(s) associated with stream. These APIs can
 228 only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM
 229 framework, 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
 244 SDW_STREAM_PREPARED
 245 ~~~~~~~~~~~~~~~~~~~
 246
 247 Prepare 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
 270 After all above operations are successful, stream state is set to
 271 ``SDW_STREAM_PREPARED``.
 272
 273 Bus implements below API for PREPARE state which needs to be called once per
 274 stream. 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
 282 SDW_STREAM_ENABLED
 283 ~~~~~~~~~~~~~~~~~~
 284
 285 Enable state of stream. The data port(s) are enabled upon entering this state.
 286 Operations 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
 300 After all above operations are successful, stream state is set to
 301 ``SDW_STREAM_ENABLED``.
 302
 303 Bus implements below API for ENABLE state which needs to be called once per
 304 stream. 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
 311 SDW_STREAM_DISABLED
 312 ~~~~~~~~~~~~~~~~~~~
 313
 314 Disable state of stream. The data port(s) are disabled upon exiting this state.
 315 Operations 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
 328 After all above operations are successful, stream state is set to
 329 ``SDW_STREAM_DISABLED``.
 330
 331 Bus implements below API for DISABLED state which needs to be called once
 332 per 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
 340 SDW_STREAM_DEPREPARED
 341 ~~~~~~~~~~~~~~~~~~~~~
 342
 343 De-prepare state of stream. Operations performed before entering in this
 344 state:
 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
 353 After all above operations are successful, stream state is set to
 354 ``SDW_STREAM_DEPREPARED``.
 355
 356 Bus implements below API for DEPREPARED state which needs to be called once
 357 per 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
 365 SDW_STREAM_RELEASED
 366 ~~~~~~~~~~~~~~~~~~~
 367
 368 Release 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
 378 After all above operations are successful, stream state is set to
 379 ``SDW_STREAM_RELEASED``.
 380
 381 Bus implements below APIs for RELEASE state which needs to be called by
 382 all the Master(s) and Slave(s) associated with stream. From ASoC DPCM
 383 framework, 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
 393 The .shutdown() ASoC DPCM operation calls below Bus API to release
 394 stream assigned as part of ALLOCATED state.
 395
 396 In .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
 402 Not Supported
 403 =============
 404
 405 1. A single port with multiple channels supported cannot be used between two
 406 streams or across stream. For example a port with 4 channels cannot be used
 407 to handle 2 independent stereo streams even though it's possible in theory
 408 in SoundWire.