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