1 .. -*- coding: utf-8; mode: rst -*-
3 .. _VIDIOC_CREATE_BUFS:
5 ************************
6 ioctl VIDIOC_CREATE_BUFS
7 ************************
12 VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_create_buffers *argp )
25 File descriptor returned by :ref:`open() <func-open>`.
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.
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``
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).
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.
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.
76 .. _v4l2-create-buffers:
78 .. flat-table:: struct v4l2_create_buffers
90 - The starting buffer index, returned by the driver.
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
112 - Applications set this field to ``V4L2_MEMORY_MMAP``,
113 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
118 - struct :ref:`v4l2_format <v4l2-format>`
122 - Filled in by the application, preserved by the driver.
130 - A place holder for future extensions. Drivers and applications
131 must set the array to zero.
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.
142 No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
145 The buffer type (``format.type`` field), requested I/O method
146 (``memory``) or format (``format`` field) is not valid.