1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
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
14
15 Synopsis
16 ========
17
18 .. c:macro:: VIDIOC_REQBUFS
19
20 ``int ioctl(int fd, VIDIOC_REQBUFS, struct v4l
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_requestbuf
30
31 Description
32 ===========
33
34 This ioctl is used to initiate :ref:`memory ma
35 :ref:`user pointer <userp>` or :ref:`DMABUF <d
36 Memory mapped buffers are located in device me
37 with this ioctl before they can be mapped into
38 space. User buffers are allocated by applicati
39 ioctl is merely used to switch the driver into
40 to setup some internal structures. Similarly,
41 allocated by applications through a device dri
42 configures the driver into DMABUF I/O mode wit
43 allocation.
44
45 To allocate device buffers applications initia
46 struct :c:type:`v4l2_requestbuffers` structure
47 field to the respective stream or buffer type,
48 the desired number of buffers, ``memory`` must
49 I/O method and the ``reserved`` array must be
50 called with a pointer to this structure the dr
51 allocate the requested number of buffers and i
52 allocated in the ``count`` field. It can be sm
53 requested, even zero, when the driver runs out
54 number is also possible when the driver requir
55 function correctly. For example video output r
56 buffers, one displayed and one filled by the a
57
58 When the I/O method is not supported the ioctl
59 code.
60
61 Applications can call :ref:`VIDIOC_REQBUFS` ag
62 buffers. Note that if any buffers are still ma
63 then :ref:`VIDIOC_REQBUFS` can only succeed if
64 ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` capabi
65 :ref:`VIDIOC_REQBUFS` will return the ``EBUSY`
66 If ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` is
67 orphaned and will be freed when they are unmap
68 fds are closed. A ``count`` value of zero free
69 aborting or finishing any DMA in progress, an
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 gra
86 * - __u32
87 - ``type``
88 - Type of the stream or buffers, this is
89 :c:type:`v4l2_format` ``type`` field.
90 :c:type:`v4l2_buf_type` for valid valu
91 * - __u32
92 - ``memory``
93 - Applications set this field to ``V4L2_
94 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMOR
95 :c:type:`v4l2_memory`.
96 * - __u32
97 - ``capabilities``
98 - Set by the driver. If 0, then the driv
99 capabilities. In that case all you kno
100 guaranteed to support ``V4L2_MEMORY_MM
101 other :c:type:`v4l2_memory` types. It
102 capabilities.
103
104 If you want to query the capabilities
105 then this can be called with ``count``
106 ``V4L2_MEMORY_MMAP`` and ``type`` set
107 free any previously allocated buffers,
108 that will be done at the start of the
109 * - __u8
110 - ``flags``
111 - Specifies additional buffer management
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_M
136 * - ``V4L2_BUF_CAP_SUPPORTS_USERPTR``
137 - 0x00000002
138 - This buffer type supports the ``V4L2_M
139 * - ``V4L2_BUF_CAP_SUPPORTS_DMABUF``
140 - 0x00000004
141 - This buffer type supports the ``V4L2_M
142 * - ``V4L2_BUF_CAP_SUPPORTS_REQUESTS``
143 - 0x00000008
144 - This buffer type supports :ref:`reques
145 * - ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`
146 - 0x00000010
147 - The kernel allows calling :ref:`VIDIOC
148 mapped or exported via DMABUF. These o
149 when they are unmapped or when the exp
150 * - ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTU
151 - 0x00000020
152 - Only valid for stateless decoders. If
153 ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF``
154 capture buffer until the OUTPUT timest
155 * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HIN
156 - 0x00000040
157 - This capability is set by the driver t
158 cache and memory management hints. How
159 queue is used for :ref:`memory mapping
160 :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDAT
161 :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4
162 :ref:`V4L2_MEMORY_FLAG_NON_COHERENT <V
163 * - ``V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFER
164 - 0x00000080
165 - If set, then the ``max_num_buffers`` f
166 is valid. If not set, then the maximum
167 * - ``V4L2_BUF_CAP_SUPPORTS_REMOVE_BUFS``
168 - 0x00000100
169 - If set, then ``VIDIOC_REMOVE_BUFS`` is
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 cohere
182 coherent between the CPU and the bus)
183 latter can provide performance gains,
184 sync/flush operations can be avoided i
185 corresponding device only and the CPU
186 buffer. However, this requires extra c
187 guarantee memory consistency by issuin
188 consistency is needed. If this flag is
189 allocate the buffer in non-coherent me
190 only if the buffer is used for :ref:`m
191 queue reports the :ref:`V4L2_BUF_CAP_S
192 <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINT
193
194 .. raw:: latex
195
196 \normalsize
197
198 Return Value
199 ============
200
201 On success 0 is returned, on error -1 and the
202 appropriately. The generic error codes are des
203 :ref:`Generic Error Codes <gen-errors>` chapte
204
205 EINVAL
206 The buffer type (``type`` field) or the re
207 (``memory``) is not supported.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.