| Message ID | 1477053673-16021-3-git-send-email-hardik.t.shah@intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
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
>> +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.
On Mon, Nov 14, 2016 at 10:50:10AM -0600, Pierre-Louis Bossart wrote: > > >>+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. > > Cool we should leave that as is then :-) > >>+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. Ah ok that is what is getting pushed out there, thanks for explaining. Thanks, Charles
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.