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/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
19 VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O
25 .. c:function:: int ioctl( int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp )
33 File descriptor returned by :ref:`open() <func-open>`.
36 Pointer to struct :c:type:`v4l2_requestbuffers`.
41 This ioctl is used to initiate :ref:`memory mapped <mmap>`,
42 :ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O.
43 Memory mapped buffers are located in device memory and must be allocated
44 with this ioctl before they can be mapped into the application's address
45 space. User buffers are allocated by applications themselves, and this
46 ioctl is merely used to switch the driver into user pointer I/O mode and
47 to setup some internal structures. Similarly, DMABUF buffers are
48 allocated by applications through a device driver, and this ioctl only
49 configures the driver into DMABUF I/O mode without performing any direct
52 To allocate device buffers applications initialize all fields of the
53 struct :c:type:`v4l2_requestbuffers` structure. They set the ``type``
54 field to the respective stream or buffer type, the ``count`` field to
55 the desired number of buffers, ``memory`` must be set to the requested
56 I/O method and the ``reserved`` array must be zeroed. When the ioctl is
57 called with a pointer to this structure the driver will attempt to
58 allocate the requested number of buffers and it stores the actual number
59 allocated in the ``count`` field. It can be smaller than the number
60 requested, even zero, when the driver runs out of free memory. A larger
61 number is also possible when the driver requires more buffers to
62 function correctly. For example video output requires at least two
63 buffers, one displayed and one filled by the application.
65 When the I/O method is not supported the ioctl returns an ``EINVAL`` error
68 Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of
69 buffers. Note that if any buffers are still mapped or exported via DMABUF,
70 then :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.
73 If ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` is set, then these buffers are
74 orphaned and will be freed when they are unmapped or when the exported DMABUF
75 fds are closed. A ``count`` value of zero frees or orphans all buffers, after
76 aborting or finishing any DMA in progress, an implicit
77 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`.
80 .. c:type:: v4l2_requestbuffers
82 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
84 .. flat-table:: struct v4l2_requestbuffers
91 - The number of buffers requested or granted.
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.
99 - Applications set this field to ``V4L2_MEMORY_MMAP``,
100 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
101 :c:type:`v4l2_memory`.
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 others
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.
117 - A place holder for future extensions. Drivers and applications
118 must set the array to zero.
120 .. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}|
122 .. _v4l2-buf-capabilities:
123 .. _V4L2-BUF-CAP-SUPPORTS-MMAP:
124 .. _V4L2-BUF-CAP-SUPPORTS-USERPTR:
125 .. _V4L2-BUF-CAP-SUPPORTS-DMABUF:
126 .. _V4L2-BUF-CAP-SUPPORTS-REQUESTS:
127 .. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS:
129 .. cssclass:: longtable
131 .. flat-table:: V4L2 Buffer Capabilities Flags
136 * - ``V4L2_BUF_CAP_SUPPORTS_MMAP``
138 - This buffer type supports the ``V4L2_MEMORY_MMAP`` streaming mode.
139 * - ``V4L2_BUF_CAP_SUPPORTS_USERPTR``
141 - This buffer type supports the ``V4L2_MEMORY_USERPTR`` streaming mode.
142 * - ``V4L2_BUF_CAP_SUPPORTS_DMABUF``
144 - This buffer type supports the ``V4L2_MEMORY_DMABUF`` streaming mode.
145 * - ``V4L2_BUF_CAP_SUPPORTS_REQUESTS``
147 - This buffer type supports :ref:`requests <media-request-api>`.
148 * - ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS``
150 - The kernel allows calling :ref:`VIDIOC_REQBUFS` while buffers are still
151 mapped or exported via DMABUF. These orphaned buffers will be freed
152 when they are unmapped or when the exported DMABUF fds are closed.
157 On success 0 is returned, on error -1 and the ``errno`` variable is set
158 appropriately. The generic error codes are described at the
159 :ref:`Generic Error Codes <gen-errors>` chapter.
162 The buffer type (``type`` field) or the requested I/O method
163 (``memory``) is not supported.