VIDIOC_CREATE_BUFS ioctl

이름, 호출 형식과 인자

`VIDIOC_CREATE_BUFS`는 메모리 매핑, 사용자 포인터 또는 DMA 버퍼 I/O에 사용할 버퍼를 생성합니다. 호출 형식은 `int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)`입니다.

`fd`는 `open()`이 반환한 파일 디스크립터이며, `argp`는 응용 프로그램이 초기화하고 드라이버가 결과를 채우는 `struct v4l2_create_buffers`를 가리킵니다. 이 문서는 V4L C 네임스페이스의 `VIDIOC_CREATE_BUFS` 매크로를 설명합니다.

.. 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`.

버퍼 생성, 형식과 크기 규칙

이 ioctl은 MMAP, USERPTR 또는 DMABUF I/O용 버퍼를 만들며, 버퍼를 더 정밀하게 제어해야 할 때 `VIDIOC_REQBUFS` 대신 또는 그와 함께 사용할 수 있습니다. 서로 다른 크기의 버퍼를 만들기 위해 여러 번 호출할 수도 있습니다.

응용 프로그램은 `count`에 요청할 버퍼 수를, `memory`에 I/O 방식을 설정하고 `reserved` 배열을 0으로 채워야 합니다. `format`에는 버퍼가 처리할 수 있어야 하는 `struct v4l2_format`을 넣습니다. 보통 `VIDIOC_TRY_FMT` 또는 `VIDIOC_G_FMT`으로 드라이버가 지원하는 형식을 먼저 확인합니다.

단일 플레인 형식은 `format.type`에 따른 버퍼 크기를, 멀티플레인 형식은 각 plane 크기를 사용합니다. 하드웨어가 크기를 지원하지 않으면, 대개 너무 작을 때, 드라이버가 오류를 반환할 수 있습니다.

생성되는 버퍼의 최소 크기는 `format.pix.sizeimage` 또는 해당 형식 유형의 대응 필드가 정의합니다. 요구 최소값보다 작으면 일반적으로 거부되고, 더 큰 값이 허용되면 드라이버는 그 값을 바꾸지 않고 그대로 사용합니다. 호출이 성공하면 `count`에는 실제 할당 수가, `index`에는 첫 버퍼 인덱스가 반환되며 실제 수는 요청보다 작을 수 있습니다.

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

v4l2_create_buffers 필드

`struct v4l2_create_buffers`는 생성 위치와 수, 메모리 방식, 형식, 큐 capability와 관리 플래그를 한 번의 요청에 전달합니다. 드라이버와 응용 프로그램은 미래 확장용 예약 필드를 반드시 0으로 유지해야 합니다.

`count == 0`이면 버퍼를 만들지 않고 현재 생성된 버퍼 수를 `index`에 반환하며 `memory`와 `format.type`의 유효성을 검사합니다. 둘 중 하나가 잘못되면 `EINVAL`, 유효하면 0을 반환하고 이 특별한 경우에는 `EBUSY`를 반환하지 않습니다.

변경 없이 capability만 조회하려면 `count`를 0, `memory`를 `V4L2_MEMORY_MMAP`, `format.type`을 조회할 버퍼 유형으로 설정합니다. `capabilities == 0`이면 해당 드라이버가 capability 보고를 지원하지 않는다는 뜻이며 MMAP 지원만 확실합니다.

than the number requested.

.. c:type:: v4l2_create_buffers

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. 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 other
	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
      - ``flags``
      - Specifies additional buffer management attributes.
	See :ref:`memory-flags`.
    * - __u32
      - ``max_num_buffers``
      - If the V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS capability flag is set
        this field indicates the maximum possible number of buffers
        for this queue.
    * - __u32
      - ``reserved``\ [5]
      - A place holder for future extensions. Drivers and applications

반환값과 오류

성공하면 0을 반환합니다. 실패하면 -1을 반환하고 `errno`를 설정하며 공통 오류는 Generic Error Codes 절을 따릅니다.

	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.