Documentation/media/uapi/v4l/vidioc-qbuf.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_QBUF:
  11
  12 *******************************
  13 ioctl VIDIOC_QBUF, VIDIOC_DQBUF
  14 *******************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_QBUF, struct v4l2_buffer *argp )
  26     :name: VIDIOC_QBUF
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp )
  29     :name: VIDIOC_DQBUF
  30
  31
  32 Arguments
  33 =========
  34
  35 ``fd``
  36     File descriptor returned by :ref:`open() <func-open>`.
  37
  38 ``argp``
  39     Pointer to struct :c:type:`v4l2_buffer`.
  40
  41
  42 Description
  43 ===========
  44
  45 Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
  46 (capturing) or filled (output) buffer in the driver's incoming queue.
  47 The semantics depend on the selected I/O method.
  48
  49 To enqueue a buffer applications set the ``type`` field of a struct
  50 :c:type:`v4l2_buffer` to the same buffer type as was
  51 previously used with struct :c:type:`v4l2_format` ``type``
  52 and struct :c:type:`v4l2_requestbuffers` ``type``.
  53 Applications must also set the ``index`` field. Valid index numbers
  54 range from zero to the number of buffers allocated with
  55 :ref:`VIDIOC_REQBUFS` (struct
  56 :c:type:`v4l2_requestbuffers` ``count``) minus
  57 one. The contents of the struct :c:type:`v4l2_buffer` returned
  58 by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.
  59 When the buffer is intended for output (``type`` is
  60 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
  61 or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
  62 ``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
  63 for details. Applications must also set ``flags`` to 0. The
  64 ``reserved2`` and ``reserved`` fields must be set to 0. When using the
  65 :ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must
  66 contain a userspace pointer to a filled-in array of struct
  67 :c:type:`v4l2_plane` and the ``length`` field must be set
  68 to the number of elements in that array.
  69
  70 To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
  71 ``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
  72 with a pointer to this structure the driver sets the
  73 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
  74 the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
  75 ``EINVAL`` error code.
  76
  77 To enqueue a :ref:`user pointer <userp>` buffer applications set the
  78 ``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
  79 the address of the buffer and ``length`` to its size. When the
  80 multi-planar API is used, ``m.userptr`` and ``length`` members of the
  81 passed array of struct :c:type:`v4l2_plane` have to be used
  82 instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
  83 the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
  84 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
  85 ``flags`` field, or it returns an error code. This ioctl locks the
  86 memory pages of the buffer in physical memory, they cannot be swapped
  87 out to disk. Buffers remain locked until dequeued, until the
  88 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
  89 :ref:`VIDIOC_REQBUFS` ioctl is called, or until the
  90 device is closed.
  91
  92 To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
  93 ``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
  94 file descriptor associated with a DMABUF buffer. When the multi-planar
  95 API is used the ``m.fd`` fields of the passed array of struct
  96 :c:type:`v4l2_plane` have to be used instead. When
  97 ``VIDIOC_QBUF`` is called with a pointer to this structure the driver
  98 sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
  99 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
 100 ``flags`` field, or it returns an error code. This ioctl locks the
 101 buffer. Locking a buffer means passing it to a driver for a hardware
 102 access (usually DMA). If an application accesses (reads/writes) a locked
 103 buffer then the result is undefined. Buffers remain locked until
 104 dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
 105 :ref:`VIDIOC_REQBUFS` ioctl is called, or until the
 106 device is closed.
 107
 108 The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to specify
 109 the file descriptor of a :ref:`request <media-request-api>`, if requests are
 110 in use. Setting it means that the buffer will not be passed to the driver
 111 until the request itself is queued. Also, the driver will apply any
 112 settings associated with the request for this buffer. This field will
 113 be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set.
 114 If the device does not support requests, then ``EACCES`` will be returned.
 115 If requests are supported but an invalid request file descriptor is given,
 116 then ``EINVAL`` will be returned.
 117
 118 .. caution::
 119    It is not allowed to mix queuing requests with queuing buffers directly.
 120    ``EBUSY`` will be returned if the first buffer was queued directly and
 121    then the application tries to queue a request, or vice versa. After
 122    closing the file descriptor, calling
 123    :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS`
 124    the check for this will be reset.
 125
 126    For :ref:`memory-to-memory devices <codec>` you can specify the
 127    ``request_fd`` only for output buffers, not for capture buffers. Attempting
 128    to specify this for a capture buffer will result in an ``EACCES`` error.
 129
 130 Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
 131 (capturing) or displayed (output) buffer from the driver's outgoing
 132 queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
 133 a struct :c:type:`v4l2_buffer` as above, when
 134 ``VIDIOC_DQBUF`` is called with a pointer to this structure the driver
 135 fills the remaining fields or returns an error code. The driver may also
 136 set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a
 137 non-critical (recoverable) streaming error. In such case the application
 138 may continue as normal, but should be aware that data in the dequeued
 139 buffer might be corrupted. When using the multi-planar API, the planes
 140 array must be passed in as well.
 141
 142 By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
 143 queue. When the ``O_NONBLOCK`` flag was given to the
 144 :ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns
 145 immediately with an ``EAGAIN`` error code when no buffer is available.
 146
 147 The struct :c:type:`v4l2_buffer` structure is specified in
 148 :ref:`buffer`.
 149
 150
 151 Return Value
 152 ============
 153
 154 On success 0 is returned, on error -1 and the ``errno`` variable is set
 155 appropriately. The generic error codes are described at the
 156 :ref:`Generic Error Codes <gen-errors>` chapter.
 157
 158 EAGAIN
 159     Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
 160     buffer was in the outgoing queue.
 161
 162 EINVAL
 163     The buffer ``type`` is not supported, or the ``index`` is out of
 164     bounds, or no buffers have been allocated yet, or the ``userptr`` or
 165     ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was
 166     set but the the given ``request_fd`` was invalid, or ``m.fd`` was
 167     an invalid DMABUF file descriptor.
 168
 169 EIO
 170     ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
 171     temporary problems like signal loss.
 172
 173     .. note::
 174
 175        The driver might dequeue an (empty) buffer despite returning
 176        an error, or even stop capturing. Reusing such buffer may be unsafe
 177        though and its details (e.g. ``index``) may not be returned either.
 178        It is recommended that drivers indicate recoverable errors by setting
 179        the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
 180        application should be able to safely reuse the buffer and continue
 181        streaming.
 182
 183 EPIPE
 184     ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem
 185     codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already
 186     dequeued and no new buffers are expected to become available.
 187
 188 EACCES
 189     The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not
 190     support requests for the given buffer type.
 191
 192 EBUSY
 193     The first buffer was queued via a request, but the application now tries
 194     to queue it directly, or vice versa (it is not permitted to mix the two
 195     APIs).