1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
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
14
15 Synopsis
16 ========
17
18 .. c:macro:: VIDIOC_CREATE_BUFS
19
20 ``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct
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_buf
30
31 Description
32 ===========
33
34 This ioctl is used to create buffers for :ref:
35 or :ref:`user pointer <userp>` or :ref:`DMA bu
36 can be used as an alternative or in addition t
37 :ref:`VIDIOC_REQBUFS` ioctl, when a tighter co
38 over buffers is required. This ioctl can be ca
39 create buffers of different sizes.
40
41 To allocate the device buffers applications mu
42 fields of the struct :c:type:`v4l2_create_buff
43 ``count`` field must be set to the number of r
44 ``memory`` field specifies the requested I/O m
45 array must be zeroed.
46
47 The ``format`` field specifies the image forma
48 able to handle. The application has to fill in
49 :c:type:`v4l2_format`. Usually this will be do
50 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or
51 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to e
52 requested format is supported by the driver. B
53 ``type`` field the requested buffer size (for
54 sizes (for multi-planar formats) will be used
55 The driver may return an error if the size(s)
56 hardware (usually because they are too small).
57
58 The buffers created by this ioctl will have as
59 defined by the ``format.pix.sizeimage`` field
60 fields for other format types). Usually if the
61 field is less than the minimum required for th
62 error will be returned since drivers will typi
63 it is larger, then the value will be used as-i
64 driver may reject the requested size, but if i
65 will use it unchanged.
66
67 When the ioctl is called with a pointer to thi
68 will attempt to allocate up to the requested n
69 the actual number allocated and the starting i
70 the ``index`` fields respectively. On return `
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
85 * - __u32
86 - ``count``
87 - The number of buffers requested or gra
88 :ref:`VIDIOC_CREATE_BUFS` will set ``i
89 created buffers, and it will check the
90 ``format.type``. If those are invalid
91 set to ``EINVAL`` error code, otherwis
92 0. It will never set errno to ``EBUSY`
93 case.
94 * - __u32
95 - ``memory``
96 - Applications set this field to ``V4L2_
97 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMOR
98 :c:type:`v4l2_memory`
99 * - struct :c:type:`v4l2_format`
100 - ``format``
101 - Filled in by the application, preserve
102 * - __u32
103 - ``capabilities``
104 - Set by the driver. If 0, then the driv
105 capabilities. In that case all you kno
106 guaranteed to support ``V4L2_MEMORY_MM
107 other :c:type:`v4l2_memory` types. It
108 capabilities. See :ref:`here <v4l2-buf
109 capabilities.
110
111 If you want to just query the capabili
112 other changes, then set ``count`` to 0
113 ``V4L2_MEMORY_MMAP`` and ``format.type
114
115 * - __u32
116 - ``flags``
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.
127 must set the array to zero.
128
129 Return Value
130 ============
131
132 On success 0 is returned, on error -1 and the
133 appropriately. The generic error codes are des
134 :ref:`Generic Error Codes <gen-errors>` chapte
135
136 ENOMEM
137 No memory to allocate buffers for :ref:`me
138
139 EINVAL
140 The buffer type (``format.type`` field), r
141 (``memory``) or format (``format`` field)
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.