aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/Documentation/media/uapi/v4l/vidioc-create-bufs.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-create-bufs.rst')
-rw-r--r--Documentation/media/uapi/v4l/vidioc-create-bufs.rst141
1 files changed, 0 insertions, 141 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-create-bufs.rst b/Documentation/media/uapi/v4l/vidioc-create-bufs.rst
deleted file mode 100644
index bd08e4f77ae4..000000000000
--- a/Documentation/media/uapi/v4l/vidioc-create-bufs.rst
+++ /dev/null
@@ -1,141 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/media/uapi/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _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:function:: int ioctl( int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp )
- :name: VIDIOC_CREATE_BUFS
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <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
-than the number requested.
-
-
-.. c:type:: v4l2_create_buffers
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: struct v4l2_create_buffers
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
- * - __u32
- - ``index``
- - The starting buffer index, returned by the driver.
- * - __u32
- - ``count``
- - The number of buffers requested or granted. If count == 0, then
- :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of
- created buffers, and it will check the validity of ``memory`` and
- ``format.type``. If those are invalid -1 is returned and errno is
- set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns
- 0. It will never set errno to ``EBUSY`` error code in this particular
- case.
- * - __u32
- - ``memory``
- - Applications set this field to ``V4L2_MEMORY_MMAP``,
- ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
- :c:type:`v4l2_memory`
- * - struct :c:type:`v4l2_format`
- - ``format``
- - Filled in by the application, preserved by the driver.
- * - __u32
- - ``capabilities``
- - Set by the driver. If 0, then the driver doesn't support
- capabilities. In that case all you know is that the driver is
- guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support
- other :c:type:`v4l2_memory` types. It will not support any others
- capabilities. See :ref:`here <v4l2-buf-capabilities>` for a list of the
- capabilities.
-
- If you want to just query the capabilities without making any
- other changes, then set ``count`` to 0, ``memory`` to
- ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type.
- * - __u32
- - ``reserved``\ [7]
- - A place holder for future extensions. Drivers and applications
- must set the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-ENOMEM
- No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
-
-EINVAL
- The buffer type (``format.type`` field), requested I/O method
- (``memory``) or format (``format`` field) is not valid.