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