1.. -*- coding: utf-8; mode: rst -*-
2
3.. _VIDIOC_QBUF:
4
5*******************************
6ioctl VIDIOC_QBUF, VIDIOC_DQBUF
7*******************************
8
9Name
10====
11
12VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver
13
14
15Synopsis
16========
17
18.. c:function:: int ioctl( int fd, VIDIOC_QBUF, struct v4l2_buffer *argp )
19    :name: VIDIOC_QBUF
20
21.. c:function:: int ioctl( int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp )
22    :name: VIDIOC_DQBUF
23
24
25Arguments
26=========
27
28``fd``
29    File descriptor returned by :ref:`open() <func-open>`.
30
31``argp``
32    Pointer to struct :c:type:`v4l2_buffer`.
33
34
35Description
36===========
37
38Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
39(capturing) or filled (output) buffer in the driver's incoming queue.
40The semantics depend on the selected I/O method.
41
42To enqueue a buffer applications set the ``type`` field of a struct
43:c:type:`v4l2_buffer` to the same buffer type as was
44previously used with struct :c:type:`v4l2_format` ``type``
45and struct :c:type:`v4l2_requestbuffers` ``type``.
46Applications must also set the ``index`` field. Valid index numbers
47range from zero to the number of buffers allocated with
48:ref:`VIDIOC_REQBUFS` (struct
49:c:type:`v4l2_requestbuffers` ``count``) minus
50one. The contents of the struct :c:type:`v4l2_buffer` returned
51by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.
52When the buffer is intended for output (``type`` is
53``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
54or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
55``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
56for details. Applications must also set ``flags`` to 0. The
57``reserved2`` and ``reserved`` fields must be set to 0. When using the
58:ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must
59contain a userspace pointer to a filled-in array of struct
60:c:type:`v4l2_plane` and the ``length`` field must be set
61to the number of elements in that array.
62
63To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
64``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
65with a pointer to this structure the driver sets the
66``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
67the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
68EINVAL error code.
69
70To enqueue a :ref:`user pointer <userp>` buffer applications set the
71``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
72the address of the buffer and ``length`` to its size. When the
73multi-planar API is used, ``m.userptr`` and ``length`` members of the
74passed array of struct :c:type:`v4l2_plane` have to be used
75instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
76the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
77``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
78``flags`` field, or it returns an error code. This ioctl locks the
79memory pages of the buffer in physical memory, they cannot be swapped
80out to disk. Buffers remain locked until dequeued, until the
81:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
82:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
83device is closed.
84
85To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
86``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
87file descriptor associated with a DMABUF buffer. When the multi-planar
88API is used the ``m.fd`` fields of the passed array of struct
89:c:type:`v4l2_plane` have to be used instead. When
90``VIDIOC_QBUF`` is called with a pointer to this structure the driver
91sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
92``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
93``flags`` field, or it returns an error code. This ioctl locks the
94buffer. Locking a buffer means passing it to a driver for a hardware
95access (usually DMA). If an application accesses (reads/writes) a locked
96buffer then the result is undefined. Buffers remain locked until
97dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
98:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
99device is closed.
100
101Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
102(capturing) or displayed (output) buffer from the driver's outgoing
103queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
104a struct :c:type:`v4l2_buffer` as above, when
105``VIDIOC_DQBUF`` is called with a pointer to this structure the driver
106fills the remaining fields or returns an error code. The driver may also
107set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a
108non-critical (recoverable) streaming error. In such case the application
109may continue as normal, but should be aware that data in the dequeued
110buffer might be corrupted. When using the multi-planar API, the planes
111array must be passed in as well.
112
113By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
114queue. When the ``O_NONBLOCK`` flag was given to the
115:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns
116immediately with an ``EAGAIN`` error code when no buffer is available.
117
118The struct :c:type:`v4l2_buffer` structure is specified in
119:ref:`buffer`.
120
121
122Return Value
123============
124
125On success 0 is returned, on error -1 and the ``errno`` variable is set
126appropriately. The generic error codes are described at the
127:ref:`Generic Error Codes <gen-errors>` chapter.
128
129EAGAIN
130    Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
131    buffer was in the outgoing queue.
132
133EINVAL
134    The buffer ``type`` is not supported, or the ``index`` is out of
135    bounds, or no buffers have been allocated yet, or the ``userptr`` or
136    ``length`` are invalid.
137
138EIO
139    ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
140    temporary problems like signal loss.
141
142    .. note::
143
144       The driver might dequeue an (empty) buffer despite returning
145       an error, or even stop capturing. Reusing such buffer may be unsafe
146       though and its details (e.g. ``index``) may not be returned either.
147       It is recommended that drivers indicate recoverable errors by setting
148       the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
149       application should be able to safely reuse the buffer and continue
150       streaming.
151
152EPIPE
153    ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem
154    codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already
155    dequeued and no new buffers are expected to become available.
156