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