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 SoundWire Stream Management flow
 105 ================================
 106
 107 Stream definitions
 108 ------------------
 109
 110   (1) Current stream: This is classified as the stream on which operation has
 111       to be performed like prepare, enable, disable, de-prepare etc.
 112
 113   (2) Active stream: This is classified as the stream which is already active
 114       on Bus other than current stream. There can be multiple active streams
 115       on the Bus.
 116
 117 SoundWire Bus manages stream operations for each stream getting
 118 rendered/captured on the SoundWire Bus. This section explains Bus operations
 119 done for each of the stream allocated/released on Bus. Following are the
 120 stream states maintained by the Bus for each of the audio stream.
 121
 122
 123 SoundWire stream states
 124 -----------------------
 125
 126 Below shows the SoundWire stream states and state transition diagram. ::
 127
 128         +-----------+     +------------+     +----------+     +----------+
 129         | ALLOCATED +---->| CONFIGURED +---->| PREPARED +---->| ENABLED  |
 130         |   STATE   |     |    STATE   |     |  STATE   |     |  STATE   |
 131         +-----------+     +------------+     +----------+     +----+-----+
 132                                                                    ^
 133                                                                    |
 134                                                                    |
 135                                                                    v
 136                  +----------+           +------------+        +----+-----+
 137                  | RELEASED |<----------+ DEPREPARED |<-------+ DISABLED |
 138                  |  STATE   |           |   STATE    |        |  STATE   |
 139                  +----------+           +------------+        +----------+
 140
 141 NOTE: State transition between prepare and deprepare is supported in Spec
 142 but not in the software (subsystem)
 143
 144 NOTE2: Stream state transition checks need to be handled by caller
 145 framework, for example ALSA/ASoC. No checks for stream transition exist in
 146 SoundWire subsystem.
 147
 148 Stream State Operations
 149 -----------------------
 150
 151 Below section explains the operations done by the Bus on Master(s) and
 152 Slave(s) as part of stream state transitions.
 153
 154 SDW_STREAM_ALLOCATED
 155 ~~~~~~~~~~~~~~~~~~~~
 156
 157 Allocation state for stream. This is the entry state
 158 of the stream. Operations performed before entering in this state:
 159
 160   (1) A stream runtime is allocated for the stream. This stream
 161       runtime is used as a reference for all the operations performed
 162       on the stream.
 163
 164   (2) The resources required for holding stream runtime information are
 165       allocated and initialized. This holds all stream related information
 166       such as stream type (PCM/PDM) and parameters, Master and Slave
 167       interface associated with the stream, stream state etc.
 168
 169 After all above operations are successful, stream state is set to
 170 ``SDW_STREAM_ALLOCATED``.
 171
 172 Bus implements below API for allocate a stream which needs to be called once
 173 per stream. From ASoC DPCM framework, this stream state maybe linked to
 174 .startup() operation.
 175
 176   .. code-block:: c
 177   int sdw_alloc_stream(char * stream_name);
 178
 179
 180 SDW_STREAM_CONFIGURED
 181 ~~~~~~~~~~~~~~~~~~~~~
 182
 183 Configuration state of stream. Operations performed before entering in
 184 this state:
 185
 186   (1) The resources allocated for stream information in SDW_STREAM_ALLOCATED
 187       state are updated here. This includes stream parameters, Master(s)
 188       and Slave(s) runtime information associated with current stream.
 189
 190   (2) All the Master(s) and Slave(s) associated with current stream provide
 191       the port information to Bus which includes port numbers allocated by
 192       Master(s) and Slave(s) for current stream and their channel mask.
 193
 194 After all above operations are successful, stream state is set to
 195 ``SDW_STREAM_CONFIGURED``.
 196
 197 Bus implements below APIs for CONFIG state which needs to be called by
 198 the respective Master(s) and Slave(s) associated with stream. These APIs can
 199 only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM
 200 framework, this stream state is linked to .hw_params() operation.
 201
 202   .. code-block:: c
 203   int sdw_stream_add_master(struct sdw_bus * bus,
 204                 struct sdw_stream_config * stream_config,
 205                 struct sdw_ports_config * ports_config,
 206                 struct sdw_stream_runtime * stream);
 207
 208   int sdw_stream_add_slave(struct sdw_slave * slave,
 209                 struct sdw_stream_config * stream_config,
 210                 struct sdw_ports_config * ports_config,
 211                 struct sdw_stream_runtime * stream);
 212
 213
 214 SDW_STREAM_PREPARED
 215 ~~~~~~~~~~~~~~~~~~~
 216
 217 Prepare state of stream. Operations performed before entering in this state:
 218
 219   (1) Bus parameters such as bandwidth, frame shape, clock frequency,
 220       are computed based on current stream as well as already active
 221       stream(s) on Bus. Re-computation is required to accommodate current
 222       stream on the Bus.
 223
 224   (2) Transport and port parameters of all Master(s) and Slave(s) port(s) are
 225       computed for the current as well as already active stream based on frame
 226       shape and clock frequency computed in step 1.
 227
 228   (3) Computed Bus and transport parameters are programmed in Master(s) and
 229       Slave(s) registers. The banked registers programming is done on the
 230       alternate bank (bank currently unused). Port(s) are enabled for the
 231       already active stream(s) on the alternate bank (bank currently unused).
 232       This is done in order to not disrupt already active stream(s).
 233
 234   (4) Once all the values are programmed, Bus initiates switch to alternate
 235       bank where all new values programmed gets into effect.
 236
 237   (5) Ports of Master(s) and Slave(s) for current stream are prepared by
 238       programming PrepareCtrl register.
 239
 240 After all above operations are successful, stream state is set to
 241 ``SDW_STREAM_PREPARED``.
 242
 243 Bus implements below API for PREPARE state which needs to be called once per
 244 stream. From ASoC DPCM framework, this stream state is linked to
 245 .prepare() operation.
 246
 247   .. code-block:: c
 248   int sdw_prepare_stream(struct sdw_stream_runtime * stream);
 249
 250
 251 SDW_STREAM_ENABLED
 252 ~~~~~~~~~~~~~~~~~~
 253
 254 Enable state of stream. The data port(s) are enabled upon entering this state.
 255 Operations performed before entering in this state:
 256
 257   (1) All the values computed in SDW_STREAM_PREPARED state are programmed
 258       in alternate bank (bank currently unused). It includes programming of
 259       already active stream(s) as well.
 260
 261   (2) All the Master(s) and Slave(s) port(s) for the current stream are
 262       enabled on alternate bank (bank currently unused) by programming
 263       ChannelEn register.
 264
 265   (3) Once all the values are programmed, Bus initiates switch to alternate
 266       bank where all new values programmed gets into effect and port(s)
 267       associated with current stream are enabled.
 268
 269 After all above operations are successful, stream state is set to
 270 ``SDW_STREAM_ENABLED``.
 271
 272 Bus implements below API for ENABLE state which needs to be called once per
 273 stream. From ASoC DPCM framework, this stream state is linked to
 274 .trigger() start operation.
 275
 276   .. code-block:: c
 277   int sdw_enable_stream(struct sdw_stream_runtime * stream);
 278
 279 SDW_STREAM_DISABLED
 280 ~~~~~~~~~~~~~~~~~~~
 281
 282 Disable state of stream. The data port(s) are disabled upon exiting this state.
 283 Operations performed before entering in this state:
 284
 285   (1) All the Master(s) and Slave(s) port(s) for the current stream are
 286       disabled on alternate bank (bank currently unused) by programming
 287       ChannelEn register.
 288
 289   (2) All the current configuration of Bus and active stream(s) are programmed
 290       into alternate bank (bank currently unused).
 291
 292   (3) Once all the values are programmed, Bus initiates switch to alternate
 293       bank where all new values programmed gets into effect and port(s) associated
 294       with current stream are disabled.
 295
 296 After all above operations are successful, stream state is set to
 297 ``SDW_STREAM_DISABLED``.
 298
 299 Bus implements below API for DISABLED state which needs to be called once
 300 per stream. From ASoC DPCM framework, this stream state is linked to
 301 .trigger() stop operation.
 302
 303   .. code-block:: c
 304   int sdw_disable_stream(struct sdw_stream_runtime * stream);
 305
 306
 307 SDW_STREAM_DEPREPARED
 308 ~~~~~~~~~~~~~~~~~~~~~
 309
 310 De-prepare state of stream. Operations performed before entering in this
 311 state:
 312
 313   (1) All the port(s) of Master(s) and Slave(s) for current stream are
 314       de-prepared by programming PrepareCtrl register.
 315
 316   (2) The payload bandwidth of current stream is reduced from the total
 317       bandwidth requirement of bus and new parameters calculated and
 318       applied by performing bank switch etc.
 319
 320 After all above operations are successful, stream state is set to
 321 ``SDW_STREAM_DEPREPARED``.
 322
 323 Bus implements below API for DEPREPARED state which needs to be called once
 324 per stream. From ASoC DPCM framework, this stream state is linked to
 325 .trigger() stop operation.
 326
 327   .. code-block:: c
 328   int sdw_deprepare_stream(struct sdw_stream_runtime * stream);
 329
 330
 331 SDW_STREAM_RELEASED
 332 ~~~~~~~~~~~~~~~~~~~
 333
 334 Release state of stream. Operations performed before entering in this state:
 335
 336   (1) Release port resources for all Master(s) and Slave(s) port(s)
 337       associated with current stream.
 338
 339   (2) Release Master(s) and Slave(s) runtime resources associated with
 340       current stream.
 341
 342   (3) Release stream runtime resources associated with current stream.
 343
 344 After all above operations are successful, stream state is set to
 345 ``SDW_STREAM_RELEASED``.
 346
 347 Bus implements below APIs for RELEASE state which needs to be called by
 348 all the Master(s) and Slave(s) associated with stream. From ASoC DPCM
 349 framework, this stream state is linked to .hw_free() operation.
 350
 351   .. code-block:: c
 352   int sdw_stream_remove_master(struct sdw_bus * bus,
 353                 struct sdw_stream_runtime * stream);
 354   int sdw_stream_remove_slave(struct sdw_slave * slave,
 355                 struct sdw_stream_runtime * stream);
 356
 357
 358 The .shutdown() ASoC DPCM operation calls below Bus API to release
 359 stream assigned as part of ALLOCATED state.
 360
 361 In .shutdown() the data structure maintaining stream state are freed up.
 362
 363   .. code-block:: c
 364   void sdw_release_stream(struct sdw_stream_runtime * stream);
 365
 366 Not Supported
 367 =============
 368
 369 1. A single port with multiple channels supported cannot be used between two
 370 streams or across stream. For example a port with 4 channels cannot be used
 371 to handle 2 independent stereo streams even though it's possible in theory
 372 in SoundWire.