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