Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
MIME-Version: 1.0
References: <20190124100419.26492-1-tfiga@chromium.org> <20190124100419.26492-3-tfiga@chromium.org>
 <20190430193412.4291fca8@litschi.hi.pengutronix.de> <20190514081204.GA132745@chromium.org>
 <20190516103715.283face8@litschi.hi.pengutronix.de>
In-Reply-To: <20190516103715.283face8@litschi.hi.pengutronix.de>
From:   Tomasz Figa <tfiga@chromium.org>
Date:   Thu, 16 May 2019 17:48:07 +0900
Message-ID: <CAAFQd5BNvip1SGA21_C+ogB276jog2CupkKV3TZ_FUO90y0c=Q@mail.gmail.com>
Subject: Re: [PATCH v3 2/2] media: docs-rst: Document memory-to-memory video
 encoder interface
To:     Michael Tretter <m.tretter@pengutronix.de>
Cc:     Linux Media Mailing List <linux-media@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        Hans Verkuil <hverkuil@xs4all.nl>,
        Mauro Carvalho Chehab <mchehab@kernel.org>,
        Pawel Osciak <posciak@chromium.org>,
        Alexandre Courbot <acourbot@chromium.org>,
        Kamil Debski <kamil@wypas.org>,
        Andrzej Hajda <a.hajda@samsung.com>,
        Kyungmin Park <kyungmin.park@samsung.com>,
        Jeongtae Park <jtp.park@samsung.com>,
        Philipp Zabel <p.zabel@pengutronix.de>,
        =?UTF-8?B?VGlmZmFueSBMaW4gKOael+aFp+ePiik=?= 
        <tiffany.lin@mediatek.com>,
        =?UTF-8?B?QW5kcmV3LUNUIENoZW4gKOmZs+aZuui/qik=?= 
        <andrew-ct.chen@mediatek.com>,
        Stanimir Varbanov <stanimir.varbanov@linaro.org>,
        Todor Tomov <todor.tomov@linaro.org>,
        Nicolas Dufresne <nicolas@ndufresne.ca>,
        Paul Kocialkowski <paul.kocialkowski@bootlin.com>,
        Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
        dave.stevenson@raspberrypi.org,
        Ezequiel Garcia <ezequiel@collabora.com>,
        Maxime Jourdan <maxi.jourdan@wanadoo.fr>
Content-Type: text/plain; charset="UTF-8"
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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