From 21636363be97725432591071d26dc0dca088ecbb Mon Sep 17 00:00:00 2001
From: Pawel Osciak <p.osciak@samsung.com>
Date: Wed, 28 Apr 2010 04:05:23 -0300
Subject: [PATCH] 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>
---
Documentation/DocBook/v4l/io.xml | 10 ++++++++++
Documentation/DocBook/v4l/vidioc-qbuf.xml | 14 ++++++++++++--
2 files changed, 22 insertions(+), 2 deletions(-)
diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml
index bb685ed6fe7b3..d424886beda05 100644
--- 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 b843bd7b38973..ab691ebf3b937 100644
--- 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>
--
2.30.2