Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
Extension
.rst
Size
5178 bytes
Lines
142
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_CREATE_BUFS:

************************
ioctl VIDIOC_CREATE_BUFS
************************

Name
====

VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O

Synopsis
========

.. c:macro:: VIDIOC_CREATE_BUFS

``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_create_buffers`.

Description
===========

This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
can be used as an alternative or in addition to the
:ref:`VIDIOC_REQBUFS` ioctl, when a tighter control
over buffers is required. This ioctl can be called multiple times to
create buffers of different sizes.

To allocate the device buffers applications must initialize the relevant
fields of the struct :c:type:`v4l2_create_buffers` structure. The
``count`` field must be set to the number of requested buffers, the
``memory`` field specifies the requested I/O method and the ``reserved``
array must be zeroed.

The ``format`` field specifies the image format that the buffers must be
able to handle. The application has to fill in this struct
:c:type:`v4l2_format`. Usually this will be done using the
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the
requested format is supported by the driver. Based on the format's
``type`` field the requested buffer size (for single-planar) or plane
sizes (for multi-planar formats) will be used for the allocated buffers.
The driver may return an error if the size(s) are not supported by the
hardware (usually because they are too small).

The buffers created by this ioctl will have as minimum size the size
defined by the ``format.pix.sizeimage`` field (or the corresponding
fields for other format types). Usually if the ``format.pix.sizeimage``
field is less than the minimum required for the given format, then an
error will be returned since drivers will typically not allow this. If
it is larger, then the value will be used as-is. In other words, the
driver may reject the requested size, but if it is accepted the driver
will use it unchanged.

When the ioctl is called with a pointer to this structure the driver
will attempt to allocate up to the requested number of buffers and store
the actual number allocated and the starting index in the ``count`` and
the ``index`` fields respectively. On return ``count`` can be smaller

Annotation

Implementation Notes