lkml.org 
[lkml]   [2016]   [Oct]   [21]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[RFC 02/14] SoundWire: Add SoundWire stream documentation
    Date
    This patch adds stream documentation describing SoundWire stream and
    stream states.

    Signed-off-by: Hardik Shah <hardik.t.shah@intel.com>
    Signed-off-by: Sanyog Kale <sanyog.r.kale@intel.com>
    Reviewed-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
    ---
    Documentation/sound/alsa/sdw/stream.txt | 346 +++++++++++++++++++++++++++++++
    1 file changed, 346 insertions(+)
    create mode 100644 Documentation/sound/alsa/sdw/stream.txt

    diff --git a/Documentation/sound/alsa/sdw/stream.txt b/Documentation/sound/alsa/sdw/stream.txt
    new file mode 100644
    index 0000000..a1a2ed0
    --- /dev/null
    +++ b/Documentation/sound/alsa/sdw/stream.txt
    @@ -0,0 +1,346 @@
    +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 of different way 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: 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: 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 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 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 Slave
    +Interface 1 to Slave Interface 2. Master is driving the Clock. Audio
    +stream data flow is from Slave interface 1 to Slave Interface 2.
    +
    +
    + +---------------+
    ++---------------+ Clock Signal | |
    +| Master +--+----------------------------------> | Slave |
    +| Interface | | Data Signal | Interface |
    +| +--------+----------------------------+ | 1 |
    ++---------------+ | | | |
    + | | | L + R |
    + | | +----------------+ | (Data) |
    + | | | +---------------+
    + | | |
    + | | | Data Direction
    + | | | +---------------+
    + | | | | |
    + | | +----------------> | Slave |
    + | | | Interface |
    + | | Clock Signal | 2 |
    + | +------------------------------+ |
    + | Data Signal | L + R |
    + +------------------------------------+ (Data) |
    + +---------------+
    +
    +
    +SoundWire Stream Management flow
    +================================
    +
    +SoundWire 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 driver manages stream operations for each stream getting
    +rendered/captured on the SoundWire bus.
    +
    +This section explains what Bus driver operations are done for each of
    +the stream getting allocated/released on bus driver. Following are the
    +stream states maintained by the Bus driver for each of the audio stream
    +getting opened.
    +
    +
    +SoundWire stream states
    +=======================
    +Below figure shows the SoundWire stream states and possible state
    +transition diagram.
    +
    +|--------------| |-------------| |--------------| |--------------|
    +| ALLOC |---->| CONFIG |---->| PREPARE |---->| ENABLE |
    +| STATE | | STATE | | STATE | | STATE |
    +|--------------| |-------------| |--------------| |--------------|
    + ^ |
    + | |
    + | |
    + | |
    + | \/
    + |--------------| |--------------| |--------------|
    + | RELEASE |<--------------------| DEPREPARE |<----| DISABLE |
    + | STATE | | STATE | | STATE |
    + |--------------| |--------------| |--------------|
    +
    +
    +SoundWire Stream State Operations
    +==================================
    +Below section explains the operations done by the bus driver on
    +Master(s) and Slave(s) as part of stream state transitions.
    +
    +SDW_STATE_STRM_ALLOC: Allocation state for stream. This is the entry
    +state of the stream. Operations performed before entering in this
    +state:
    +1. An unique stream tag is assigned to stream. This stream tag is used
    +as a reference for all the operations performed on 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, reference counting, stream state etc.
    +
    +After all above operations are successful, stream state is set to
    +SDW_STATE_STRM_ALLOC.
    +
    +
    +SDW_STATE_STRM_CONFIG: Configuration state of stream. Operations
    +performed before entering in this state:
    +1. The resources allocated for stream information in
    +SDW_STATE_STRM_ALLOC state are updated. This includes stream parameters,
    +Masters and Slaves runtime information associated with the stream.
    +
    +2. All the Masters and Slaves associated with the stream updates the
    +port configuration to bus driver. This includes port numbers allocated
    +by Master(s) and Slave(s) for this stream.
    +
    +After all above operations are successful, stream state is set to
    +SDW_STATE_STRM_CONFIG.
    +
    +
    +SDW_STATE_STRM_PREPARE: Prepare state of stream. Operations performed
    +before entering in this state:
    +1. Bus parameters such as bandwidth, frame shape, clock frequency, SSP
    +interval are computed based on current stream as well as already active
    +streams on bus. Re-computation is required to accommodate current stream
    +on the bus.
    +
    +2. Transport parameters of all Master and Slave ports are computed for
    +the current as well as already active stream based on above calculated
    +frame shape and clock frequency.
    +
    +3. Computed bus and transport parameters are programmed in Master and
    +Slave registers. The banked registers programming is done on the
    +alternate bank (bank currently unused). Port channels are enabled for
    +the already active streams on the alternate bank (bank currently
    +unused). This is done in order to not to disrupt already active
    +stream(s).
    +
    +4. Once all the new values are programmed, bus initiates switch to
    +alternate bank. Once switch is successful, the port channels enabled on
    +previous bank for already active streams are disabled.
    +
    +5. Ports of Master and Slave for current stream are prepared.
    +
    +After all above operations are successful, stream state is set to
    +SDW_STATE_STRM_PREPARE.
    +
    +
    +SDW_STATE_STRM_ENABLE: Enable state of stream. Operations performed
    +before entering in this state:
    +1. All the values computed in SDW_STATE_STRM_PREPARE state are
    +programmed in alternate bank (bank currently unused). It includes
    +programming of already active streams as well.
    +
    +2. All the Master and Slave port channels for the current stream are
    +enabled on alternate bank (bank currently unused).
    +
    +3. Once all the new values are programmed, bus initiates switch to
    +alternate bank. Once the switch is successful, the port channels enabled
    +on previous bank for already active streams are disabled.
    +
    +After all above operations are successful, stream state is set to
    +SDW_STATE_STRM_ENABLE.
    +
    +
    +SDW_STATE_STRM_DISABLE --> Disable state of stream. Operations performed
    +before entering in this state:
    +1. Disable for Master and Slave ports channels is performed on on
    +alternate bank (bank currently unused) registers for current stream.
    +
    +2. All the current configuration of bus and Master and Slave ports are
    +programmed into alternate bank (bank currently unused). It includes
    +programming of already active streams port channels on alternate bank
    +(bank currently unused).
    +
    +3. Bus initiates switch to alternate bank. Once the switch is
    +successful, the port channels of current stream are disabled. All the
    +port channels enabled on previous bank for active stream are disabled.
    +
    +After all above operations are successful, stream state is set to
    +SDW_STATE_STRM_DISABLE.
    +
    +
    +SDW_STATE_STRM_DEPREPARE: De-prepare state of stream. Operations
    +performed before entering in this state:
    +1. Check the bandwidth required per Master. If its zero, de-prepare
    +current stream and move stream state to SDW_STATE_STRM_DEPREPARE, rest
    +of the steps are not required. If bandwidth required per Master is non
    +zero that means some more streams are running on Master and continue
    +with next step.
    +
    +2. Bus parameters and transport parameters are computed for the active
    +stream(s) on the given Master.
    +
    +3. All the computed values for active stream(s) are programmed into
    +alternate bank (bank currently unused) in Master and Slave registers.
    +
    +4. Bus initiates switch to alternate bank. Once the switch is
    +successful, all the port channels enabled on previous bank for active
    +stream are disabled.
    +
    +5. De-prepare ports of the Master and Slave associated with current
    +stream.
    +
    +After all above operations are successful, stream state is set to
    +SDW_STATE_DEPREPARE.
    +
    +
    +SDW_STATE_STRM_RELEASE: Release state of stream. Operations performed
    +before entering in this state:
    +1. Release port resources for all Master and Slave ports used for
    +current stream.
    +
    +2. Release Master and Slave runtime resources used for current stream.
    +
    +3. Release stream runtime resources used for current stream.
    +
    +After all above operations are successful, stream state is set to
    +SDW_STATE_STRM_RELEASE.
    +
    +Future Enhancements
    +===================
    +1. Slave to Slave communication: Currently stream between Slaves is not
    +supported. Master should be always part of the stream(s).
    +
    +2. Stream Linking for synchronized start: Currently multiple streams
    +cannot be synchronously started together with single bank switch. This
    +may require ASoC framework changes as well.
    +
    +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.
    +
    +2. Bandwidth allocation is done in contiguous slots for stream.
    +Non-contiguous slots created due to bandwidth fragmentation are not
    +taken care in bandwidth calculation.
    --
    1.7.9.5
    \
     
     \ /
      Last update: 2016-10-21 14:40    [W:3.110 / U:22.180 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site