Documentation/media/uapi/v4l/vidioc-create-bufs.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_CREATE_BUFS:
  11
  12 ************************
  13 ioctl VIDIOC_CREATE_BUFS
  14 ************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp )
  26     :name: VIDIOC_CREATE_BUFS
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`v4l2_create_buffers`.
  37
  38
  39 Description
  40 ===========
  41
  42 This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
  43 or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
  44 can be used as an alternative or in addition to the
  45 :ref:`VIDIOC_REQBUFS` ioctl, when a tighter control
  46 over buffers is required. This ioctl can be called multiple times to
  47 create buffers of different sizes.
  48
  49 To allocate the device buffers applications must initialize the relevant
  50 fields of the struct :c:type:`v4l2_create_buffers` structure. The
  51 ``count`` field must be set to the number of requested buffers, the
  52 ``memory`` field specifies the requested I/O method and the ``reserved``
  53 array must be zeroed.
  54
  55 The ``format`` field specifies the image format that the buffers must be
  56 able to handle. The application has to fill in this struct
  57 :c:type:`v4l2_format`. Usually this will be done using the
  58 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or
  59 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the
  60 requested format is supported by the driver. Based on the format's
  61 ``type`` field the requested buffer size (for single-planar) or plane
  62 sizes (for multi-planar formats) will be used for the allocated buffers.
  63 The driver may return an error if the size(s) are not supported by the
  64 hardware (usually because they are too small).
  65
  66 The buffers created by this ioctl will have as minimum size the size
  67 defined by the ``format.pix.sizeimage`` field (or the corresponding
  68 fields for other format types). Usually if the ``format.pix.sizeimage``
  69 field is less than the minimum required for the given format, then an
  70 error will be returned since drivers will typically not allow this. If
  71 it is larger, then the value will be used as-is. In other words, the
  72 driver may reject the requested size, but if it is accepted the driver
  73 will use it unchanged.
  74
  75 When the ioctl is called with a pointer to this structure the driver
  76 will attempt to allocate up to the requested number of buffers and store
  77 the actual number allocated and the starting index in the ``count`` and
  78 the ``index`` fields respectively. On return ``count`` can be smaller
  79 than the number requested.
  80
  81
  82 .. c:type:: v4l2_create_buffers
  83
  84 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  85
  86 .. flat-table:: struct v4l2_create_buffers
  87     :header-rows:  0
  88     :stub-columns: 0
  89     :widths:       1 1 2
  90
  91     * - __u32
  92       - ``index``
  93       - The starting buffer index, returned by the driver.
  94     * - __u32
  95       - ``count``
  96       - The number of buffers requested or granted. If count == 0, then
  97         :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of
  98         created buffers, and it will check the validity of ``memory`` and
  99         ``format.type``. If those are invalid -1 is returned and errno is
 100         set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns
 101         0. It will never set errno to ``EBUSY`` error code in this particular
 102         case.
 103     * - __u32
 104       - ``memory``
 105       - Applications set this field to ``V4L2_MEMORY_MMAP``,
 106         ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
 107         :c:type:`v4l2_memory`
 108     * - struct :c:type:`v4l2_format`
 109       - ``format``
 110       - Filled in by the application, preserved by the driver.
 111     * - __u32
 112       - ``capabilities``
 113       - Set by the driver. If 0, then the driver doesn't support
 114         capabilities. In that case all you know is that the driver is
 115         guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support
 116         other :c:type:`v4l2_memory` types. It will not support any others
 117         capabilities. See :ref:`here <v4l2-buf-capabilities>` for a list of the
 118         capabilities.
 119
 120         If you want to just query the capabilities without making any
 121         other changes, then set ``count`` to 0, ``memory`` to
 122         ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type.
 123     * - __u32
 124       - ``reserved``\ [7]
 125       - A place holder for future extensions. Drivers and applications
 126         must set the array to zero.
 127
 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.