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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_CREATE_BUFS:
   4
   5 ************************
   6 ioctl VIDIOC_CREATE_BUFS
   7 ************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_create_buffers *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_CREATE_BUFS
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
  37 or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
  38 can be used as an alternative or in addition to the
  39 :ref:`VIDIOC_REQBUFS` ioctl, when a tighter control
  40 over buffers is required. This ioctl can be called multiple times to
  41 create buffers of different sizes.
  42
  43 To allocate the device buffers applications must initialize the relevant
  44 fields of the :ref:`struct v4l2_create_buffers <v4l2-create-buffers>` structure. The
  45 ``count`` field must be set to the number of requested buffers, the
  46 ``memory`` field specifies the requested I/O method and the ``reserved``
  47 array must be zeroed.
  48
  49 The ``format`` field specifies the image format that the buffers must be
  50 able to handle. The application has to fill in this struct
  51 :ref:`v4l2_format <v4l2-format>`. Usually this will be done using the
  52 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or
  53 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the
  54 requested format is supported by the driver. Based on the format's
  55 ``type`` field the requested buffer size (for single-planar) or plane
  56 sizes (for multi-planar formats) will be used for the allocated buffers.
  57 The driver may return an error if the size(s) are not supported by the
  58 hardware (usually because they are too small).
  59
  60 The buffers created by this ioctl will have as minimum size the size
  61 defined by the ``format.pix.sizeimage`` field (or the corresponding
  62 fields for other format types). Usually if the ``format.pix.sizeimage``
  63 field is less than the minimum required for the given format, then an
  64 error will be returned since drivers will typically not allow this. If
  65 it is larger, then the value will be used as-is. In other words, the
  66 driver may reject the requested size, but if it is accepted the driver
  67 will use it unchanged.
  68
  69 When the ioctl is called with a pointer to this structure the driver
  70 will attempt to allocate up to the requested number of buffers and store
  71 the actual number allocated and the starting index in the ``count`` and
  72 the ``index`` fields respectively. On return ``count`` can be smaller
  73 than the number requested.
  74
  75
  76 .. _v4l2-create-buffers:
  77
  78 .. flat-table:: struct v4l2_create_buffers
  79     :header-rows:  0
  80     :stub-columns: 0
  81     :widths:       1 1 2
  82
  83
  84     -  .. row 1
  85
  86        -  __u32
  87
  88        -  ``index``
  89
  90        -  The starting buffer index, returned by the driver.
  91
  92     -  .. row 2
  93
  94        -  __u32
  95
  96        -  ``count``
  97
  98        -  The number of buffers requested or granted. If count == 0, then
  99           :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of
 100           created buffers, and it will check the validity of ``memory`` and
 101           ``format.type``. If those are invalid -1 is returned and errno is
 102           set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns
 103           0. It will never set errno to ``EBUSY`` error code in this particular
 104           case.
 105
 106     -  .. row 3
 107
 108        -  __u32
 109
 110        -  ``memory``
 111
 112        -  Applications set this field to ``V4L2_MEMORY_MMAP``,
 113           ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
 114           :ref:`v4l2-memory`
 115
 116     -  .. row 4
 117
 118        -  struct :ref:`v4l2_format <v4l2-format>`
 119
 120        -  ``format``
 121
 122        -  Filled in by the application, preserved by the driver.
 123
 124     -  .. row 5
 125
 126        -  __u32
 127
 128        -  ``reserved``\ [8]
 129
 130        -  A place holder for future extensions. Drivers and applications
 131           must set the array to zero.
 132
 133
 134 Return Value
 135 ============
 136
 137 On success 0 is returned, on error -1 and the ``errno`` variable is set
 138 appropriately. The generic error codes are described at the
 139 :ref:`Generic Error Codes <gen-errors>` chapter.
 140
 141 ENOMEM
 142     No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
 143
 144 EINVAL
 145     The buffer type (``format.type`` field), requested I/O method
 146     (``memory``) or format (``format`` field) is not valid.