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/userspace-api/media/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _VIDIOC_REQBUFS: 11 12******************** 13ioctl VIDIOC_REQBUFS 14******************** 15 16Name 17==== 18 19VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O 20 21 22Synopsis 23======== 24 25.. c:function:: int ioctl( int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp ) 26 :name: VIDIOC_REQBUFS 27 28 29Arguments 30========= 31 32``fd`` 33 File descriptor returned by :ref:`open() <func-open>`. 34 35``argp`` 36 Pointer to struct :c:type:`v4l2_requestbuffers`. 37 38Description 39=========== 40 41This ioctl is used to initiate :ref:`memory mapped <mmap>`, 42:ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O. 43Memory mapped buffers are located in device memory and must be allocated 44with this ioctl before they can be mapped into the application's address 45space. User buffers are allocated by applications themselves, and this 46ioctl is merely used to switch the driver into user pointer I/O mode and 47to setup some internal structures. Similarly, DMABUF buffers are 48allocated by applications through a device driver, and this ioctl only 49configures the driver into DMABUF I/O mode without performing any direct 50allocation. 51 52To allocate device buffers applications initialize all fields of the 53struct :c:type:`v4l2_requestbuffers` structure. They set the ``type`` 54field to the respective stream or buffer type, the ``count`` field to 55the desired number of buffers, ``memory`` must be set to the requested 56I/O method and the ``reserved`` array must be zeroed. When the ioctl is 57called with a pointer to this structure the driver will attempt to 58allocate the requested number of buffers and it stores the actual number 59allocated in the ``count`` field. It can be smaller than the number 60requested, even zero, when the driver runs out of free memory. A larger 61number is also possible when the driver requires more buffers to 62function correctly. For example video output requires at least two 63buffers, one displayed and one filled by the application. 64 65When the I/O method is not supported the ioctl returns an ``EINVAL`` error 66code. 67 68Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of 69buffers. Note that if any buffers are still mapped or exported via DMABUF, 70then :ref:`VIDIOC_REQBUFS` can only succeed if the 71``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` capability is set. Otherwise 72:ref:`VIDIOC_REQBUFS` will return the ``EBUSY`` error code. 73If ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` is set, then these buffers are 74orphaned and will be freed when they are unmapped or when the exported DMABUF 75fds are closed. A ``count`` value of zero frees or orphans all buffers, after 76aborting or finishing any DMA in progress, an implicit 77:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`. 78 79 80.. c:type:: v4l2_requestbuffers 81 82.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 83 84.. flat-table:: struct v4l2_requestbuffers 85 :header-rows: 0 86 :stub-columns: 0 87 :widths: 1 1 2 88 89 * - __u32 90 - ``count`` 91 - The number of buffers requested or granted. 92 * - __u32 93 - ``type`` 94 - Type of the stream or buffers, this is the same as the struct 95 :c:type:`v4l2_format` ``type`` field. See 96 :c:type:`v4l2_buf_type` for valid values. 97 * - __u32 98 - ``memory`` 99 - Applications set this field to ``V4L2_MEMORY_MMAP``, 100 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See 101 :c:type:`v4l2_memory`. 102 * - __u32 103 - ``capabilities`` 104 - Set by the driver. If 0, then the driver doesn't support 105 capabilities. In that case all you know is that the driver is 106 guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support 107 other :c:type:`v4l2_memory` types. It will not support any other 108 capabilities. 109 110 If you want to query the capabilities with a minimum of side-effects, 111 then this can be called with ``count`` set to 0, ``memory`` set to 112 ``V4L2_MEMORY_MMAP`` and ``type`` set to the buffer type. This will 113 free any previously allocated buffers, so this is typically something 114 that will be done at the start of the application. 115 * - __u32 116 - ``reserved``\ [1] 117 - A place holder for future extensions. Drivers and applications 118 must set the array to zero. 119 120.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| 121 122.. _v4l2-buf-capabilities: 123.. _V4L2-BUF-CAP-SUPPORTS-MMAP: 124.. _V4L2-BUF-CAP-SUPPORTS-USERPTR: 125.. _V4L2-BUF-CAP-SUPPORTS-DMABUF: 126.. _V4L2-BUF-CAP-SUPPORTS-REQUESTS: 127.. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS: 128.. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF: 129.. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS: 130 131.. cssclass:: longtable 132 133.. flat-table:: V4L2 Buffer Capabilities Flags 134 :header-rows: 0 135 :stub-columns: 0 136 :widths: 3 1 4 137 138 * - ``V4L2_BUF_CAP_SUPPORTS_MMAP`` 139 - 0x00000001 140 - This buffer type supports the ``V4L2_MEMORY_MMAP`` streaming mode. 141 * - ``V4L2_BUF_CAP_SUPPORTS_USERPTR`` 142 - 0x00000002 143 - This buffer type supports the ``V4L2_MEMORY_USERPTR`` streaming mode. 144 * - ``V4L2_BUF_CAP_SUPPORTS_DMABUF`` 145 - 0x00000004 146 - This buffer type supports the ``V4L2_MEMORY_DMABUF`` streaming mode. 147 * - ``V4L2_BUF_CAP_SUPPORTS_REQUESTS`` 148 - 0x00000008 149 - This buffer type supports :ref:`requests <media-request-api>`. 150 * - ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` 151 - 0x00000010 152 - The kernel allows calling :ref:`VIDIOC_REQBUFS` while buffers are still 153 mapped or exported via DMABUF. These orphaned buffers will be freed 154 when they are unmapped or when the exported DMABUF fds are closed. 155 * - ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` 156 - 0x00000020 157 - Only valid for stateless decoders. If set, then userspace can set the 158 ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag to hold off on returning the 159 capture buffer until the OUTPUT timestamp changes. 160 * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS`` 161 - 0x00000040 162 - This capability is set by the driver to indicate that the queue supports 163 cache and memory management hints. However, it's only valid when the 164 queue is used for :ref:`memory mapping <mmap>` streaming I/O. See 165 :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and 166 :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`. 167 168 169Return Value 170============ 171 172On success 0 is returned, on error -1 and the ``errno`` variable is set 173appropriately. The generic error codes are described at the 174:ref:`Generic Error Codes <gen-errors>` chapter. 175 176EINVAL 177 The buffer type (``type`` field) or the requested I/O method 178 (``memory``) is not supported. 179