1*4882a593Smuzhiyun.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2*4882a593Smuzhiyun.. c:namespace:: V4L 3*4882a593Smuzhiyun 4*4882a593Smuzhiyun.. _VIDIOC_CREATE_BUFS: 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun************************ 7*4882a593Smuzhiyunioctl VIDIOC_CREATE_BUFS 8*4882a593Smuzhiyun************************ 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunName 11*4882a593Smuzhiyun==== 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunVIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O 14*4882a593Smuzhiyun 15*4882a593SmuzhiyunSynopsis 16*4882a593Smuzhiyun======== 17*4882a593Smuzhiyun 18*4882a593Smuzhiyun.. c:macro:: VIDIOC_CREATE_BUFS 19*4882a593Smuzhiyun 20*4882a593Smuzhiyun``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)`` 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunArguments 23*4882a593Smuzhiyun========= 24*4882a593Smuzhiyun 25*4882a593Smuzhiyun``fd`` 26*4882a593Smuzhiyun File descriptor returned by :c:func:`open()`. 27*4882a593Smuzhiyun 28*4882a593Smuzhiyun``argp`` 29*4882a593Smuzhiyun Pointer to struct :c:type:`v4l2_create_buffers`. 30*4882a593Smuzhiyun 31*4882a593SmuzhiyunDescription 32*4882a593Smuzhiyun=========== 33*4882a593Smuzhiyun 34*4882a593SmuzhiyunThis ioctl is used to create buffers for :ref:`memory mapped <mmap>` 35*4882a593Smuzhiyunor :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It 36*4882a593Smuzhiyuncan be used as an alternative or in addition to the 37*4882a593Smuzhiyun:ref:`VIDIOC_REQBUFS` ioctl, when a tighter control 38*4882a593Smuzhiyunover buffers is required. This ioctl can be called multiple times to 39*4882a593Smuzhiyuncreate buffers of different sizes. 40*4882a593Smuzhiyun 41*4882a593SmuzhiyunTo allocate the device buffers applications must initialize the relevant 42*4882a593Smuzhiyunfields of the struct :c:type:`v4l2_create_buffers` structure. The 43*4882a593Smuzhiyun``count`` field must be set to the number of requested buffers, the 44*4882a593Smuzhiyun``memory`` field specifies the requested I/O method and the ``reserved`` 45*4882a593Smuzhiyunarray must be zeroed. 46*4882a593Smuzhiyun 47*4882a593SmuzhiyunThe ``format`` field specifies the image format that the buffers must be 48*4882a593Smuzhiyunable to handle. The application has to fill in this struct 49*4882a593Smuzhiyun:c:type:`v4l2_format`. Usually this will be done using the 50*4882a593Smuzhiyun:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or 51*4882a593Smuzhiyun:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the 52*4882a593Smuzhiyunrequested format is supported by the driver. Based on the format's 53*4882a593Smuzhiyun``type`` field the requested buffer size (for single-planar) or plane 54*4882a593Smuzhiyunsizes (for multi-planar formats) will be used for the allocated buffers. 55*4882a593SmuzhiyunThe driver may return an error if the size(s) are not supported by the 56*4882a593Smuzhiyunhardware (usually because they are too small). 57*4882a593Smuzhiyun 58*4882a593SmuzhiyunThe buffers created by this ioctl will have as minimum size the size 59*4882a593Smuzhiyundefined by the ``format.pix.sizeimage`` field (or the corresponding 60*4882a593Smuzhiyunfields for other format types). Usually if the ``format.pix.sizeimage`` 61*4882a593Smuzhiyunfield is less than the minimum required for the given format, then an 62*4882a593Smuzhiyunerror will be returned since drivers will typically not allow this. If 63*4882a593Smuzhiyunit is larger, then the value will be used as-is. In other words, the 64*4882a593Smuzhiyundriver may reject the requested size, but if it is accepted the driver 65*4882a593Smuzhiyunwill use it unchanged. 66*4882a593Smuzhiyun 67*4882a593SmuzhiyunWhen the ioctl is called with a pointer to this structure the driver 68*4882a593Smuzhiyunwill attempt to allocate up to the requested number of buffers and store 69*4882a593Smuzhiyunthe actual number allocated and the starting index in the ``count`` and 70*4882a593Smuzhiyunthe ``index`` fields respectively. On return ``count`` can be smaller 71*4882a593Smuzhiyunthan the number requested. 72*4882a593Smuzhiyun 73*4882a593Smuzhiyun.. c:type:: v4l2_create_buffers 74*4882a593Smuzhiyun 75*4882a593Smuzhiyun.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 76*4882a593Smuzhiyun 77*4882a593Smuzhiyun.. flat-table:: struct v4l2_create_buffers 78*4882a593Smuzhiyun :header-rows: 0 79*4882a593Smuzhiyun :stub-columns: 0 80*4882a593Smuzhiyun :widths: 1 1 2 81*4882a593Smuzhiyun 82*4882a593Smuzhiyun * - __u32 83*4882a593Smuzhiyun - ``index`` 84*4882a593Smuzhiyun - The starting buffer index, returned by the driver. 85*4882a593Smuzhiyun * - __u32 86*4882a593Smuzhiyun - ``count`` 87*4882a593Smuzhiyun - The number of buffers requested or granted. If count == 0, then 88*4882a593Smuzhiyun :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of 89*4882a593Smuzhiyun created buffers, and it will check the validity of ``memory`` and 90*4882a593Smuzhiyun ``format.type``. If those are invalid -1 is returned and errno is 91*4882a593Smuzhiyun set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns 92*4882a593Smuzhiyun 0. It will never set errno to ``EBUSY`` error code in this particular 93*4882a593Smuzhiyun case. 94*4882a593Smuzhiyun * - __u32 95*4882a593Smuzhiyun - ``memory`` 96*4882a593Smuzhiyun - Applications set this field to ``V4L2_MEMORY_MMAP``, 97*4882a593Smuzhiyun ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See 98*4882a593Smuzhiyun :c:type:`v4l2_memory` 99*4882a593Smuzhiyun * - struct :c:type:`v4l2_format` 100*4882a593Smuzhiyun - ``format`` 101*4882a593Smuzhiyun - Filled in by the application, preserved by the driver. 102*4882a593Smuzhiyun * - __u32 103*4882a593Smuzhiyun - ``capabilities`` 104*4882a593Smuzhiyun - Set by the driver. If 0, then the driver doesn't support 105*4882a593Smuzhiyun capabilities. In that case all you know is that the driver is 106*4882a593Smuzhiyun guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support 107*4882a593Smuzhiyun other :c:type:`v4l2_memory` types. It will not support any other 108*4882a593Smuzhiyun capabilities. See :ref:`here <v4l2-buf-capabilities>` for a list of the 109*4882a593Smuzhiyun capabilities. 110*4882a593Smuzhiyun 111*4882a593Smuzhiyun If you want to just query the capabilities without making any 112*4882a593Smuzhiyun other changes, then set ``count`` to 0, ``memory`` to 113*4882a593Smuzhiyun ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type. 114*4882a593Smuzhiyun 115*4882a593Smuzhiyun * - __u32 116*4882a593Smuzhiyun - ``reserved``\ [7] 117*4882a593Smuzhiyun - A place holder for future extensions. Drivers and applications 118*4882a593Smuzhiyun must set the array to zero. 119*4882a593Smuzhiyun 120*4882a593SmuzhiyunReturn Value 121*4882a593Smuzhiyun============ 122*4882a593Smuzhiyun 123*4882a593SmuzhiyunOn success 0 is returned, on error -1 and the ``errno`` variable is set 124*4882a593Smuzhiyunappropriately. The generic error codes are described at the 125*4882a593Smuzhiyun:ref:`Generic Error Codes <gen-errors>` chapter. 126*4882a593Smuzhiyun 127*4882a593SmuzhiyunENOMEM 128*4882a593Smuzhiyun No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. 129*4882a593Smuzhiyun 130*4882a593SmuzhiyunEINVAL 131*4882a593Smuzhiyun The buffer type (``format.type`` field), requested I/O method 132*4882a593Smuzhiyun (``memory``) or format (``format`` field) is not valid. 133