summaryrefslogtreecommitdiff
path: root/Documentation/userspace-api
diff options
context:
space:
mode:
authorAlexandre Courbot <acourbot@chromium.org>2021-10-18 12:14:27 +0300
committerMauro Carvalho Chehab <mchehab+huawei@kernel.org>2021-11-30 14:03:23 +0300
commit4cfe98e647b1be8ac9ff06562959cf833b43e608 (patch)
treec835655d6fd917240baef49e3cdc7dfed83a6ad8 /Documentation/userspace-api
parentef054e345ed8c79ce1121a3599b5a2dfd78e57a0 (diff)
downloadlinux-4cfe98e647b1be8ac9ff06562959cf833b43e608.tar.xz
media: docs: dev-decoder: add restrictions about CAPTURE buffers
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@chromium.org> Acked-by: Tomasz Figa <tfiga@chromium.org> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Diffstat (limited to 'Documentation/userspace-api')
-rw-r--r--Documentation/userspace-api/media/v4l/dev-decoder.rst17
1 files changed, 17 insertions, 0 deletions
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