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