198 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_QBUF:5 6*******************************7ioctl VIDIOC_QBUF, VIDIOC_DQBUF8*******************************9 10Name11====12 13VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver14 15Synopsis16========17 18.. c:macro:: VIDIOC_QBUF19 20``int ioctl(int fd, VIDIOC_QBUF, struct v4l2_buffer *argp)``21 22.. c:macro:: VIDIOC_DQBUF23 24``int ioctl(int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp)``25 26Arguments27=========28 29``fd``30 File descriptor returned by :c:func:`open()`.31 32``argp``33 Pointer to struct :c:type:`v4l2_buffer`.34 35Description36===========37 38Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty39(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 struct43:c:type:`v4l2_buffer` to the same buffer type as was44previously used with struct :c:type:`v4l2_format` ``type``45and struct :c:type:`v4l2_requestbuffers` ``type``.46Applications must also set the ``index`` field. Valid index numbers47range from zero to the number of buffers allocated with48:ref:`VIDIOC_REQBUFS` (struct49:c:type:`v4l2_requestbuffers` ``count``) minus50one. The contents of the struct :c:type:`v4l2_buffer` returned51by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.52When the buffer is intended for output (``type`` is53``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,54or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the55``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`56for details. Applications must also set ``flags`` to 0. The57``reserved2`` and ``reserved`` fields must be set to 0. When using the58:ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must59contain a userspace pointer to a filled-in array of struct60:c:type:`v4l2_plane` and the ``length`` field must be set61to the number of elements in that array.62 63To enqueue a :ref:`memory mapped <mmap>` buffer applications set the64``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called65with a pointer to this structure the driver sets the66``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears67the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an68``EINVAL`` error code.69 70To enqueue a :ref:`user pointer <userp>` buffer applications set the71``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to72the address of the buffer and ``length`` to its size. When the73multi-planar API is used, ``m.userptr`` and ``length`` members of the74passed array of struct :c:type:`v4l2_plane` have to be used75instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure76the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the77``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the78``flags`` field, or it returns an error code. This ioctl locks the79memory pages of the buffer in physical memory, they cannot be swapped80out to disk. Buffers remain locked until dequeued, until the81:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or82:ref:`VIDIOC_REQBUFS` ioctl is called, or until the83device is closed.84 85To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the86``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a87file descriptor associated with a DMABUF buffer. When the multi-planar88API is used the ``m.fd`` fields of the passed array of struct89:c:type:`v4l2_plane` have to be used instead. When90``VIDIOC_QBUF`` is called with a pointer to this structure the driver91sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the92``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the93``flags`` field, or it returns an error code. This ioctl locks the94buffer. Locking a buffer means passing it to a driver for a hardware95access (usually DMA). If an application accesses (reads/writes) a locked96buffer then the result is undefined. Buffers remain locked until97dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or98:ref:`VIDIOC_REQBUFS` ioctl is called, or until the99device is closed.100 101The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to specify102the file descriptor of a :ref:`request <media-request-api>`, if requests are103in use. Setting it means that the buffer will not be passed to the driver104until the request itself is queued. Also, the driver will apply any105settings associated with the request for this buffer. This field will106be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set.107If the device does not support requests, then ``EBADR`` will be returned.108If requests are supported but an invalid request file descriptor is given,109then ``EINVAL`` will be returned.110 111.. caution::112 It is not allowed to mix queuing requests with queuing buffers directly.113 ``EBUSY`` will be returned if the first buffer was queued directly and114 then the application tries to queue a request, or vice versa. After115 closing the file descriptor, calling116 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS`117 the check for this will be reset.118 119 For :ref:`memory-to-memory devices <mem2mem>` you can specify the120 ``request_fd`` only for output buffers, not for capture buffers. Attempting121 to specify this for a capture buffer will result in an ``EBADR`` error.122 123Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled124(capturing) or displayed (output) buffer from the driver's outgoing125queue. They just set the ``type``, ``memory`` and ``reserved`` fields of126a struct :c:type:`v4l2_buffer` as above, when127``VIDIOC_DQBUF`` is called with a pointer to this structure the driver128fills all remaining fields or returns an error code. The driver may also129set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a130non-critical (recoverable) streaming error. In such case the application131may continue as normal, but should be aware that data in the dequeued132buffer might be corrupted. When using the multi-planar API, the planes133array must be passed in as well.134 135If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to136dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field137with a file descriptor numerically the same as the one given to ``VIDIOC_QBUF``138when the buffer was enqueued. No new file descriptor is created at dequeue time139and the value is only for the application convenience. When the multi-planar140API is used the ``m.fd`` fields of the passed array of struct141:c:type:`v4l2_plane` are filled instead.142 143By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing144queue. When the ``O_NONBLOCK`` flag was given to the145:c:func:`open()` function, ``VIDIOC_DQBUF`` returns146immediately with an ``EAGAIN`` error code when no buffer is available.147 148The struct :c:type:`v4l2_buffer` structure is specified in149:ref:`buffer`.150 151Return Value152============153 154On success 0 is returned, on error -1 and the ``errno`` variable is set155appropriately. The generic error codes are described at the156:ref:`Generic Error Codes <gen-errors>` chapter.157 158EAGAIN159 Non-blocking I/O has been selected using ``O_NONBLOCK`` and no160 buffer was in the outgoing queue.161 162EINVAL163 The buffer ``type`` is not supported, or the ``index`` is out of164 bounds, or no buffers have been allocated yet, or the ``userptr`` or165 ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was166 set but the given ``request_fd`` was invalid, or ``m.fd`` was167 an invalid DMABUF file descriptor.168 169EIO170 ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate171 temporary problems like signal loss.172 173 .. note::174 175 The driver might dequeue an (empty) buffer despite returning176 an error, or even stop capturing. Reusing such buffer may be unsafe177 though and its details (e.g. ``index``) may not be returned either.178 It is recommended that drivers indicate recoverable errors by setting179 the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the180 application should be able to safely reuse the buffer and continue181 streaming.182 183EPIPE184 ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem185 codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already186 dequeued and no new buffers are expected to become available.187 188EBADR189 The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not190 support requests for the given buffer type, or191 the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires192 that the buffer is part of a request.193 194EBUSY195 The first buffer was queued via a request, but the application now tries196 to queue it directly, or vice versa (it is not permitted to mix the two197 APIs).198