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