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. +