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