From: Philipp Zabel Date: Mon, 4 May 2015 10:51:04 +0000 (-0300) Subject: [media] DocBook media: document codec draining flow X-Git-Url: https://git.karo-electronics.de/?a=commitdiff_plain;h=8cee396bfa77ce3a2e5fe48f597206c1cd547f9c;p=linux-beck.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 1c17f802b471..cff2ffd3c8a6 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -1127,6 +1127,18 @@ passed on to a DMA-capable hardware unit for further processing or output. Typically applications shall use this flag for output buffers if the data 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 diff --git a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml index 9215627b04c7..73eb5cfe698a 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 0619ca5d2d36..fc1d4625a78c 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 3504a7f2f382..6cfc53b83a20 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. + +