aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Documentation/DocBook/v4l/io.xml10
-rw-r--r--Documentation/DocBook/v4l/vidioc-qbuf.xml14
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
@@ -702,6 +702,16 @@ They can be both cleared however, then the buffer is in "dequeued"
702state, in the application domain to say so.</entry> 702state, in the application domain to say so.</entry>
703 </row> 703 </row>
704 <row> 704 <row>
705 <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
706 <entry>0x0040</entry>
707 <entry>When this flag is set, the buffer has been dequeued
708 successfully, although the data might have been corrupted.
709 This is recoverable, streaming may continue as normal and
710 the buffer may be reused normally.
711 Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
712 ioctl is called.</entry>
713 </row>
714 <row>
705 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> 715 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
706 <entry>0x0008</entry> 716 <entry>0x0008</entry>
707 <entry>Drivers set or clear this flag when calling the 717 <entry>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 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
111and <structfield>reserved</structfield> 111and <structfield>reserved</structfield>
112fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant> 112fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
113is called with a pointer to this structure the driver fills the 113is called with a pointer to this structure the driver fills the
114remaining fields or returns an error code.</para> 114remaining fields or returns an error code. The driver may also set
115<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
116field. It indicates a non-critical (recoverable) streaming error. In such case
117the application may continue as normal, but should be aware that data in the
118dequeued buffer might be corrupted.</para>
115 119
116 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no 120 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
117buffer is in the outgoing queue. When the 121buffer is in the outgoing queue. When the
@@ -158,7 +162,13 @@ enqueue a user pointer buffer.</para>
158 <para><constant>VIDIOC_DQBUF</constant> failed due to an 162 <para><constant>VIDIOC_DQBUF</constant> failed due to an
159internal error. Can also indicate temporary problems like signal 163internal error. Can also indicate temporary problems like signal
160loss. Note the driver might dequeue an (empty) buffer despite 164loss. Note the driver might dequeue an (empty) buffer despite
161returning an error, or even stop capturing.</para> 165returning an error, or even stop capturing. Reusing such buffer may be unsafe
166though and its details (e.g. <structfield>index</structfield>) may not be
167returned either. It is recommended that drivers indicate recoverable errors
168by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
169In that case the application should be able to safely reuse the buffer and
170continue streaming.
171 </para>
162 </listitem> 172 </listitem>
163 </varlistentry> 173 </varlistentry>
164 </variablelist> 174 </variablelist>