0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_CREATE_BUFS:
0005
0006 ************************
0007 ioctl VIDIOC_CREATE_BUFS
0008 ************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_CREATE_BUFS
0019
0020 ``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_create_buffers`.
0030
0031 Description
0032 ===========
0033
0034 This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
0035 or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
0036 can be used as an alternative or in addition to the
0037 :ref:`VIDIOC_REQBUFS` ioctl, when a tighter control
0038 over buffers is required. This ioctl can be called multiple times to
0039 create buffers of different sizes.
0040
0041 To allocate the device buffers applications must initialize the relevant
0042 fields of the struct :c:type:`v4l2_create_buffers` structure. The
0043 ``count`` field must be set to the number of requested buffers, the
0044 ``memory`` field specifies the requested I/O method and the ``reserved``
0045 array must be zeroed.
0046
0047 The ``format`` field specifies the image format that the buffers must be
0048 able to handle. The application has to fill in this struct
0049 :c:type:`v4l2_format`. Usually this will be done using the
0050 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or
0051 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the
0052 requested format is supported by the driver. Based on the format's
0053 ``type`` field the requested buffer size (for single-planar) or plane
0054 sizes (for multi-planar formats) will be used for the allocated buffers.
0055 The driver may return an error if the size(s) are not supported by the
0056 hardware (usually because they are too small).
0057
0058 The buffers created by this ioctl will have as minimum size the size
0059 defined by the ``format.pix.sizeimage`` field (or the corresponding
0060 fields for other format types). Usually if the ``format.pix.sizeimage``
0061 field is less than the minimum required for the given format, then an
0062 error will be returned since drivers will typically not allow this. If
0063 it is larger, then the value will be used as-is. In other words, the
0064 driver may reject the requested size, but if it is accepted the driver
0065 will use it unchanged.
0066
0067 When the ioctl is called with a pointer to this structure the driver
0068 will attempt to allocate up to the requested number of buffers and store
0069 the actual number allocated and the starting index in the ``count`` and
0070 the ``index`` fields respectively. On return ``count`` can be smaller
0071 than the number requested.
0072
0073 .. c:type:: v4l2_create_buffers
0074
0075 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0076
0077 .. flat-table:: struct v4l2_create_buffers
0078 :header-rows: 0
0079 :stub-columns: 0
0080 :widths: 1 1 2
0081
0082 * - __u32
0083 - ``index``
0084 - The starting buffer index, returned by the driver.
0085 * - __u32
0086 - ``count``
0087 - The number of buffers requested or granted. If count == 0, then
0088 :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of
0089 created buffers, and it will check the validity of ``memory`` and
0090 ``format.type``. If those are invalid -1 is returned and errno is
0091 set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns
0092 0. It will never set errno to ``EBUSY`` error code in this particular
0093 case.
0094 * - __u32
0095 - ``memory``
0096 - Applications set this field to ``V4L2_MEMORY_MMAP``,
0097 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
0098 :c:type:`v4l2_memory`
0099 * - struct :c:type:`v4l2_format`
0100 - ``format``
0101 - Filled in by the application, preserved by the driver.
0102 * - __u32
0103 - ``capabilities``
0104 - Set by the driver. If 0, then the driver doesn't support
0105 capabilities. In that case all you know is that the driver is
0106 guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support
0107 other :c:type:`v4l2_memory` types. It will not support any other
0108 capabilities. See :ref:`here <v4l2-buf-capabilities>` for a list of the
0109 capabilities.
0110
0111 If you want to just query the capabilities without making any
0112 other changes, then set ``count`` to 0, ``memory`` to
0113 ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type.
0114
0115 * - __u32
0116 - ``flags``
0117 - Specifies additional buffer management attributes.
0118 See :ref:`memory-flags`.
0119
0120 * - __u32
0121 - ``reserved``\ [6]
0122 - A place holder for future extensions. Drivers and applications
0123 must set the array to zero.
0124
0125 Return Value
0126 ============
0127
0128 On success 0 is returned, on error -1 and the ``errno`` variable is set
0129 appropriately. The generic error codes are described at the
0130 :ref:`Generic Error Codes <gen-errors>` chapter.
0131
0132 ENOMEM
0133 No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
0134
0135 EINVAL
0136 The buffer type (``format.type`` field), requested I/O method
0137 (``memory``) or format (``format`` field) is not valid.
