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

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