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