V4L/DVB: Add documentation for the new error flag

Add documentation for V4L2_BUF_FLAG_ERROR.

Signed-off-by: Pawel Osciak <p.osciak@samsung.com>
Signed-off-by: Kyungmin Park <kyungmin.park@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml
index bb685ed6fe7b311d3c7cf5c0fcdb64a701d0ff10..d424886beda051a7f9bbe6db441c1d76bdb62250 100644 (file)
--- a/Documentation/DocBook/v4l/io.xml
+++ b/Documentation/DocBook/v4l/io.xml
@@ -701,6 +701,16 @@ buffer cannot be on both queues at the same time, the
 They can be both cleared however, then the buffer is in "dequeued"
 state, in the application domain to say so.</entry>
          </row>
+         <row>
+           <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
+           <entry>0x0040</entry>
+           <entry>When this flag is set, the buffer has been dequeued
+           successfully, although the data might have been corrupted.
+           This is recoverable, streaming may continue as normal and
+           the buffer may be reused normally.
+           Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
+           ioctl is called.</entry>
+         </row>
          <row>
            <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
            <entry>0x0008</entry>

diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml
index b843bd7b389735725bd7d68954560509efe5cc41..ab691ebf3b9373969b95a2af7cac8d84663fc35a 100644 (file)
--- a/Documentation/DocBook/v4l/vidioc-qbuf.xml
+++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml
@@ -111,7 +111,11 @@ from the driver's outgoing queue. They just set the
 and <structfield>reserved</structfield>
 fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
 is called with a pointer to this structure the driver fills the
-remaining fields or returns an error code.</para>
+remaining fields or returns an error code. The driver may also set
+<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
+field. It indicates a non-critical (recoverable) streaming error. In such case
+the application may continue as normal, but should be aware that data in the
+dequeued buffer might be corrupted.</para>
 
     <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
 buffer is in the outgoing queue. When the
@@ -158,7 +162,13 @@ enqueue a user pointer buffer.</para>
          <para><constant>VIDIOC_DQBUF</constant> failed due to an
 internal error. Can also indicate temporary problems like signal
 loss. Note the driver might dequeue an (empty) buffer despite
-returning an error, or even stop capturing.</para>
+returning an error, or even stop capturing. Reusing such buffer may be unsafe
+though and its details (e.g. <structfield>index</structfield>) may not be
+returned either. It is recommended that drivers indicate recoverable errors
+by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
+In that case the application should be able to safely reuse the buffer and
+continue streaming.
+       </para>
        </listitem>
       </varlistentry>
     </variablelist>