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