From 21636363be97725432591071d26dc0dca088ecbb Mon Sep 17 00:00:00 2001
From: Pawel Osciak
Date: Wed, 28 Apr 2010 04:05:23 -0300
Subject: V4L/DVB: Add documentation for the new error flag
Add documentation for V4L2_BUF_FLAG_ERROR.
Signed-off-by: Pawel Osciak
Signed-off-by: Kyungmin Park
Signed-off-by: Mauro Carvalho Chehab
diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml
index bb685ed..d424886 100644
--- a/Documentation/DocBook/v4l/io.xml
+++ b/Documentation/DocBook/v4l/io.xml
@@ -702,6 +702,16 @@ They can be both cleared however, then the buffer is in "dequeued"
state, in the application domain to say so.
+ V4L2_BUF_FLAG_ERROR
+ 0x0040
+ 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 VIDIOC_DQBUF
+ ioctl is called.
+
+
V4L2_BUF_FLAG_KEYFRAME
0x0008
Drivers set or clear this flag when calling the
diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml
index b843bd7..ab691eb 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 reserved
fields of a &v4l2-buffer; as above, when VIDIOC_DQBUF
is called with a pointer to this structure the driver fills the
-remaining fields or returns an error code.
+remaining fields or returns an error code. The driver may also set
+V4L2_BUF_FLAG_ERROR in the flags
+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.
By default VIDIOC_DQBUF blocks when no
buffer is in the outgoing queue. When the
@@ -158,7 +162,13 @@ enqueue a user pointer buffer.
VIDIOC_DQBUF 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.
+returning an error, or even stop capturing. Reusing such buffer may be unsafe
+though and its details (e.g. index) may not be
+returned either. It is recommended that drivers indicate recoverable errors
+by setting the V4L2_BUF_FLAG_ERROR and returning 0 instead.
+In that case the application should be able to safely reuse the buffer and
+continue streaming.
+
--
cgit v0.10.2