Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst

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