1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _VIDIOC_CREATE_BUFS:
5
6 ************************
7 ioctl VIDIOC_CREATE_BUFS
8 ************************
9
10 Name
11 ====
12
13 VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
14
15 Synopsis
16 ========
17
18 .. c:macro:: VIDIOC_CREATE_BUFS
19
20 ``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)``
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_create_buffers`.
30
31 Description
32 ===========
33
34 This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
35 or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
36 can be used as an alternative or in addition to the
37 :ref:`VIDIOC_REQBUFS` ioctl, when a tighter control
38 over buffers is required. This ioctl can be called multiple times to
39 create buffers of different sizes.
40
41 To allocate the device buffers applications must initialize the relevant
42 fields of the struct :c:type:`v4l2_create_buffers` structure. The
43 ``count`` field must be set to the number of requested buffers, the
44 ``memory`` field specifies the requested I/O method and the ``reserved``
45 array must be zeroed.
46
47 The ``format`` field specifies the image format that the buffers must be
48 able to handle. The application has to fill in this struct
49 :c:type:`v4l2_format`. Usually this will be done using the
50 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or
51 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the
52 requested format is supported by the driver. Based on the format's
53 ``type`` field the requested buffer size (for single-planar) or plane
54 sizes (for multi-planar formats) will be used for the allocated buffers.
55 The driver may return an error if the size(s) are not supported by the
56 hardware (usually because they are too small).
57
58 The buffers created by this ioctl will have as minimum size the size
59 defined by the ``format.pix.sizeimage`` field (or the corresponding
60 fields for other format types). Usually if the ``format.pix.sizeimage``
61 field is less than the minimum required for the given format, then an
62 error will be returned since drivers will typically not allow this. If
63 it is larger, then the value will be used as-is. In other words, the
64 driver may reject the requested size, but if it is accepted the driver
65 will use it unchanged.
66
67 When the ioctl is called with a pointer to this structure the driver
68 will attempt to allocate up to the requested number of buffers and store
69 the actual number allocated and the starting index in the ``count`` and
70 the ``index`` fields respectively. On return ``count`` can be smaller
71 than the number requested.
72
73 .. c:type:: v4l2_create_buffers
74
75 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
76
77 .. flat-table:: struct v4l2_create_buffers
78 :header-rows: 0
79 :stub-columns: 0
80 :widths: 1 1 2
81
82 * - __u32
83 - ``index``
84 - The starting buffer index, returned by the driver.
85 * - __u32
86 - ``count``
87 - The number of buffers requested or granted. If count == 0, then
88 :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of
89 created buffers, and it will check the validity of ``memory`` and
90 ``format.type``. If those are invalid -1 is returned and errno is
91 set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns
92 0. It will never set errno to ``EBUSY`` error code in this particular
93 case.
94 * - __u32
95 - ``memory``
96 - Applications set this field to ``V4L2_MEMORY_MMAP``,
97 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
98 :c:type:`v4l2_memory`
99 * - struct :c:type:`v4l2_format`
100 - ``format``
101 - Filled in by the application, preserved by the driver.
102 * - __u32
103 - ``capabilities``
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 other
108 capabilities. See :ref:`here <v4l2-buf-capabilities>` for a list of the
109 capabilities.
110
111 If you want to just query the capabilities without making any
112 other changes, then set ``count`` to 0, ``memory`` to
113 ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type.
114
115 * - __u32
116 - ``flags``
117 - Specifies additional buffer management attributes.
118 See :ref:`memory-flags`.
119 * - __u32
120 - ``max_num_buffers``
121 - If the V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS capability flag is set
122 this field indicates the maximum possible number of buffers
123 for this queue.
124 * - __u32
125 - ``reserved``\ [5]
126 - A place holder for future extensions. Drivers and applications
127 must set the array to zero.
128
129 Return Value
130 ============
131
132 On success 0 is returned, on error -1 and the ``errno`` variable is set
133 appropriately. The generic error codes are described at the
134 :ref:`Generic Error Codes <gen-errors>` chapter.
135
136 ENOMEM
137 No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
138
139 EINVAL
140 The buffer type (``format.type`` field), requested I/O method
141 (``memory``) or format (``format`` field) is not valid.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.