From 22a437cd6336193d8ffeb4217e9753fb92c7c870 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 7 Mar 2014 10:16:48 -0300 Subject: [PATCH] [media] DocBook media: clarify v4l2_buffer/plane fields Be more specific as to who has to fill in each field/flag: the driver or the application. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/io.xml | 54 +++++++++++++++++--------- 1 file changed, 36 insertions(+), 18 deletions(-) diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 49e48be9c2b4..0a5d8c6003cf 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -676,10 +676,11 @@ plane structures. __u32 index - Number of the buffer, set by the application. This -field is only used for memory mapping I/O -and can range from zero to the number of buffers allocated -with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; count) minus one. + Number of the buffer, set by the application except +when calling &VIDIOC-DQBUF;, then it is set by the driver. +This field can range from zero to the number of buffers allocated +with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; count), +plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one. __u32 @@ -698,7 +699,7 @@ linkend="v4l2-buf-type" /> buffer. It depends on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when type -refers to an input stream, applications when an output stream. +refers to an input stream, applications when it refers to an output stream. __u32 @@ -715,7 +716,7 @@ linkend="buffer-flags" />. buffer, see . This field is not used when the buffer contains VBI data. Drivers must set it when type refers to an input stream, -applications when an output stream. +applications when it refers to an output stream. struct timeval @@ -729,7 +730,9 @@ applications when an output stream. stores the time at which the last data byte was actually sent out in the timestamp field. This permits applications to monitor the drift between the video and system - clock. + clock. For output streams that use V4L2_BUF_FLAG_TIMESTAMP_COPY + the application has to fill in the timestamp which will be copied + by the driver to the capture stream. &v4l2-timecode; @@ -822,7 +825,8 @@ is the file descriptor associated with a DMABUF buffer. length Size of the buffer (not the payload) in bytes for the - single-planar API. For the multi-planar API the application sets + single-planar API. This is set by the driver based on the calls to + &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets this to the number of elements in the planes array. The driver will fill in the actual number of valid elements in that array. @@ -856,13 +860,15 @@ should set this to 0. bytesused The number of bytes occupied by data in the plane - (its payload). + (its payload). Drivers must set this field when type + refers to an input stream, applications when it refers to an output stream. __u32 length - Size in bytes of the plane (not its payload). + Size in bytes of the plane (not its payload). This is set by the driver + based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. union @@ -901,7 +907,9 @@ should set this to 0. __u32 data_offset - Offset in bytes to video data in the plane, if applicable. + Offset in bytes to video data in the plane. + Drivers must set this field when type + refers to an input stream, applications when it refers to an output stream. @@ -1031,7 +1039,7 @@ buffer cannot be on both queues at the same time, the V4L2_BUF_FLAG_QUEUED and V4L2_BUF_FLAG_DONE flag are mutually exclusive. They can be both cleared however, then the buffer is in "dequeued" -state, in the application domain to say so. +state, in the application domain so to say. V4L2_BUF_FLAG_ERROR @@ -1049,27 +1057,35 @@ state, in the application domain to say so. Drivers set or clear this flag when calling the VIDIOC_DQBUF ioctl. It may be set by video capture devices when the buffer contains a compressed image which is a -key frame (or field), &ie; can be decompressed on its own. +key frame (or field), &ie; can be decompressed on its own. Also know as +an I-frame. Applications can set this bit when type +refers to an output stream. V4L2_BUF_FLAG_PFRAME 0x00000010 Similar to V4L2_BUF_FLAG_KEYFRAME this flags predicted frames or fields which contain only differences to a -previous key frame. +previous key frame. Applications can set this bit when type +refers to an output stream. V4L2_BUF_FLAG_BFRAME 0x00000020 - Similar to V4L2_BUF_FLAG_PFRAME - this is a bidirectional predicted frame or field. [ooc tbd] + Similar to V4L2_BUF_FLAG_KEYFRAME +this flags a bi-directional predicted frame or field which contains only +the differences between the current frame and both the preceding and following +key frames to specify its content. Applications can set this bit when +type refers to an output stream. V4L2_BUF_FLAG_TIMECODE 0x00000100 The timecode field is valid. Drivers set or clear this flag when the VIDIOC_DQBUF -ioctl is called. +ioctl is called. Applications can set this bit and the corresponding +timecode structure when type +refers to an output stream. V4L2_BUF_FLAG_PREPARED @@ -1141,7 +1157,9 @@ in which case caches have not been used. the frame. Logical 'and' operation between the flags field and V4L2_BUF_FLAG_TSTAMP_SRC_MASK produces the - value of the timestamp source. + value of the timestamp source. Applications must set the timestamp + source when type refers to an output stream + and V4L2_BUF_FLAG_TIMESTAMP_COPY is set. V4L2_BUF_FLAG_TSTAMP_SRC_EOF -- 2.20.1