Re: [RFC 02/14] SoundWire: Add SoundWire stream documentation

[Charles Keepax <ckeepax@opensource.wolfsonmicro.com>]

On Fri, Oct 21, 2016 at 06:11:00PM +0530, Hardik Shah wrote:
> 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 @@
<snip>
> +
> +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     |
> +    |--------------|                     |--------------|     |--------------|
> +

One minor comment, this looks very similar to the clock
frameworks state model, but the clock framework calls it
unprepare would there be some milage in aligning to?

> +
> +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

A unique

> +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).
> +

This could probably use a little more explaination to show how it
differs from step 3/4 in PREPARE, as it looks like all the
computed values where applied there. I imagine this is just my lack
of understanding rather than an actual issue but even looking at
the code I am having a little difficulty tying up these two.

sdw_prepare_op
- sdw_compute_params (prepare step 1/2)
- sdw_program_params (prepare step 3)
- sdw_update_bus_params (prepare step 4)

sdw_enable_op
- sdw_program_params (enable step 1)
- sdw_update_bus_params (enable step 2)

It looks like the params are still basically the same as they
were when we called sdw_program_params in prepare.

> +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.
> +
> +

Thanks,
Charles