Re: [PATCH] media: docs: dev-decoder: add restrictions about CAPTURE buffers

[Tomasz Figa]

On Mon, Oct 18, 2021 at 6:14 PM Alexandre Courbot <acourbot@xxxxxxxxxxxx> wrote:
>
> CAPTURE buffers might be read by the hardware after they are dequeued,
> which goes against the general idea that userspace has full control over
> dequeued buffers. Explain why and document the restrictions that this
> implies for userspace.
>
> Signed-off-by: Alexandre Courbot <acourbot@xxxxxxxxxxxx>
> ---
>  .../userspace-api/media/v4l/dev-decoder.rst     | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst
> index 5b9b83feeceb..3cf2b496f2d0 100644
> --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst
> +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst
> @@ -752,6 +752,23 @@ available to dequeue. Specifically:
>       buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
>       timestamps will not retain the order of ``OUTPUT`` timestamps.
>
> +.. note::
> +
> +   The backing memory of ``CAPTURE`` buffers that are used as reference frames
> +   by the stream may be read by the hardware even after they are dequeued.
> +   Consequently, the client should avoid writing into this memory while the
> +   ``CAPTURE`` queue is streaming. Failure to observe this may result in
> +   corruption of decoded frames.
> +
> +   Similarly, when using a memory type other than ``V4L2_MEMORY_MMAP``, the
> +   client should make sure that each ``CAPTURE`` buffer is always queued with
> +   the same backing memory for as long as the ``CAPTURE`` queue is streaming.
> +   The reason for this is that V4L2 buffer indices can be used by drivers to
> +   identify frames. Thus, if the backing memory of a reference frame is
> +   submitted under a different buffer ID, the driver may misidentify it and
> +   decode a new frame into it while it is still in use, resulting in corruption
> +   of the following frames.
> +
>  During the decoding, the decoder may initiate one of the special sequences, as
>  listed below. The sequences will result in the decoder returning all the
>  ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
> --
> 2.33.0.1079.g6e70778dc9-goog
>

Acked-by: Tomasz Figa <tfiga@xxxxxxxxxxxx>

Best regards,
Tomasz