Audio Stream in SoundWire

Audio stream과 memory sample

Audio stream은 system memory buffer와 Codec, DSP memory buffer와 Codec, FIFO와 Codec 또는 Codec과 Codec 사이에 만드는 logical 또는 virtual connection입니다.

일반적으로 DMA channel이 data link를 통해 stream을 구동합니다. 하나의 audio stream에는 한 개 이상의 data channel이 들어가며, 같은 stream의 모든 channel은 sample rate와 sample size가 같아야 합니다.

SoundWire interface로 Left와 Right 두 channel의 stream을 열었다고 가정하면 system memory, DSP memory 또는 FIFO의 sample은 `L | R | L | R | L | R` 순서로 interleave될 수 있습니다.

=========================
Audio Stream in SoundWire
=========================

An audio stream is a logical or virtual connection created between

  (1) System memory buffer(s) and Codec(s)

  (2) DSP memory buffer(s) and Codec(s)

  (3) FIFO(s) and Codec(s)

  (4) Codec(s) and Codec(s)

which is typically driven by a DMA(s) channel through the data link. An
audio stream contains one or more channels of data. All channels within
stream must have same sample rate and same sample size.

Assume a stream with two channels (Left & Right) is opened using SoundWire
interface. Below are some ways a stream can be represented in SoundWire.

Stream Sample in memory (System memory, DSP memory or FIFOs) ::

        -------------------------
        | L | R | L | R | L | R |
        -------------------------

Example 1-2: 단일 port render와 capture

Example 1은 Master에서 Slave로 stereo stream을 render합니다. Master와 Slave가 각각 하나의 port를 사용하고, clock은 Master interface에서 Slave interface로 전달되며 L+R data도 같은 방향으로 흐릅니다.

Example 2는 Slave에서 Master로 stereo stream을 capture합니다. 두 endpoint 모두 single port를 사용하지만 data direction은 Slave에서 Master 쪽으로 반대가 됩니다. Clock signal 방향은 그대로 Master에서 Slave입니다.

Example 1: Stereo Stream with L and R channels is rendered from Master to
Slave. Both Master and Slave is using single port. ::

        +---------------+                    Clock Signal  +---------------+
        |    Master     +----------------------------------+     Slave     |
        |   Interface   |                                  |   Interface   |
        |               |                                  |       1       |
        |               |                     Data Signal  |               |
        |    L  +  R    +----------------------------------+    L  +  R    |
        |     (Data)    |     Data Direction               |     (Data)    |
        +---------------+  +----------------------->       +---------------+


Example 2: Stereo Stream with L and R channels is captured from Slave to
Master. Both Master and Slave is using single port. ::


        +---------------+                    Clock Signal  +---------------+
        |    Master     +----------------------------------+     Slave     |
        |   Interface   |                                  |   Interface   |
        |               |                                  |       1       |
        |               |                     Data Signal  |               |
        |    L  +  R    +----------------------------------+    L  +  R    |
        |     (Data)    |     Data Direction               |     (Data)    |
        +---------------+  <-----------------------+       +---------------+

Example 3-4: 여러 Slave의 channel 선택

Example 3에서는 Master가 L+R stereo를 render하고 서로 다른 두 Slave가 각각 한 channel만 받습니다. Master와 두 Slave는 모두 single port를 사용하며 Slave Interface 1은 L, Slave Interface 2는 R을 수신합니다.

Example 4에서도 Master가 L+R을 render하지만 두 Slave 모두 L+R 전체를 받습니다. 각 Slave는 static configuration 또는 dynamic orientation에 따라 L+R data를 local에서 처리하고 하나 이상의 speaker를 구동할 수 있습니다.

Example 3: Stereo Stream with L and R channels is rendered by Master. Each
of the L and R channel is received by two different Slaves. Master and both
Slaves are using single port. ::

        +---------------+                    Clock Signal  +---------------+
        |    Master     +---------+------------------------+     Slave     |
        |   Interface   |         |                        |   Interface   |
        |               |         |                        |       1       |
        |               |         |           Data Signal  |               |
        |    L  +  R    +---+------------------------------+       L       |
        |     (Data)    |   |     |    Data Direction      |     (Data)    |
        +---------------+   |     |   +------------->      +---------------+
                            |     |
                            |     |
                            |     |                        +---------------+
                            |     +----------------------> |     Slave     |
                            |                              |   Interface   |
                            |                              |       2       |
                            |                              |               |
                            +----------------------------> |       R       |
                                                           |     (Data)    |
                                                           +---------------+

Example 4: Stereo Stream with L and R channels is rendered by
Master. Both of the L and R channels are received by two different
Slaves. Master and both Slaves are using single port handling
L+R. Each Slave device processes the L + R data locally, typically
based on static configuration or dynamic orientation, and may drive
one or more speakers. ::

        +---------------+                    Clock Signal  +---------------+
        |    Master     +---------+------------------------+     Slave     |
        |   Interface   |         |                        |   Interface   |
        |               |         |                        |       1       |
        |               |         |           Data Signal  |               |
        |    L  +  R    +---+------------------------------+     L + R     |
        |     (Data)    |   |     |    Data Direction      |     (Data)    |
        +---------------+   |     |   +------------->      +---------------+
                            |     |
                            |     |
                            |     |                        +---------------+
                            |     +----------------------> |     Slave     |
                            |                              |   Interface   |
                            |                              |       2       |
                            |                              |               |
                            +----------------------------> |     L + R     |
                                                           |     (Data)    |
                                                           +---------------+

Example 5-6: 여러 port와 여러 Master

Example 5에서는 한 Master의 서로 다른 두 port가 L과 R을 각각 render하고, 한 Slave interface의 single port가 L+R을 함께 수신합니다. Master Data Port 1은 L, Data Port 2는 R을 제공합니다.

Example 6에서는 두 Master가 각각 한 channel을 render하고 두 Slave가 각각 한 channel을 받습니다. Master Interface 1과 Slave Interface 1은 L을, Master Interface 2와 Slave Interface 2는 R을 담당하며 모든 endpoint는 single port를 사용합니다.

Example 5: Stereo Stream with L and R channel is rendered by two different
Ports of the Master and is received by only single Port of the Slave
interface. ::

        +--------------------+
        |                    |
        |     +--------------+                             +----------------+
        |     |             ||                             |                |
        |     |  Data Port  ||  L Channel                  |                |
        |     |      1      |------------+                 |                |
        |     |  L Channel  ||           |                 +-----+----+     |
        |     |   (Data)    ||           |   L + R Channel ||    Data |     |
        | Master  +----------+           | +---+---------> ||    Port |     |
        | Interface          |           |                 ||     1   |     |
        |     +--------------+           |                 ||         |     |
        |     |             ||           |                 +----------+     |
        |     |  Data Port  |------------+                 |                |
        |     |      2      ||  R Channel                  |     Slave      |
        |     |  R Channel  ||                             |   Interface    |
        |     |   (Data)    ||                             |       1        |
        |     +--------------+         Clock Signal        |     L  +  R    |
        |                    +---------------------------> |      (Data)    |
        +--------------------+                             |                |
                                                           +----------------+

Example 6: Stereo Stream with L and R channel is rendered by 2 Masters, each
rendering one channel, and is received by two different Slaves, each
receiving one channel. Both Masters and both Slaves are using single port. ::

        +---------------+                    Clock Signal  +---------------+
        |    Master     +----------------------------------+     Slave     |
        |   Interface   |                                  |   Interface   |
        |       1       |                                  |       1       |
        |               |                     Data Signal  |               |
        |       L       +----------------------------------+       L       |
        |     (Data)    |     Data Direction               |     (Data)    |
        +---------------+  +----------------------->       +---------------+

        +---------------+                    Clock Signal  +---------------+
        |    Master     +----------------------------------+     Slave     |
        |   Interface   |                                  |   Interface   |
        |       2       |                                  |       2       |
        |               |                     Data Signal  |               |
        |       R       +----------------------------------+       R       |
        |     (Data)    |     Data Direction               |     (Data)    |
        +---------------+  +----------------------->       +---------------+

Example 7-8: Multi-link stream

Example 7에서는 두 Master가 각각 L+R을 render하고 각 Slave도 L+R을 받습니다. Application은 Example 4와 같지만 Slave가 별도 link에 배치됩니다.

Example 8은 4-channel stream을 두 Master가 각각 2 channel씩 render하는 구성입니다. Master Interface 1은 L1+R1을 Slave Interface 1로, Master Interface 2는 L2+R2를 Slave Interface 2로 전달합니다.

Example 7: Stereo Stream with L and R channel is rendered by 2
Masters, each rendering both channels. Each Slave receives L + R. This
is the same application as Example 4 but with Slaves placed on
separate links. ::

        +---------------+                    Clock Signal  +---------------+
        |    Master     +----------------------------------+     Slave     |
        |   Interface   |                                  |   Interface   |
        |       1       |                                  |       1       |
        |               |                     Data Signal  |               |
        |     L + R     +----------------------------------+     L + R     |
        |     (Data)    |     Data Direction               |     (Data)    |
        +---------------+  +----------------------->       +---------------+

        +---------------+                    Clock Signal  +---------------+
        |    Master     +----------------------------------+     Slave     |
        |   Interface   |                                  |   Interface   |
        |       2       |                                  |       2       |
        |               |                     Data Signal  |               |
        |     L + R     +----------------------------------+     L + R     |
        |     (Data)    |     Data Direction               |     (Data)    |
        +---------------+  +----------------------->       +---------------+

Example 8: 4-channel Stream is rendered by 2 Masters, each rendering a
2 channels. Each Slave receives 2 channels. ::

        +---------------+                    Clock Signal  +---------------+
        |    Master     +----------------------------------+     Slave     |
        |   Interface   |                                  |   Interface   |
        |       1       |                                  |       1       |
        |               |                     Data Signal  |               |
        |    L1 + R1    +----------------------------------+    L1 + R1    |
        |     (Data)    |     Data Direction               |     (Data)    |
        +---------------+  +----------------------->       +---------------+

        +---------------+                    Clock Signal  +---------------+
        |    Master     +----------------------------------+     Slave     |
        |   Interface   |                                  |   Interface   |
        |       2       |                                  |       2       |
        |               |                     Data Signal  |               |
        |     L2 + R2   +----------------------------------+    L2 + R2    |
        |     (Data)    |     Data Direction               |     (Data)    |
        +---------------+  +----------------------->       +---------------+

Multi-link lock, TDM slot과 bitSlot 제약

Note 1: 일반적인 multi-link locking이라면 global lock을 acquire한 다음 각 bus instance를 lock합니다. 그러나 caller framework인 ASoC DPCM이 한 card의 stream operation을 항상 serialize하므로 race condition이 없고 global lock이 필요하지 않습니다.

Note 2: Slave는 주어진 Stream에서 link로 전송되는 모든 channel을 받거나 일부만 받을 수 있습니다. 이 Slave configuration은 SoundWire subsystem API가 아니라 `snd_soc_dai_set_tdm_slot()` API로 처리하며 platform 또는 machine driver가 사용할 slot을 정합니다.

Example 4에서는 모든 Device가 같은 slot을 사용합니다. Example 3에서는 예를 들어 Slave Device1이 Slot 0을, Slave device2가 Slot 1을 사용합니다.

Note 3: 여러 Sink port는 SoundWire frame의 같은 bitSlot에서 같은 정보를 추출할 수 있지만 여러 Source port는 서로 다른 bitSlot configuration을 사용해야 합니다. 이는 I2S/PCM TDM과 같은 제약입니다.

Note1: In multi-link cases like above, to lock, one would acquire a global
lock and then go on locking bus instances. But, in this case the caller
framework(ASoC DPCM) guarantees that stream operations on a card are
always serialized. So, there is no race condition and hence no need for
global lock.

Note2: A Slave device may be configured to receive all channels
transmitted on a link for a given Stream (Example 4) or just a subset
of the data (Example 3). The configuration of the Slave device is not
handled by a SoundWire subsystem API, but instead by the
snd_soc_dai_set_tdm_slot() API. The platform or machine driver will
typically configure which of the slots are used. For Example 4, the
same slots would be used by all Devices, while for Example 3 the Slave
Device1 would use e.g. Slot 0 and Slave device2 slot 1.

Note3: Multiple Sink ports can extract the same information for the
same bitSlots in the SoundWire frame, however multiple Source ports
shall be configured with different bitSlot configurations. This is the
same limitation as with I2S/PCM TDM usages.

SoundWire Stream Management flow

Current stream과 Active stream

Current stream은 Prepare, Enable, Disable, De-prepare 같은 operation을 지금 수행해야 하는 stream입니다.

Active stream은 current stream 이외에 Bus에서 이미 active인 stream입니다. 하나의 Bus에는 active stream이 여러 개 존재할 수 있습니다.

SoundWire Bus는 Bus에서 render 또는 capture되는 각 stream의 operation을 관리하고, allocation과 release 사이의 상태를 stream별로 유지합니다.

================================

Stream definitions
------------------

  (1) Current stream: This is classified as the stream on which operation has
      to be performed like prepare, enable, disable, de-prepare etc.

  (2) Active stream: This is classified as the stream which is already active
      on Bus other than current stream. There can be multiple active streams
      on the Bus.

SoundWire Bus manages stream operations for each stream getting
rendered/captured on the SoundWire Bus. This section explains Bus operations
done for each of the stream allocated/released on Bus. Following are the
stream states maintained by the Bus for each of the audio stream.

Stream state와 transition

기본 lifecycle은 `SDW_STREAM_ALLOCATED`에서 `SDW_STREAM_CONFIGURED`, `SDW_STREAM_PREPARED`, `SDW_STREAM_ENABLED`로 진행하고, 정지 시 `SDW_STREAM_DISABLED`, `SDW_STREAM_DEPREPARED`, `SDW_STREAM_RELEASED`로 이동합니다.

ALSA/ASoC가 `INFO_PAUSE`를 지원할 때만 `SDW_STREAM_ENABLED`와 `SDW_STREAM_DISABLED` 사이 transition이 의미가 있습니다. `SDW_DISABLED_STATE`에서 `SDW_PREPARED_STATE`로 돌아가는 transition도 `INFO_RESUME` 지원에 의존합니다.

Framework는 기본 state transition을 검사하지만 특정 platform에서 DISABLED에서 ENABLED로의 transition이 유효한지는 검사하지 않습니다. 이런 검사는 ALSA/ASoC level에 추가해야 합니다.

SoundWire stream states
-----------------------

Below shows the SoundWire stream states and state transition diagram. ::

        +-----------+     +------------+     +----------+     +----------+
        | ALLOCATED +---->| CONFIGURED +---->| PREPARED +---->| ENABLED  |
        |   STATE   |     |    STATE   |     |  STATE   |     |  STATE   |
        +-----------+     +------------+     +---+--+---+     +----+-----+
                                                 ^  ^              ^
                                                 |  |              |
                                               __|  |___________   |
                                              |                 |  |
                                              v                 |  v
                 +----------+           +-----+------+        +-+--+-----+
                 | RELEASED |<----------+ DEPREPARED |<-------+ DISABLED |
                 |  STATE   |           |   STATE    |        |  STATE   |
                 +----------+           +------------+        +----------+

NOTE: State transitions between ``SDW_STREAM_ENABLED`` and
``SDW_STREAM_DISABLED`` are only relevant when then INFO_PAUSE flag is
supported at the ALSA/ASoC level. Likewise the transition between
``SDW_DISABLED_STATE`` and ``SDW_PREPARED_STATE`` depends on the
INFO_RESUME flag.

NOTE2: The framework implements basic state transition checks, but
does not e.g. check if a transition from DISABLED to ENABLED is valid
on a specific platform. Such tests need to be added at the ALSA/ASoC
level.

SDW_STREAM_ALLOCATED

`SDW_STREAM_ALLOCATED`는 stream의 entry state입니다. 먼저 이후 모든 stream operation의 reference가 되는 stream runtime을 allocate합니다.

그다음 stream runtime information을 보관할 resource를 allocate하고 initialize합니다. 여기에는 stream type인 PCM/PDM과 parameter, 연결된 Master·Slave interface, stream state 등 모든 stream 관련 정보가 포함됩니다.

모든 operation이 성공하면 state를 `SDW_STREAM_ALLOCATED`로 설정합니다.

Bus API `sdw_alloc_stream(char * stream_name, enum sdw_stream_type type)`은 stream마다 한 번 호출하며 ASoC DPCM의 `.startup()` operation과 연결할 수 있습니다.

SoundWire core의 `sdw_startup_stream()` helper는 일반적으로 dailink `.startup()` callback에서 호출합니다. 이 helper는 stream을 allocate하고 해당 stream에 연결된 모든 DAI의 stream pointer를 설정합니다.

Stream State Operations
-----------------------

Below section explains the operations done by the Bus on Master(s) and
Slave(s) as part of stream state transitions.

SDW_STREAM_ALLOCATED
~~~~~~~~~~~~~~~~~~~~

Allocation state for stream. This is the entry state
of the stream. Operations performed before entering in this state:

  (1) A stream runtime is allocated for the stream. This stream
      runtime is used as a reference for all the operations performed
      on the stream.

  (2) The resources required for holding stream runtime information are
      allocated and initialized. This holds all stream related information
      such as stream type (PCM/PDM) and parameters, Master and Slave
      interface associated with the stream, stream state etc.

After all above operations are successful, stream state is set to
``SDW_STREAM_ALLOCATED``.

Bus implements below API for allocate a stream which needs to be called once
per stream. From ASoC DPCM framework, this stream state maybe linked to
.startup() operation.

.. code-block:: c

  int sdw_alloc_stream(char * stream_name, enum sdw_stream_type type);

The SoundWire core provides a sdw_startup_stream() helper function,
typically called during a dailink .startup() callback, which performs
stream allocation and sets the stream pointer for all DAIs
connected to a stream.

SDW_STREAM_CONFIGURED

`SDW_STREAM_CONFIGURED`에 들어가기 전에 ALLOCATED state에서 만든 resource를 stream parameter와 current stream의 Master·Slave runtime information으로 update합니다.

Current stream에 연결된 모든 Master와 Slave는 할당한 port number와 channel mask를 포함한 port information을 Bus에 제공합니다.

모든 operation이 성공하면 state를 `SDW_STREAM_CONFIGURED`로 설정합니다.

각 Master와 Slave는 CONFIG state API를 각각 한 번만 호출할 수 있습니다. Master는 `sdw_stream_add_master()`, Slave는 `sdw_stream_add_slave()`를 사용하며 ASoC DPCM의 `.hw_params()` operation과 연결됩니다.

SDW_STREAM_CONFIGURED
~~~~~~~~~~~~~~~~~~~~~

Configuration state of stream. Operations performed before entering in
this state:

  (1) The resources allocated for stream information in SDW_STREAM_ALLOCATED
      state are updated here. This includes stream parameters, Master(s)
      and Slave(s) runtime information associated with current stream.

  (2) All the Master(s) and Slave(s) associated with current stream provide
      the port information to Bus which includes port numbers allocated by
      Master(s) and Slave(s) for current stream and their channel mask.

After all above operations are successful, stream state is set to
``SDW_STREAM_CONFIGURED``.

Bus implements below APIs for CONFIG state which needs to be called by
the respective Master(s) and Slave(s) associated with stream. These APIs can
only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM
framework, this stream state is linked to .hw_params() operation.

.. code-block:: c

  int sdw_stream_add_master(struct sdw_bus * bus,
                struct sdw_stream_config * stream_config,
                const struct sdw_ports_config * ports_config,
                struct sdw_stream_runtime * stream);

  int sdw_stream_add_slave(struct sdw_slave * slave,
                struct sdw_stream_config * stream_config,
                const struct sdw_ports_config * ports_config,
                struct sdw_stream_runtime * stream);

SDW_STREAM_PREPARED

Resume operation에서는 bus bandwidth를 이미 알고 있으므로 아래 1단계와 2단계를 생략합니다.

1단계에서는 current stream과 기존 active stream을 함께 고려해 bandwidth, frame shape, clock frequency 같은 Bus parameter를 다시 계산합니다. Current stream을 Bus에 수용하기 위해 re-computation이 필요합니다.

2단계에서는 1단계의 frame shape와 clock frequency를 바탕으로 current stream과 active stream의 모든 Master·Slave port에 대한 transport parameter와 port parameter를 계산합니다.

3단계에서는 계산한 Bus·transport parameter를 Master와 Slave register의 alternate bank에 program하고, 이미 active인 stream의 port도 alternate bank에서 enable합니다. 기존 active stream을 중단하지 않기 위한 절차입니다.

4단계에서는 Bus가 alternate bank로 switch해 새 값을 적용합니다. 5단계에서는 `PrepareCtrl` register를 program해 current stream의 Master·Slave port를 prepare합니다.

성공하면 state를 `SDW_STREAM_PREPARED`로 설정합니다. `sdw_prepare_stream()`은 stream마다 한 번 호출하며 ASoC DPCM `.prepare()`와 연결됩니다. `.trigger()`가 `.prepare()` 뒤에 오지 않을 수 있으므로 PREPARED에서 DEPREPARED로 직접 전이할 수 있습니다.

SDW_STREAM_PREPARED
~~~~~~~~~~~~~~~~~~~

Prepare state of stream. Operations performed before entering in this state:

  (0) Steps 1 and 2 are omitted in the case of a resume operation,
      where the bus bandwidth is known.

  (1) Bus parameters such as bandwidth, frame shape, clock frequency,
      are computed based on current stream as well as already active
      stream(s) on Bus. Re-computation is required to accommodate current
      stream on the Bus.

  (2) Transport and port parameters of all Master(s) and Slave(s) port(s) are
      computed for the current as well as already active stream based on frame
      shape and clock frequency computed in step 1.

  (3) Computed Bus and transport parameters are programmed in Master(s) and
      Slave(s) registers. The banked registers programming is done on the
      alternate bank (bank currently unused). Port(s) are enabled for the
      already active stream(s) on the alternate bank (bank currently unused).
      This is done in order to not disrupt already active stream(s).

  (4) Once all the values are programmed, Bus initiates switch to alternate
      bank where all new values programmed gets into effect.

  (5) Ports of Master(s) and Slave(s) for current stream are prepared by
      programming PrepareCtrl register.

After all above operations are successful, stream state is set to
``SDW_STREAM_PREPARED``.

Bus implements below API for PREPARE state which needs to be called
once per stream. From ASoC DPCM framework, this stream state is linked
to .prepare() operation. Since the .trigger() operations may not
follow the .prepare(), a direct transition from
``SDW_STREAM_PREPARED`` to ``SDW_STREAM_DEPREPARED`` is allowed.

.. code-block:: c

  int sdw_prepare_stream(struct sdw_stream_runtime * stream);

SDW_STREAM_ENABLED

`SDW_STREAM_ENABLED`에 들어가면 data port가 enable됩니다.

먼저 PREPARED state에서 계산한 모든 값과 기존 active stream의 설정을 alternate bank에 program합니다. 그다음 `ChannelEn` register를 program해 current stream의 모든 Master·Slave port를 alternate bank에서 enable합니다.

값을 모두 program한 뒤 Bus가 alternate bank로 switch하면 새 값이 적용되고 current stream port가 활성화됩니다. 성공하면 state를 `SDW_STREAM_ENABLED`로 설정합니다.

`sdw_enable_stream()`은 stream마다 한 번 호출하며 ASoC DPCM의 `.trigger()` start operation과 연결됩니다.

SDW_STREAM_ENABLED
~~~~~~~~~~~~~~~~~~

Enable state of stream. The data port(s) are enabled upon entering this state.
Operations performed before entering in this state:

  (1) All the values computed in SDW_STREAM_PREPARED state are programmed
      in alternate bank (bank currently unused). It includes programming of
      already active stream(s) as well.

  (2) All the Master(s) and Slave(s) port(s) for the current stream are
      enabled on alternate bank (bank currently unused) by programming
      ChannelEn register.

  (3) Once all the values are programmed, Bus initiates switch to alternate
      bank where all new values programmed gets into effect and port(s)
      associated with current stream are enabled.

After all above operations are successful, stream state is set to
``SDW_STREAM_ENABLED``.

Bus implements below API for ENABLE state which needs to be called once per
stream. From ASoC DPCM framework, this stream state is linked to
.trigger() start operation.

.. code-block:: c

  int sdw_enable_stream(struct sdw_stream_runtime * stream);

SDW_STREAM_DISABLED

DISABLED state로 들어갈 때 current stream의 data port를 disable합니다. 모든 Master·Slave port의 `ChannelEn` register를 alternate bank에서 program해 disable합니다.

현재 Bus configuration과 active stream configuration도 alternate bank에 program한 뒤 bank switch를 수행합니다. 새 값이 적용되면 current stream port가 disable되고 state를 `SDW_STREAM_DISABLED`로 설정합니다.

`sdw_disable_stream()`은 stream마다 한 번 호출하며 ASoC DPCM의 `.trigger()` stop operation과 연결됩니다.

`INFO_PAUSE`를 지원하면 DISABLED에서 ENABLED로 직접 전이할 수 있습니다. ASoC가 `.prepare()` callback을 쓰는 resume에서는 DISABLED에서 PREPARED로 전이해 필요한 설정을 복원하지만 bandwidth와 bit allocation은 update하지 않습니다.

SDW_STREAM_DISABLED
~~~~~~~~~~~~~~~~~~~

Disable state of stream. The data port(s) are disabled upon exiting this state.
Operations performed before entering in this state:

  (1) All the Master(s) and Slave(s) port(s) for the current stream are
      disabled on alternate bank (bank currently unused) by programming
      ChannelEn register.

  (2) All the current configuration of Bus and active stream(s) are programmed
      into alternate bank (bank currently unused).

  (3) Once all the values are programmed, Bus initiates switch to alternate
      bank where all new values programmed gets into effect and port(s) associated
      with current stream are disabled.

After all above operations are successful, stream state is set to
``SDW_STREAM_DISABLED``.

Bus implements below API for DISABLED state which needs to be called once
per stream. From ASoC DPCM framework, this stream state is linked to
.trigger() stop operation.

When the INFO_PAUSE flag is supported, a direct transition to
``SDW_STREAM_ENABLED`` is allowed.

For resume operations where ASoC will use the .prepare() callback, the
stream can transition from ``SDW_STREAM_DISABLED`` to
``SDW_STREAM_PREPARED``, with all required settings restored but
without updating the bandwidth and bit allocation.

.. code-block:: c

  int sdw_disable_stream(struct sdw_stream_runtime * stream);

SDW_STREAM_DEPREPARED

DEPREPARED state에 들어가기 전에 `PrepareCtrl` register를 program해 current stream의 모든 Master·Slave port를 de-prepare합니다.

Current stream의 payload bandwidth를 Bus의 total bandwidth requirement에서 빼고 새 parameter를 계산한 뒤 bank switch 등으로 적용합니다. 성공하면 state를 `SDW_STREAM_DEPREPARED`로 설정합니다.

`sdw_deprepare_stream()`은 stream마다 한 번 호출합니다. ALSA/ASoC에는 deprepare concept가 없으므로 이 state와 ALSA/ASoC operation의 mapping은 implementation-specific일 수 있습니다.

`INFO_PAUSE`를 지원하면 이 state는 `.hw_free()` operation과 연결되고 `TRIGGER_STOP`에서는 stream을 de-prepare하지 않습니다. 다른 구현은 PREPARED를 거치는 transition이 필요할 때 `TRIGGER_STOP`에서 DEPREPARED로 이동할 수 있습니다.

SDW_STREAM_DEPREPARED
~~~~~~~~~~~~~~~~~~~~~

De-prepare state of stream. Operations performed before entering in this
state:

  (1) All the port(s) of Master(s) and Slave(s) for current stream are
      de-prepared by programming PrepareCtrl register.

  (2) The payload bandwidth of current stream is reduced from the total
      bandwidth requirement of bus and new parameters calculated and
      applied by performing bank switch etc.

After all above operations are successful, stream state is set to
``SDW_STREAM_DEPREPARED``.

Bus implements below API for DEPREPARED state which needs to be called
once per stream. ALSA/ASoC do not have a concept of 'deprepare', and
the mapping from this stream state to ALSA/ASoC operation may be
implementation specific.

When the INFO_PAUSE flag is supported, the stream state is linked to
the .hw_free() operation - the stream is not deprepared on a
TRIGGER_STOP.

Other implementations may transition to the ``SDW_STREAM_DEPREPARED``
state on TRIGGER_STOP, should they require a transition through the
``SDW_STREAM_PREPARED`` state.

.. code-block:: c

  int sdw_deprepare_stream(struct sdw_stream_runtime * stream);

SDW_STREAM_RELEASED

RELEASED state에 들어가기 전에 current stream과 연결된 모든 Master·Slave port resource, Master·Slave runtime resource, stream runtime resource를 차례로 release합니다.

모든 operation이 성공하면 state를 `SDW_STREAM_RELEASED`로 설정합니다.

모든 연결된 Master와 Slave가 `sdw_stream_remove_master()` 또는 `sdw_stream_remove_slave()`를 호출해야 하며, ASoC DPCM의 `.hw_free()` operation과 연결됩니다.

`.shutdown()`은 ALLOCATED state에서 할당한 stream을 release하기 위해 `sdw_release_stream()`을 호출하고 stream state를 유지하던 data structure를 해제합니다.

SoundWire core의 `sdw_shutdown_stream()` helper는 일반적으로 dailink `.shutdown()` callback에서 호출합니다. 연결된 모든 DAI의 stream pointer를 clear하고 stream에 할당한 memory를 release합니다.

SDW_STREAM_RELEASED
~~~~~~~~~~~~~~~~~~~

Release state of stream. Operations performed before entering in this state:

  (1) Release port resources for all Master(s) and Slave(s) port(s)
      associated with current stream.

  (2) Release Master(s) and Slave(s) runtime resources associated with
      current stream.

  (3) Release stream runtime resources associated with current stream.

After all above operations are successful, stream state is set to
``SDW_STREAM_RELEASED``.

Bus implements below APIs for RELEASE state which needs to be called by
all the Master(s) and Slave(s) associated with stream. From ASoC DPCM
framework, this stream state is linked to .hw_free() operation.

.. code-block:: c

  int sdw_stream_remove_master(struct sdw_bus * bus,
                struct sdw_stream_runtime * stream);
  int sdw_stream_remove_slave(struct sdw_slave * slave,
                struct sdw_stream_runtime * stream);


The .shutdown() ASoC DPCM operation calls below Bus API to release
stream assigned as part of ALLOCATED state.

In .shutdown() the data structure maintaining stream state are freed up.

.. code-block:: c

  void sdw_release_stream(struct sdw_stream_runtime * stream);

The SoundWire core provides a sdw_shutdown_stream() helper function,
typically called during a dailink .shutdown() callback, which clears
the stream pointer for all DAIS connected to a stream and releases the
memory allocated for the stream.

지원하지 않는 port 공유

여러 channel을 지원하는 single port 하나를 두 stream 사이 또는 여러 stream에 걸쳐 사용할 수 없습니다.

예를 들어 이론적으로 SoundWire에서 가능하더라도 4-channel port 하나로 서로 독립적인 stereo stream 두 개를 처리할 수 없습니다.

Not Supported
=============

1. A single port with multiple channels supported cannot be used between two
   streams or across stream. For example a port with 4 channels cannot be used
   to handle 2 independent stereo streams even though it's possible in theory
   in SoundWire.