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 * - union { 116 - (anonymous) 117 * - __u32 118 - ``flags`` 119 - Specifies additional buffer management attributes. 120 See :ref:`memory-flags`. 121 * - __u32 122 - ``reserved``\ [1] 123 - Kept for backwards compatibility. Use ``flags`` instead. 124 * - } 125 - 126 127.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| 128 129.. _v4l2-buf-capabilities: 130.. _V4L2-BUF-CAP-SUPPORTS-MMAP: 131.. _V4L2-BUF-CAP-SUPPORTS-USERPTR: 132.. _V4L2-BUF-CAP-SUPPORTS-DMABUF: 133.. _V4L2-BUF-CAP-SUPPORTS-REQUESTS: 134.. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS: 135.. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF: 136.. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS: 137 138.. cssclass:: longtable 139 140.. flat-table:: V4L2 Buffer Capabilities Flags 141 :header-rows: 0 142 :stub-columns: 0 143 :widths: 3 1 4 144 145 * - ``V4L2_BUF_CAP_SUPPORTS_MMAP`` 146 - 0x00000001 147 - This buffer type supports the ``V4L2_MEMORY_MMAP`` streaming mode. 148 * - ``V4L2_BUF_CAP_SUPPORTS_USERPTR`` 149 - 0x00000002 150 - This buffer type supports the ``V4L2_MEMORY_USERPTR`` streaming mode. 151 * - ``V4L2_BUF_CAP_SUPPORTS_DMABUF`` 152 - 0x00000004 153 - This buffer type supports the ``V4L2_MEMORY_DMABUF`` streaming mode. 154 * - ``V4L2_BUF_CAP_SUPPORTS_REQUESTS`` 155 - 0x00000008 156 - This buffer type supports :ref:`requests <media-request-api>`. 157 * - ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` 158 - 0x00000010 159 - The kernel allows calling :ref:`VIDIOC_REQBUFS` while buffers are still 160 mapped or exported via DMABUF. These orphaned buffers will be freed 161 when they are unmapped or when the exported DMABUF fds are closed. 162 * - ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` 163 - 0x00000020 164 - Only valid for stateless decoders. If set, then userspace can set the 165 ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag to hold off on returning the 166 capture buffer until the OUTPUT timestamp changes. 167 * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS`` 168 - 0x00000040 169 - This capability is set by the driver to indicate that the queue supports 170 cache and memory management hints. However, it's only valid when the 171 queue is used for :ref:`memory mapping <mmap>` streaming I/O. See 172 :ref:`V4L2_FLAG_MEMORY_NON_CONSISTENT <V4L2-FLAG-MEMORY-NON-CONSISTENT>`, 173 :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and 174 :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`. 175 176 177Return Value 178============ 179 180On success 0 is returned, on error -1 and the ``errno`` variable is set 181appropriately. The generic error codes are described at the 182:ref:`Generic Error Codes <gen-errors>` chapter. 183 184EINVAL 185 The buffer type (``type`` field) or the requested I/O method 186 (``memory``) is not supported. 187