upstream: [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 <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <m.chehab@samsung.com>

diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index 1e7ea3c..8d7afdb 100644 (file)
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -662,10 +662,11 @@ plane structures.</para>
            <entry>__u32</entry>
            <entry><structfield>index</structfield></entry>
            <entry></entry>
-           <entry>Number of the buffer, set by the application. This
-field is only used for <link linkend="mmap">memory mapping</link> I/O
-and can range from zero to the number of buffers allocated
-with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>
+           <entry>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; <structfield>count</structfield>),
+plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry>
          </row>
          <row>
            <entry>__u32</entry>
@@ -684,7 +685,7 @@ linkend="v4l2-buf-type" /></entry>
 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 <structfield>type</structfield>
-refers to an input stream, applications when an output stream.</entry>
+refers to an input stream, applications when it refers to an output stream.</entry>
          </row>
          <row>
            <entry>__u32</entry>
@@ -701,7 +702,7 @@ linkend="buffer-flags" />.</entry>
 buffer, see <xref linkend="v4l2-field" />. This field is not used when
 the buffer contains VBI data. Drivers must set it when
 <structfield>type</structfield> refers to an input stream,
-applications when an output stream.</entry>
+applications when it refers to an output stream.</entry>
          </row>
          <row>
            <entry>struct timeval</entry>
@@ -715,7 +716,9 @@ applications when an output stream.</entry>
            stores the time at which the last data byte was actually sent out
            in the  <structfield>timestamp</structfield> field. This permits
            applications to monitor the drift between the video and system
-           clock.</para></entry>
+           clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant>
+           the application has to fill in the timestamp which will be copied
+           by the driver to the capture stream.</para></entry>
          </row>
          <row>
            <entry>&v4l2-timecode;</entry>
@@ -808,7 +811,8 @@ is the file descriptor associated with a DMABUF buffer.</entry>
            <entry><structfield>length</structfield></entry>
            <entry></entry>
            <entry>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 <structfield>planes</structfield>
            array. The driver will fill in the actual number of valid elements in
            that array.
@@ -842,13 +846,15 @@ should set this to 0.</entry>
            <entry><structfield>bytesused</structfield></entry>
            <entry></entry>
            <entry>The number of bytes occupied by data in the plane
-           (its payload).</entry>
+             (its payload). Drivers must set this field when <structfield>type</structfield>
+             refers to an input stream, applications when it refers to an output stream.</entry>
          </row>
          <row>
            <entry>__u32</entry>
            <entry><structfield>length</structfield></entry>
            <entry></entry>
-           <entry>Size in bytes of the plane (not its payload).</entry>
+           <entry>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;.</entry>
          </row>
          <row>
            <entry>union</entry>
@@ -887,7 +893,9 @@ should set this to 0.</entry>
            <entry>__u32</entry>
            <entry><structfield>data_offset</structfield></entry>
            <entry></entry>
-           <entry>Offset in bytes to video data in the plane, if applicable.
+           <entry>Offset in bytes to video data in the plane.
+             Drivers must set this field when <structfield>type</structfield>
+             refers to an input stream, applications when it refers to an output stream.
            </entry>
          </row>
          <row>
@@ -1017,7 +1025,7 @@ buffer cannot be on both queues at the same time, the
 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
 They can be both cleared however, then the buffer is in "dequeued"
-state, in the application domain to say so.</entry>
+state, in the application domain so to say.</entry>
          </row>
          <row>
            <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
@@ -1035,27 +1043,35 @@ state, in the application domain to say so.</entry>
          <entry>Drivers set or clear this flag when calling the
 <constant>VIDIOC_DQBUF</constant> 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.</entry>
+key frame (or field), &ie; can be decompressed on its own. Also know as
+an I-frame.  Applications can set this bit when <structfield>type</structfield>
+refers to an output stream.</entry>
          </row>
          <row>
            <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
            <entry>0x00000010</entry>
            <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
 this flags predicted frames or fields which contain only differences to a
-previous key frame.</entry>
+previous key frame. Applications can set this bit when <structfield>type</structfield>
+refers to an output stream.</entry>
          </row>
          <row>
            <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
            <entry>0x00000020</entry>
-           <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>
-       this is a bidirectional predicted frame or field. [ooc tbd]</entry>
+           <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
+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
+<structfield>type</structfield> refers to an output stream.</entry>
          </row>
          <row>
            <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
            <entry>0x00000100</entry>
            <entry>The <structfield>timecode</structfield> field is valid.
 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
-ioctl is called.</entry>
+ioctl is called.  Applications can set this bit and the corresponding
+<structfield>timecode</structfield> structure when <structfield>type</structfield>
+refers to an output stream.</entry>
          </row>
          <row>
            <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>
@@ -1127,7 +1143,9 @@ in which case caches have not been used.</entry>
            the frame. Logical 'and' operation between the
            <structfield>flags</structfield> field and
            <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the
-           value of the timestamp source.</entry>
+           value of the timestamp source. Applications must set the timestamp
+           source when <structfield>type</structfield> refers to an output stream
+           and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry>
          </row>
          <row>
            <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry>