From 8cee396bfa77ce3a2e5fe48f597206c1cd547f9c Mon Sep 17 00:00:00 2001 From: Philipp Zabel Date: Mon, 4 May 2015 07:51:04 -0300 Subject: [PATCH] [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 --- Documentation/DocBook/media/v4l/io.xml | 12 ++++++++++++ Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml | 12 +++++++++++- Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml | 10 +++++++++- Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 8 ++++++++ 4 files changed, 40 insertions(+), 2 deletions(-) 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_MASK 0x0000e000 Mask 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. + + -- 2.7.4