media/v4l/vidioc-reqbufs.rst

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
13 VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O
34 This ioctl is used to initiate :ref:`memory mapped <mmap>`,
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
48 the desired number of buffers, ``memory`` must be set to the requested
53 requested, even zero, when the driver runs out of free memory. A larger
62 buffers. Note that if any buffers are still mapped or exported via DMABUF,
76 .. flat-table:: struct v4l2_requestbuffers
77     :header-rows:  0
78     :stub-columns: 0
81     * - __u32
82       - ``count``
83       - The number of buffers requested or granted.
84     * - __u32
85       - ``type``
86       - Type of the stream or buffers, this is the same as the struct
89     * - __u32
90       - ``memory``
91       - Applications set this field to ``V4L2_MEMORY_MMAP``,
94     * - __u32
95       - ``capabilities``
96       - Set by the driver. If 0, then the driver doesn't support
102 	If you want to query the capabilities with a minimum of side-effects,
103 	then this can be called with ``count`` set to 0, ``memory`` set to
107     * - __u8
108       - ``flags``
109       - Specifies additional buffer management attributes.
110 	See :ref:`memory-flags`.
111     * - __u8
112       - ``reserved``\ [3]
113       - Reserved for future extensions.
115 .. _v4l2-buf-capabilities:
116 .. _V4L2-BUF-CAP-SUPPORTS-MMAP:
117 .. _V4L2-BUF-CAP-SUPPORTS-USERPTR:
118 .. _V4L2-BUF-CAP-SUPPORTS-DMABUF:
119 .. _V4L2-BUF-CAP-SUPPORTS-REQUESTS:
120 .. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS:
121 .. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF:
122 .. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS:
132 .. flat-table:: V4L2 Buffer Capabilities Flags
133     :header-rows:  0
134     :stub-columns: 0
137     * - ``V4L2_BUF_CAP_SUPPORTS_MMAP``
138       - 0x00000001
139       - This buffer type supports the ``V4L2_MEMORY_MMAP`` streaming mode.
140     * - ``V4L2_BUF_CAP_SUPPORTS_USERPTR``
141       - 0x00000002
142       - This buffer type supports the ``V4L2_MEMORY_USERPTR`` streaming mode.
143     * - ``V4L2_BUF_CAP_SUPPORTS_DMABUF``
144       - 0x00000004
145       - This buffer type supports the ``V4L2_MEMORY_DMABUF`` streaming mode.
146     * - ``V4L2_BUF_CAP_SUPPORTS_REQUESTS``
147       - 0x00000008
148       - This buffer type supports :ref:`requests <media-request-api>`.
149     * - ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS``
150       - 0x00000010
151       - The kernel allows calling :ref:`VIDIOC_REQBUFS` while buffers are still
152         mapped or exported via DMABUF. These orphaned buffers will be freed
154     * - ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF``
155       - 0x00000020
156       - Only valid for stateless decoders. If set, then userspace can set the
159     * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS``
160       - 0x00000040
161       - This capability is set by the driver to indicate that the queue supports
162         cache and memory management hints. However, it's only valid when the
163         queue is used for :ref:`memory mapping <mmap>` streaming I/O. See
164         :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>`,
165         :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>` and
166         :ref:`V4L2_MEMORY_FLAG_NON_COHERENT <V4L2-MEMORY-FLAG-NON-COHERENT>`.
175 On success 0 is returned, on error -1 and the ``errno`` variable is set
177 :ref:`Generic Error Codes <gen-errors>` chapter.
181     (``memory``) is not supported.