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