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