ioctl VIDIOC_CREATE_BUFS
Prev | Appendix A. Function Reference | Next

## Name

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

## Synopsis

`int ioctl(` | int fd,
| int request,
| struct v4l2_create_buffers *argp`)`;

## Arguments

`fd`

  File descriptor returned by `open()`.

`request`

  VIDIOC_CREATE_BUFS

`argp`

## Description

### Experimental

This is an experimental interface and may change in the future.

This ioctl is used to create buffers for memory mapped or user pointer or DMA buffer I/O. It can be used as an alternative or in addition to the `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 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 v4l2_format. Usually this will be done using the `VIDIOC_TRY_FMT` or `VIDIOC_G_FMT` ioctl() to ensure that the requested format is supported by the driver. Unsupported formats will result in an error.

The buffers created by this ioctl will have as minimum size the size defined by the `format.pix.sizeimage` field. If the `format.pix.sizeimage` field is less than the minimum required for the given format, then `sizeimage` will be increased by the driver to that minimum to allocate the buffers. If it is larger, then the value will be used as-is. The same applies to the `sizeimage` field of the v4l2_plane_pix_format structure in the case of multiplanar formats.

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. The driver may also increase buffer sizes if required, however, it will not update `sizeimage` field values. The user has to use `VIDIOC_QUERYBUF` to retrieve that information.

Table A.1. struct v4l2_create_buffers

__u32 | `index` | The starting buffer index, returned by the driver.

__u32

`count`

The number of buffers requested or granted. If count == 0, then `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 `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 Table 3.5, “enum v4l2_memory”
struct v4l2_format | `format` | Filled in by the application, preserved by the driver.
__u32 | `reserved`[8] | A place holder for future extensions.

## 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 Generic Error Codes chapter.

ENOMEM

  No memory to allocate buffers for memory mapped I/O.

EINVAL

  The buffer type (`format.type` field), requested I/O method (`memory`) or format (`format` field) is not valid.

Prev | Up | Next
V4L2 ioctl() | Home | ioctl VIDIOC_CROPCAP