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     * - __u32
108       - ``reserved``\ [1]
109       - A place holder for future extensions. Drivers and applications
114 .. _v4l2-buf-capabilities:
115 .. _V4L2-BUF-CAP-SUPPORTS-MMAP:
116 .. _V4L2-BUF-CAP-SUPPORTS-USERPTR:
117 .. _V4L2-BUF-CAP-SUPPORTS-DMABUF:
118 .. _V4L2-BUF-CAP-SUPPORTS-REQUESTS:
119 .. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS:
120 .. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF:
121 .. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS:
125 .. flat-table:: V4L2 Buffer Capabilities Flags
126     :header-rows:  0
127     :stub-columns: 0
130     * - ``V4L2_BUF_CAP_SUPPORTS_MMAP``
131       - 0x00000001
132       - This buffer type supports the ``V4L2_MEMORY_MMAP`` streaming mode.
133     * - ``V4L2_BUF_CAP_SUPPORTS_USERPTR``
134       - 0x00000002
135       - This buffer type supports the ``V4L2_MEMORY_USERPTR`` streaming mode.
136     * - ``V4L2_BUF_CAP_SUPPORTS_DMABUF``
137       - 0x00000004
138       - This buffer type supports the ``V4L2_MEMORY_DMABUF`` streaming mode.
139     * - ``V4L2_BUF_CAP_SUPPORTS_REQUESTS``
140       - 0x00000008
141       - This buffer type supports :ref:`requests <media-request-api>`.
142     * - ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS``
143       - 0x00000010
144       - The kernel allows calling :ref:`VIDIOC_REQBUFS` while buffers are still
145         mapped or exported via DMABUF. These orphaned buffers will be freed
147     * - ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF``
148       - 0x00000020
149       - Only valid for stateless decoders. If set, then userspace can set the
152     * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS``
153       - 0x00000040
154       - This capability is set by the driver to indicate that the queue supports
155         cache and memory management hints. However, it's only valid when the
156         queue is used for :ref:`memory mapping <mmap>` streaming I/O. See
157         :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and
158         :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`.
163 On success 0 is returned, on error -1 and the ``errno`` variable is set
165 :ref:`Generic Error Codes <gen-errors>` chapter.
169     (``memory``) is not supported.