142 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_CREATE_BUFS:5 6************************7ioctl VIDIOC_CREATE_BUFS8************************9 10Name11====12 13VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O14 15Synopsis16========17 18.. c:macro:: VIDIOC_CREATE_BUFS19 20``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)``21 22Arguments23=========24 25``fd``26 File descriptor returned by :c:func:`open()`.27 28``argp``29 Pointer to struct :c:type:`v4l2_create_buffers`.30 31Description32===========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. It36can be used as an alternative or in addition to the37:ref:`VIDIOC_REQBUFS` ioctl, when a tighter control38over buffers is required. This ioctl can be called multiple times to39create buffers of different sizes.40 41To allocate the device buffers applications must initialize the relevant42fields of the struct :c:type:`v4l2_create_buffers` structure. The43``count`` field must be set to the number of requested buffers, the44``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 be48able to handle. The application has to fill in this struct49:c:type:`v4l2_format`. Usually this will be done using the50:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or51:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the52requested format is supported by the driver. Based on the format's53``type`` field the requested buffer size (for single-planar) or plane54sizes (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 the56hardware (usually because they are too small).57 58The buffers created by this ioctl will have as minimum size the size59defined by the ``format.pix.sizeimage`` field (or the corresponding60fields for other format types). Usually if the ``format.pix.sizeimage``61field is less than the minimum required for the given format, then an62error will be returned since drivers will typically not allow this. If63it is larger, then the value will be used as-is. In other words, the64driver may reject the requested size, but if it is accepted the driver65will use it unchanged.66 67When the ioctl is called with a pointer to this structure the driver68will attempt to allocate up to the requested number of buffers and store69the actual number allocated and the starting index in the ``count`` and70the ``index`` fields respectively. On return ``count`` can be smaller71than the number requested.72 73.. c:type:: v4l2_create_buffers74 75.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|76 77.. flat-table:: struct v4l2_create_buffers78 :header-rows: 079 :stub-columns: 080 :widths: 1 1 281 82 * - __u3283 - ``index``84 - The starting buffer index, returned by the driver.85 * - __u3286 - ``count``87 - The number of buffers requested or granted. If count == 0, then88 :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of89 created buffers, and it will check the validity of ``memory`` and90 ``format.type``. If those are invalid -1 is returned and errno is91 set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns92 0. It will never set errno to ``EBUSY`` error code in this particular93 case.94 * - __u3295 - ``memory``96 - Applications set this field to ``V4L2_MEMORY_MMAP``,97 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See98 :c:type:`v4l2_memory`99 * - struct :c:type:`v4l2_format`100 - ``format``101 - Filled in by the application, preserved by the driver.102 * - __u32103 - ``capabilities``104 - Set by the driver. If 0, then the driver doesn't support105 capabilities. In that case all you know is that the driver is106 guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support107 other :c:type:`v4l2_memory` types. It will not support any other108 capabilities. See :ref:`here <v4l2-buf-capabilities>` for a list of the109 capabilities.110 111 If you want to just query the capabilities without making any112 other changes, then set ``count`` to 0, ``memory`` to113 ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type.114 115 * - __u32116 - ``flags``117 - Specifies additional buffer management attributes.118 See :ref:`memory-flags`.119 * - __u32120 - ``max_num_buffers``121 - If the V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS capability flag is set122 this field indicates the maximum possible number of buffers123 for this queue.124 * - __u32125 - ``reserved``\ [5]126 - A place holder for future extensions. Drivers and applications127 must set the array to zero.128 129Return Value130============131 132On success 0 is returned, on error -1 and the ``errno`` variable is set133appropriately. The generic error codes are described at the134:ref:`Generic Error Codes <gen-errors>` chapter.135 136ENOMEM137 No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.138 139EINVAL140 The buffer type (``format.type`` field), requested I/O method141 (``memory``) or format (``format`` field) is not valid.142