1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _VIDIOC_CREATE_BUFS:
5
6************************
7ioctl VIDIOC_CREATE_BUFS
8************************
9
10Name
11====
12
13VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
14
15Synopsis
16========
17
18.. c:macro:: VIDIOC_CREATE_BUFS
19
20``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)``
21
22Arguments
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
31Description
32===========
33
34This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
35or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
36can be used as an alternative or in addition to the
37:ref:`VIDIOC_REQBUFS` ioctl, when a tighter control
38over buffers is required. This ioctl can be called multiple times to
39create buffers of different sizes.
40
41To allocate the device buffers applications must initialize the relevant
42fields 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``
45array must be zeroed.
46
47The ``format`` field specifies the image format that the buffers must be
48able 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
52requested format is supported by the driver. Based on the format's
53``type`` field the requested buffer size (for single-planar) or plane
54sizes (for multi-planar formats) will be used for the allocated buffers.
55The driver may return an error if the size(s) are not supported by the
56hardware (usually because they are too small).
57
58The buffers created by this ioctl will have as minimum size the size
59defined by the ``format.pix.sizeimage`` field (or the corresponding
60fields for other format types). Usually if the ``format.pix.sizeimage``
61field is less than the minimum required for the given format, then an
62error will be returned since drivers will typically not allow this. If
63it is larger, then the value will be used as-is. In other words, the
64driver may reject the requested size, but if it is accepted the driver
65will use it unchanged.
66
67When the ioctl is called with a pointer to this structure the driver
68will attempt to allocate up to the requested number of buffers and store
69the actual number allocated and the starting index in the ``count`` and
70the ``index`` fields respectively. On return ``count`` can be smaller
71than 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
120    * - __u32
121      - ``reserved``\ [6]
122      - A place holder for future extensions. Drivers and applications
123	must set the array to zero.
124
125Return Value
126============
127
128On success 0 is returned, on error -1 and the ``errno`` variable is set
129appropriately. The generic error codes are described at the
130:ref:`Generic Error Codes <gen-errors>` chapter.
131
132ENOMEM
133    No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
134
135EINVAL
136    The buffer type (``format.type`` field), requested I/O method
137    (``memory``) or format (``format`` field) is not valid.
138