1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_CREATE_BUFS: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab************************ 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_CREATE_BUFS 854f38fcaSMauro Carvalho Chehab************************ 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_CREATE_BUFS 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)`` 2154f38fcaSMauro Carvalho Chehab 2254f38fcaSMauro Carvalho ChehabArguments 2354f38fcaSMauro Carvalho Chehab========= 2454f38fcaSMauro Carvalho Chehab 2554f38fcaSMauro Carvalho Chehab``fd`` 26407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 2754f38fcaSMauro Carvalho Chehab 2854f38fcaSMauro Carvalho Chehab``argp`` 2954f38fcaSMauro Carvalho Chehab Pointer to struct :c:type:`v4l2_create_buffers`. 3054f38fcaSMauro Carvalho Chehab 3154f38fcaSMauro Carvalho ChehabDescription 3254f38fcaSMauro Carvalho Chehab=========== 3354f38fcaSMauro Carvalho Chehab 3454f38fcaSMauro Carvalho ChehabThis ioctl is used to create buffers for :ref:`memory mapped <mmap>` 3554f38fcaSMauro Carvalho Chehabor :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It 3654f38fcaSMauro Carvalho Chehabcan be used as an alternative or in addition to the 3754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_REQBUFS` ioctl, when a tighter control 3854f38fcaSMauro Carvalho Chehabover buffers is required. This ioctl can be called multiple times to 3954f38fcaSMauro Carvalho Chehabcreate buffers of different sizes. 4054f38fcaSMauro Carvalho Chehab 4154f38fcaSMauro Carvalho ChehabTo allocate the device buffers applications must initialize the relevant 4254f38fcaSMauro Carvalho Chehabfields of the struct :c:type:`v4l2_create_buffers` structure. The 4354f38fcaSMauro Carvalho Chehab``count`` field must be set to the number of requested buffers, the 4454f38fcaSMauro Carvalho Chehab``memory`` field specifies the requested I/O method and the ``reserved`` 4554f38fcaSMauro Carvalho Chehabarray must be zeroed. 4654f38fcaSMauro Carvalho Chehab 4754f38fcaSMauro Carvalho ChehabThe ``format`` field specifies the image format that the buffers must be 4854f38fcaSMauro Carvalho Chehabable to handle. The application has to fill in this struct 4954f38fcaSMauro Carvalho Chehab:c:type:`v4l2_format`. Usually this will be done using the 5054f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or 5154f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the 5254f38fcaSMauro Carvalho Chehabrequested format is supported by the driver. Based on the format's 5354f38fcaSMauro Carvalho Chehab``type`` field the requested buffer size (for single-planar) or plane 5454f38fcaSMauro Carvalho Chehabsizes (for multi-planar formats) will be used for the allocated buffers. 5554f38fcaSMauro Carvalho ChehabThe driver may return an error if the size(s) are not supported by the 5654f38fcaSMauro Carvalho Chehabhardware (usually because they are too small). 5754f38fcaSMauro Carvalho Chehab 5854f38fcaSMauro Carvalho ChehabThe buffers created by this ioctl will have as minimum size the size 5954f38fcaSMauro Carvalho Chehabdefined by the ``format.pix.sizeimage`` field (or the corresponding 6054f38fcaSMauro Carvalho Chehabfields for other format types). Usually if the ``format.pix.sizeimage`` 6154f38fcaSMauro Carvalho Chehabfield is less than the minimum required for the given format, then an 6254f38fcaSMauro Carvalho Chehaberror will be returned since drivers will typically not allow this. If 6354f38fcaSMauro Carvalho Chehabit is larger, then the value will be used as-is. In other words, the 6454f38fcaSMauro Carvalho Chehabdriver may reject the requested size, but if it is accepted the driver 6554f38fcaSMauro Carvalho Chehabwill use it unchanged. 6654f38fcaSMauro Carvalho Chehab 6754f38fcaSMauro Carvalho ChehabWhen the ioctl is called with a pointer to this structure the driver 6854f38fcaSMauro Carvalho Chehabwill attempt to allocate up to the requested number of buffers and store 6954f38fcaSMauro Carvalho Chehabthe actual number allocated and the starting index in the ``count`` and 7054f38fcaSMauro Carvalho Chehabthe ``index`` fields respectively. On return ``count`` can be smaller 7154f38fcaSMauro Carvalho Chehabthan the number requested. 7254f38fcaSMauro Carvalho Chehab 7354f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_create_buffers 7454f38fcaSMauro Carvalho Chehab 75fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 7654f38fcaSMauro Carvalho Chehab 7754f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_create_buffers 7854f38fcaSMauro Carvalho Chehab :header-rows: 0 7954f38fcaSMauro Carvalho Chehab :stub-columns: 0 8054f38fcaSMauro Carvalho Chehab :widths: 1 1 2 8154f38fcaSMauro Carvalho Chehab 8254f38fcaSMauro Carvalho Chehab * - __u32 8354f38fcaSMauro Carvalho Chehab - ``index`` 8454f38fcaSMauro Carvalho Chehab - The starting buffer index, returned by the driver. 8554f38fcaSMauro Carvalho Chehab * - __u32 8654f38fcaSMauro Carvalho Chehab - ``count`` 8754f38fcaSMauro Carvalho Chehab - The number of buffers requested or granted. If count == 0, then 8854f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of 8954f38fcaSMauro Carvalho Chehab created buffers, and it will check the validity of ``memory`` and 9054f38fcaSMauro Carvalho Chehab ``format.type``. If those are invalid -1 is returned and errno is 9154f38fcaSMauro Carvalho Chehab set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns 9254f38fcaSMauro Carvalho Chehab 0. It will never set errno to ``EBUSY`` error code in this particular 9354f38fcaSMauro Carvalho Chehab case. 9454f38fcaSMauro Carvalho Chehab * - __u32 9554f38fcaSMauro Carvalho Chehab - ``memory`` 9654f38fcaSMauro Carvalho Chehab - Applications set this field to ``V4L2_MEMORY_MMAP``, 9754f38fcaSMauro Carvalho Chehab ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See 9854f38fcaSMauro Carvalho Chehab :c:type:`v4l2_memory` 9954f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_format` 10054f38fcaSMauro Carvalho Chehab - ``format`` 10154f38fcaSMauro Carvalho Chehab - Filled in by the application, preserved by the driver. 10254f38fcaSMauro Carvalho Chehab * - __u32 10354f38fcaSMauro Carvalho Chehab - ``capabilities`` 10454f38fcaSMauro Carvalho Chehab - Set by the driver. If 0, then the driver doesn't support 10554f38fcaSMauro Carvalho Chehab capabilities. In that case all you know is that the driver is 10654f38fcaSMauro Carvalho Chehab guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support 107fcab45adSHans Verkuil other :c:type:`v4l2_memory` types. It will not support any other 10854f38fcaSMauro Carvalho Chehab capabilities. See :ref:`here <v4l2-buf-capabilities>` for a list of the 10954f38fcaSMauro Carvalho Chehab capabilities. 11054f38fcaSMauro Carvalho Chehab 11154f38fcaSMauro Carvalho Chehab If you want to just query the capabilities without making any 11254f38fcaSMauro Carvalho Chehab other changes, then set ``count`` to 0, ``memory`` to 11354f38fcaSMauro Carvalho Chehab ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type. 1141e0b2318SSergey Senozhatsky 1151e0b2318SSergey Senozhatsky * - __u32 116*c0acf9cfSSergey Senozhatsky - ``flags`` 117*c0acf9cfSSergey Senozhatsky - Specifies additional buffer management attributes. 118*c0acf9cfSSergey Senozhatsky See :ref:`memory-flags`. 119*c0acf9cfSSergey Senozhatsky 120*c0acf9cfSSergey Senozhatsky * - __u32 121*c0acf9cfSSergey Senozhatsky - ``reserved``\ [6] 12254f38fcaSMauro Carvalho Chehab - A place holder for future extensions. Drivers and applications 12354f38fcaSMauro Carvalho Chehab must set the array to zero. 12454f38fcaSMauro Carvalho Chehab 12554f38fcaSMauro Carvalho ChehabReturn Value 12654f38fcaSMauro Carvalho Chehab============ 12754f38fcaSMauro Carvalho Chehab 12854f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 12954f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 13054f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 13154f38fcaSMauro Carvalho Chehab 13254f38fcaSMauro Carvalho ChehabENOMEM 13354f38fcaSMauro Carvalho Chehab No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. 13454f38fcaSMauro Carvalho Chehab 13554f38fcaSMauro Carvalho ChehabEINVAL 13654f38fcaSMauro Carvalho Chehab The buffer type (``format.type`` field), requested I/O method 13754f38fcaSMauro Carvalho Chehab (``memory``) or format (``format`` field) is not valid. 138