0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_REQBUFS:
0005
0006 ********************
0007 ioctl VIDIOC_REQBUFS
0008 ********************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_REQBUFS
0019
0020 ``int ioctl(int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_requestbuffers`.
0030
0031 Description
0032 ===========
0033
0034 This ioctl is used to initiate :ref:`memory mapped <mmap>`,
0035 :ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O.
0036 Memory mapped buffers are located in device memory and must be allocated
0037 with this ioctl before they can be mapped into the application's address
0038 space. User buffers are allocated by applications themselves, and this
0039 ioctl is merely used to switch the driver into user pointer I/O mode and
0040 to setup some internal structures. Similarly, DMABUF buffers are
0041 allocated by applications through a device driver, and this ioctl only
0042 configures the driver into DMABUF I/O mode without performing any direct
0043 allocation.
0044
0045 To allocate device buffers applications initialize all fields of the
0046 struct :c:type:`v4l2_requestbuffers` structure. They set the ``type``
0047 field to the respective stream or buffer type, the ``count`` field to
0048 the desired number of buffers, ``memory`` must be set to the requested
0049 I/O method and the ``reserved`` array must be zeroed. When the ioctl is
0050 called with a pointer to this structure the driver will attempt to
0051 allocate the requested number of buffers and it stores the actual number
0052 allocated in the ``count`` field. It can be smaller than the number
0053 requested, even zero, when the driver runs out of free memory. A larger
0054 number is also possible when the driver requires more buffers to
0055 function correctly. For example video output requires at least two
0056 buffers, one displayed and one filled by the application.
0057
0058 When the I/O method is not supported the ioctl returns an ``EINVAL`` error
0059 code.
0060
0061 Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of
0062 buffers. Note that if any buffers are still mapped or exported via DMABUF,
0063 then :ref:`VIDIOC_REQBUFS` can only succeed if the
0064 ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` capability is set. Otherwise
0065 :ref:`VIDIOC_REQBUFS` will return the ``EBUSY`` error code.
0066 If ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` is set, then these buffers are
0067 orphaned and will be freed when they are unmapped or when the exported DMABUF
0068 fds are closed. A ``count`` value of zero frees or orphans all buffers, after
0069 aborting or finishing any DMA in progress, an implicit
0070 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`.
0071
0072 .. c:type:: v4l2_requestbuffers
0073
0074 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0075
0076 .. flat-table:: struct v4l2_requestbuffers
0077 :header-rows: 0
0078 :stub-columns: 0
0079 :widths: 1 1 2
0080
0081 * - __u32
0082 - ``count``
0083 - The number of buffers requested or granted.
0084 * - __u32
0085 - ``type``
0086 - Type of the stream or buffers, this is the same as the struct
0087 :c:type:`v4l2_format` ``type`` field. See
0088 :c:type:`v4l2_buf_type` for valid values.
0089 * - __u32
0090 - ``memory``
0091 - Applications set this field to ``V4L2_MEMORY_MMAP``,
0092 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
0093 :c:type:`v4l2_memory`.
0094 * - __u32
0095 - ``capabilities``
0096 - Set by the driver. If 0, then the driver doesn't support
0097 capabilities. In that case all you know is that the driver is
0098 guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support
0099 other :c:type:`v4l2_memory` types. It will not support any other
0100 capabilities.
0101
0102 If you want to query the capabilities with a minimum of side-effects,
0103 then this can be called with ``count`` set to 0, ``memory`` set to
0104 ``V4L2_MEMORY_MMAP`` and ``type`` set to the buffer type. This will
0105 free any previously allocated buffers, so this is typically something
0106 that will be done at the start of the application.
0107 * - __u8
0108 - ``flags``
0109 - Specifies additional buffer management attributes.
0110 See :ref:`memory-flags`.
0111 * - __u8
0112 - ``reserved``\ [3]
0113 - Reserved for future extensions.
0114
0115 .. _v4l2-buf-capabilities:
0116 .. _V4L2-BUF-CAP-SUPPORTS-MMAP:
0117 .. _V4L2-BUF-CAP-SUPPORTS-USERPTR:
0118 .. _V4L2-BUF-CAP-SUPPORTS-DMABUF:
0119 .. _V4L2-BUF-CAP-SUPPORTS-REQUESTS:
0120 .. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS:
0121 .. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF:
0122 .. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS:
0123
0124 .. raw:: latex
0125
0126 \footnotesize
0127
0128 .. tabularcolumns:: |p{8.1cm}|p{2.2cm}|p{7.0cm}|
0129
0130 .. cssclass:: longtable
0131
0132 .. flat-table:: V4L2 Buffer Capabilities Flags
0133 :header-rows: 0
0134 :stub-columns: 0
0135 :widths: 3 1 4
0136
0137 * - ``V4L2_BUF_CAP_SUPPORTS_MMAP``
0138 - 0x00000001
0139 - This buffer type supports the ``V4L2_MEMORY_MMAP`` streaming mode.
0140 * - ``V4L2_BUF_CAP_SUPPORTS_USERPTR``
0141 - 0x00000002
0142 - This buffer type supports the ``V4L2_MEMORY_USERPTR`` streaming mode.
0143 * - ``V4L2_BUF_CAP_SUPPORTS_DMABUF``
0144 - 0x00000004
0145 - This buffer type supports the ``V4L2_MEMORY_DMABUF`` streaming mode.
0146 * - ``V4L2_BUF_CAP_SUPPORTS_REQUESTS``
0147 - 0x00000008
0148 - This buffer type supports :ref:`requests <media-request-api>`.
0149 * - ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS``
0150 - 0x00000010
0151 - The kernel allows calling :ref:`VIDIOC_REQBUFS` while buffers are still
0152 mapped or exported via DMABUF. These orphaned buffers will be freed
0153 when they are unmapped or when the exported DMABUF fds are closed.
0154 * - ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF``
0155 - 0x00000020
0156 - Only valid for stateless decoders. If set, then userspace can set the
0157 ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag to hold off on returning the
0158 capture buffer until the OUTPUT timestamp changes.
0159 * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS``
0160 - 0x00000040
0161 - This capability is set by the driver to indicate that the queue supports
0162 cache and memory management hints. However, it's only valid when the
0163 queue is used for :ref:`memory mapping <mmap>` streaming I/O. See
0164 :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>`,
0165 :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>` and
0166 :ref:`V4L2_MEMORY_FLAG_NON_COHERENT <V4L2-MEMORY-FLAG-NON-COHERENT>`.
0167
0168 .. raw:: latex
0169
0170 \normalsize
0171
0172 Return Value
0173 ============
0174
0175 On success 0 is returned, on error -1 and the ``errno`` variable is set
0176 appropriately. The generic error codes are described at the
0177 :ref:`Generic Error Codes <gen-errors>` chapter.
0178
0179 EINVAL
0180 The buffer type (``type`` field) or the requested I/O method
0181 (``memory``) is not supported.
