[alsa-devel] [RFC 02/14] SoundWire: Add SoundWire stream documentation

[Pierre-Louis Bossart]

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

The SoundWire spec uses de-prepare, e.g. "De-prepare_Finished"
I'd rather stick to the wording between a spec and the implementation of 
said spec, rather than introduce a term/concept from an unrelated framework.
>
>> +
>> +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

ok

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

This last sentence makes no sense in this context, probably a copy/paste 
that shouldn't be there. The previously active streams remain active in 
this prepare step.

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

Yes, see above there was an extra sentence that isn't right.

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

The parameters are the same except for the channel-enable flags which 
are only programmed and activated via a bank switch in the enable step.