7.4. ioctl VIDIOC_EXT_CREATE_BUFS

7.4.1. Name

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

7.4.2. Synopsis

int ioctl(int fd, VIDIOC_EXT_CREATE_BUFS, struct v4l2_ext_create_buffers *argp)

7.4.3. Arguments

fd

File descriptor returned by open().

argp

Pointer to struct v4l2_ext_create_buffers.

7.4.4. Description

This ioctl is used to create buffers for memory mapped or user pointer or DMA buffer I/O. 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 v4l2_ext_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_EXT_PIX_FMT or VIDIOC_G_EXT_PIX_FMT ioctls to ensure that the requested format is supported by the driver. The driver may return an error if the size(s) are not supported by the hardware (usually because they are too small).

The driver can create a memory buffer per plane, or a single memory buffer containing all the planes, with a minimum size according to the size defined by the format.plane_fmt[i].sizeimage field. Usually if the format.plane_fmt[i].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.

struct v4l2_ext_create_buffers

VIDIOC_EXT_CREATE_BUFS argument

Definition

struct v4l2_ext_create_buffers {
  __u32 index;
  __u32 count;
  __u32 memory;
  __u32 capabilities;
  struct v4l2_ext_pix_format      format;
  __u32 flags;
  __u32 reserved[5];
};

Members

index

on return, index of the first created buffer

count

entry: number of requested buffers,

memory

enum v4l2_memory; buffer memory type

capabilities

capabilities of this buffer type.

format

frame format, for which buffers are requested

flags

additional buffer management attributes (ignored unless the queue has V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS capability and configured for MMAP streaming I/O).

reserved

extra space reserved for future fields, must be set to 0

Return

number of created buffers

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