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