From 21636363be97725432591071d26dc0dca088ecbb Mon Sep 17 00:00:00 2001
From: Pawel Osciak
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
Signed-off-by: Kyungmin Park
Signed-off-by: Mauro Carvalho Chehab
---
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 bb685ed6fe7b..d424886beda0 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.
+
+ 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
diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml
index b843bd7b3897..ab691ebf3b93 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.
+
--
2.34.1