Date: Mon, 4 May 2015 10:51:04 +0000 (-0300)
Subject: [media] DocBook media: document codec draining flow
X-Git-Tag: v4.2-rc8~12^2~402
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=8cee396bfa77ce3a2e5fe48f597206c1cd547f9c;p=platform%2Fkernel%2Flinux-exynos.git
[media] DocBook media: document codec draining flow
Document the interaction between VIDIOC_DECODER_CMD V4L2_DEC_CMD_STOP and
VIDIOC_ENCODER_CMD V4L2_ENC_CMD_STOP to start the draining, the V4L2_EVENT_EOS
event signalling all capture buffers are finished and ready to be dequeud,
the new V4L2_BUF_FLAG_LAST buffer flag indicating the last buffer being dequeued
from the capture queue, and the poll and VIDIOC_DQBUF ioctl return values once
the queue is drained.
Signed-off-by: Philipp Zabel
Acked-by: Hans Verkuil
Signed-off-by: Kamil Debski
Signed-off-by: Mauro Carvalho Chehab
---
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index 1c17f80..cff2ffd 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -1129,6 +1129,18 @@ in this buffer has not been created by the CPU but by some DMA-capable unit,
in which case caches have not been used.
+ V4L2_BUF_FLAG_LAST
+ 0x00100000
+ Last buffer produced by the hardware. mem2mem codec drivers
+set this flag on the capture queue for the last buffer when the
+VIDIOC_QUERYBUF or
+VIDIOC_DQBUF ioctl is called. Due to hardware
+limitations, the last buffer may be empty. In this case the driver will set the
+bytesused field to 0, regardless of the format. Any
+Any subsequent call to the VIDIOC_DQBUF ioctl
+will not block anymore, but return an &EPIPE;.
+
+ V4L2_BUF_FLAG_TIMESTAMP_MASK0x0000e000Mask for timestamp types below. To test the
diff --git a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml
index 9215627..73eb5cf 100644
--- a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml
@@ -197,7 +197,17 @@ be muted when playing back at a non-standard speed.
this command does nothing. This command has two flags:
if V4L2_DEC_CMD_STOP_TO_BLACK is set, then the decoder will
set the picture to black after it stopped decoding. Otherwise the last image will
-repeat. If V4L2_DEC_CMD_STOP_IMMEDIATELY is set, then the decoder
+repeat. mem2mem decoders will stop producing new frames altogether. They will send
+a V4L2_EVENT_EOS event when the last frame has been decoded
+and all frames are ready to be dequeued and will set the
+V4L2_BUF_FLAG_LAST buffer flag on the last buffer of the
+capture queue to indicate there will be no new buffers produced to dequeue. This
+buffer may be empty, indicated by the driver setting the
+bytesused field to 0. Once the
+V4L2_BUF_FLAG_LAST flag was set, the
+VIDIOC_DQBUF ioctl will not block anymore,
+but return an &EPIPE;.
+If V4L2_DEC_CMD_STOP_IMMEDIATELY is set, then the decoder
stops immediately (ignoring the pts value), otherwise it
will keep decoding until timestamp >= pts or until the last of the pending data from
its internal buffers was decoded.
diff --git a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
index 0619ca5..fc1d462 100644
--- a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
@@ -129,7 +129,15 @@ this command.
encoding will continue until the end of the current Group
Of Pictures, otherwise encoding will stop immediately.
When the encoder is already stopped, this command does
-nothing.
+nothing. mem2mem encoders will send a V4L2_EVENT_EOS event
+when the last frame has been decoded and all frames are ready to be dequeued and
+will set the V4L2_BUF_FLAG_LAST buffer flag on the last
+buffer of the capture queue to indicate there will be no new buffers produced to
+dequeue. This buffer may be empty, indicated by the driver setting the
+bytesused field to 0. Once the
+V4L2_BUF_FLAG_LAST flag was set, the
+VIDIOC_DQBUF ioctl will not block anymore,
+but return an &EPIPE;.
V4L2_ENC_CMD_PAUSE
diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
index 3504a7f..6cfc53b 100644
--- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
@@ -186,6 +186,14 @@ In that case the application should be able to safely reuse the buffer and
continue streaming.
+ EPIPE
+
+ VIDIOC_DQBUF returns this on an empty
+capture queue for mem2mem codecs if a buffer with the
+V4L2_BUF_FLAG_LAST was already dequeued and no new buffers
+are expected to become available.
+
+