[PATCH v4 1/3] ALSA: compress: document the compress audio state machine

[Vinod Koul]

Hi Amadeusz,

On 29-06-20, 11:05, Amadeusz Sławiński wrote:
> 
> 
> On 6/29/2020 9:50 AM, Vinod Koul wrote:
> > So we had some discussions of the stream states, so I thought it is a
> > good idea to document the state transitions, so add it documentation
> > 
> > Reviewed-by: Charles Keepax <ckeepax at opensource.cirrus.com>
> > Signed-off-by: Vinod Koul <vkoul at kernel.org>
> > ---
> >   .../sound/designs/compress-offload.rst        | 51 +++++++++++++++++++
> >   1 file changed, 51 insertions(+)
> > 
> > diff --git a/Documentation/sound/designs/compress-offload.rst b/Documentation/sound/designs/compress-offload.rst
> > index ad4bfbdacc83..b6e9025ae105 100644
> > --- a/Documentation/sound/designs/compress-offload.rst
> > +++ b/Documentation/sound/designs/compress-offload.rst
> > @@ -151,6 +151,57 @@ Modifications include:
> >   - Addition of encoding options when required (derived from OpenMAX IL)
> >   - Addition of rateControlSupported (missing in OpenMAX AL)
> > +State Machine
> > +=============
> > +
> > +The compressed audio stream state machine is described below ::
> > +
> > +                                        +----------+
> > +                                        |          |
> > +                                        |   OPEN   |
> > +                                        |          |
> > +                                        +----------+
> > +                                             |
> > +                                             |
> > +                                             | compr_set_params()
> > +                                             |
> > +                                             v
> > +         compr_free()                   +----------+
> > +  +------------------------------------|          |
> > +  |                                    |   SETUP  |
> > +  |          +------------------------>|          |<-------------------------+
> > +  |          | compr_drain_notify()    +----------+                          |
> > +  |          |         or                   ^                                |
> > +  |          |      compr_stop()            |                                |
> > +  |          |                              | compr_write()                  |
> > +  |          |                              |                                |
> > +  |          |                              |                                |

Not sure, this is not in the version I posted, arrow is from setup ->
prepare. See https://lore.kernel.org/alsa-devel/20200629075002.11436-2-vkoul@kernel.org/

I don't know how it got reversed in your version, maybe the MUA messed
up??

> > +  |          |                         +----------+                          |
> > +  |          |                         |          |   compr_free()           |
> > +  |          |                         |  PREPARE |---------------> A        |
> > +  |          |                         |          |                          |
> > +  |          |                         +----------+                          |
> > +  |          |                              |                                |
> > +  |          |                              |                                |
> > +  |          |                              | compr_start()                  |
> > +  |          |                              |                                |
> > +  |          |                              v                                |
> > +  |    +----------+                    +----------+                          |
> > +  |    |          |    compr_drain()   |          |        compr_stop()      |
> > +  |    |  DRAIN   |<-------------------|  RUNNING |--------------------------+
> > +  |    |          |                    |          |                          |
> > +  |    +----------+                    +----------+                          |
> > +  |                                       |    ^                             |
> > +  |          A                            |    |                             |
> > +  |          |              compr_pause() |    | compr_resume()              |
> > +  |          |                            |    |                             |
> > +  |          v                            v    |                             |
> > +  |    +----------+                   +----------+                           |
> > +  |    |          |                   |          |         compr_stop()      |
> > +  +--->|   FREE   |                   |  PAUSE   |---------------------------+
> > +       |          |                   |          |
> > +       +----------+                   +----------+
> > +
> >   Gapless Playback
> >   ================
> > 
> 
> Line containing compr_free (between SETUP and FREE) seems to be misaligned?

not in the version I posted and see on lore

> If you move prepare to the left and drain in place of drain, it feels like
> you won't need this weird indirection with A

yeah that was a compromise to make it bit neater to me than adding
overlapping arrows...

> Something like:
> 
> >> +                                             v
> > > +         compr_free()                   +----------+
> > > +  +------------------------------------|          |
> > > +  |                                    |   SETUP  |
> > > +  |          +------------------------>|          |<-------------------------+
> > > +  |          | compr_write()           +----------+                          |
> > > +  |          |                              ^                                |
> > > +  |          |                              | compr_drain_notify() or        |
> > > +  |          |                              | compr_stop()                   |
> > > +  |          |                              |                                |
> > > +  |          |                              |                                |
> > > +  |          |                         +----------+                          |
> > > +  |          |                         |          |                          |
> > > +  |          |                         |  DRAIN   |                          |
> > > +  |          |                         |          |                          |
> > > +  |          |                         +----------+                          |
> > > +  |          |                              ^                                |
> > > +  |          |                              |                                |
> > > +  |          |                              | compr_drain()                  |
> > > +  |          |                              |                                |
> > > +  |          |                              |                                |
> > > +  |    +----------+                    +----------+                          |
> > > +  |    |          |    compr_start()   |          |        compr_stop()      |
> > > +  |    |  PREPARE |------------------->|  RUNNING |--------------------------+
> > > +  |    |          |                    |          |                          |
> > > +  |    +----------+                    +----------+                          |
> > > +  |          |                            |    ^                             |
> > > +  |          | compr_free()               |    |                             |
> > > +  |          |              compr_pause() |    | compr_resume()              |
> > > +  |          |                            |    |                             |
> > > +  |          v                            v    |                             |
> > > +  |    +----------+                   +----------+                           |
> > > +  |    |          |                   |          |         compr_stop()      |
> > > +  +--->|   FREE   |                   |  PAUSE   |---------------------------+
> > > +       |          |                   |          |
> > > +       +----------+                   +----------+
> > > +
> 

> but this makes me question PREPARE state, how do you enter it?

a compr_write() moves from SETUP -> PREPARE. Fixing that above looks
better version of mine..

-- 
~Vinod