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.7cm}| 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 - ``reserved``\ [7] 117 - A place holder for future extensions. Drivers and applications 118 must set the array to zero. 119 120Return Value 121============ 122 123On success 0 is returned, on error -1 and the ``errno`` variable is set 124appropriately. The generic error codes are described at the 125:ref:`Generic Error Codes <gen-errors>` chapter. 126 127ENOMEM 128 No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. 129 130EINVAL 131 The buffer type (``format.type`` field), requested I/O method 132 (``memory``) or format (``format`` field) is not valid. 133