Re: [PATCH v3 2/2] media: docs-rst: Document memory-to-memory video encoder interface

[Tomasz Figa <tfiga@chromium.org>]

On Thu, May 16, 2019 at 5:37 PM Michael Tretter
<m.tretter@pengutronix.de> wrote:
>
> On Tue, 14 May 2019 17:12:04 +0900, Tomasz Figa wrote:
> > Hi Michael,
> >
> > On Tue, Apr 30, 2019 at 07:34:12PM +0200, Michael Tretter wrote:
> > > On Thu, 24 Jan 2019 19:04:19 +0900, Tomasz Figa wrote:
> >
> > [snip]
> >
> > > > +State machine
> > > > +=============
> > > > +
> > > > +.. kernel-render:: DOT
> > > > +   :alt: DOT digraph of encoder state machine
> > > > +   :caption: Encoder state machine
> > > > +
> > > > +   digraph encoder_state_machine {
> > > > +       node [shape = doublecircle, label="Encoding"] Encoding;
> > > > +
> > > > +       node [shape = circle, label="Initialization"] Initialization;
> > > > +       node [shape = circle, label="Stopped"] Stopped;
> > > > +       node [shape = circle, label="Drain"] Drain;
> > > > +       node [shape = circle, label="Reset"] Reset;
> > > > +
> > > > +       node [shape = point]; qi
> > > > +       qi -> Initialization [ label = "open()" ];
> > > > +
> > > > +       Initialization -> Encoding [ label = "Both queues streaming" ];
> > > > +
> > > > +       Encoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
> > > > +       Encoding -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
> > > > +       Encoding -> Stopped [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > > +       Encoding -> Encoding;
> > > > +
> > > > +       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
> > >
> > > Shouldn't this be
> > >
> > >     Drain -> Stopped [ label = "All OUTPUT\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(OUTPUT)" ];
> > >
> > > ? While draining, the encoder continues encoding until all source
> > > buffers, i.e., buffers in the OUTPUT queue, are encoded or STREAMOFF
> > > happens on the OUTPUT queue. At the same time, the client continues to
> > > queue and dequeue buffers on the CAPTURE queue and there might be
> > > buffers queued on the CAPTURE queue even if the driver returned the
> > > buffer with the FLAG_LAST set and returns -EPIPE on further DQBUF
> > > requests.
> > >
> >
> > The STREAMOFF should be on OUTPUT indeed, because that immediately
> > removes any OUTPUT buffers from the queue, so there is nothing to be
> > encoded to wait for anymore.
> >
> > The "All OUTPUT buffers dequeued" part is correct, though. The last

I just realized that I made a typo here, sorry. It obviously should be
"All CAPTURE buffers dequeued", as per the existing spec draft and
rest of the sentence. Fortunately you seem to have figured that out.
:)

> > OUTPUT buffer in the flush sequence is considered encoded after the
> > application dequeues the corresponding CAPTURE buffer is dequeued and
> > that buffer is marked with the V4L2_BUF_FLAG_LAST flag.
>
> I understand. As the application continues to queue and dequeue buffers
> on the CAPTURE queue until it received the last CAPTURE buffer and cannot
> dequeue further CAPTURE buffers, "All CAPTURE buffers dequeued" is
> correct. Thanks for the clarification.
>
> Michael
>
> >
> > Best regards,
> > Tomasz
> >