7.3. ioctl VIDIOC_CREATE_BUFS

7.3.1. 名称

VIDIOC_CREATE_BUFS - 为内存映射或用户指针或DMA缓冲区I/O创建缓冲区

7.3.2. 概要

VIDIOC_CREATE_BUFS

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

7.3.3. 参数

fd

由 open() 返回的文件描述符。

argp

指向结构体 v4l2_create_buffers 的指针。

7.3.4. 描述

此 ioctl 用于为 内存映射 或 用户指针 或 DMA缓冲区 I/O 创建缓冲区。当需要对缓冲区进行更严格的控制时，它可以作为 ioctl VIDIOC_REQBUFS ioctl 的替代或补充。可以多次调用此 ioctl 以创建不同大小的缓冲区。

要分配设备缓冲区，应用程序必须初始化结构体 v4l2_create_buffers 结构的相关字段。 count 字段必须设置为请求的缓冲区数量，memory 字段指定请求的 I/O 方法，并且 reserved 数组必须清零。

format 字段指定缓冲区必须能够处理的图像格式。应用程序必须填写此结构体 v4l2_format。通常，这将使用 VIDIOC_TRY_FMT 或 VIDIOC_G_FMT ioctl 来确保驱动程序支持请求的格式。根据格式的 type 字段，请求的缓冲区大小（对于单平面）或平面大小（对于多平面格式）将用于分配的缓冲区。如果硬件不支持大小（通常是因为它们太小），则驱动程序可能会返回错误。

由此 ioctl 创建的缓冲区的最小大小将是由 format.pix.sizeimage 字段（或其他格式类型的相应字段）定义的大小。通常，如果 format.pix.sizeimage 字段小于给定格式所需的最小值，则将返回错误，因为驱动程序通常不允许这样做。如果它更大，则该值将按原样使用。换句话说，驱动程序可能会拒绝请求的大小，但如果接受，则驱动程序将使用它而不更改。

当使用指向此结构的指针调用 ioctl 时，驱动程序将尝试分配最多请求数量的缓冲区，并将实际分配的数量和起始索引分别存储在 count 和 index 字段中。返回时，count 可以小于请求的数量。

type v4l2_create_buffers

struct v4l2_create_buffers

__u32	index	驱动程序返回的起始缓冲区索引。
__u32	count	请求或授予的缓冲区数量。如果 count == 0，则 ioctl VIDIOC_CREATE_BUFS 将 index 设置为当前创建的缓冲区数量，并检查 memory 和 format.type 的有效性。如果这些无效，则返回 -1，并将 errno 设置为 EINVAL 错误代码，否则 ioctl VIDIOC_CREATE_BUFS 返回 0。在这种特殊情况下，它永远不会将 errno 设置为 EBUSY 错误代码。
__u32	memory	应用程序将此字段设置为 V4L2_MEMORY_MMAP、V4L2_MEMORY_DMABUF 或 V4L2_MEMORY_USERPTR。请参阅 v4l2_memory
struct v4l2_format	format	由应用程序填写，由驱动程序保留。
__u32	capabilities	由驱动程序设置。如果为 0，则驱动程序不支持功能。在这种情况下，您所知道的是驱动程序保证支持 V4L2_MEMORY_MMAP，并且*可能* 支持其他 v4l2_memory 类型。它将不支持任何其他功能。有关功能列表，请参阅 此处。 如果您只想查询功能而不进行任何其他更改，则将 count 设置为 0，将 memory 设置为 V4L2_MEMORY_MMAP，将 format.type 设置为缓冲区类型。
__u32	flags	指定其他缓冲区管理属性。请参阅 内存一致性标志。
__u32	max_num_buffers	如果设置了 V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS 功能标志，则此字段指示此队列的最大可能缓冲区数量。
__u32	reserved[5]	用于未来扩展的占位符。驱动程序和应用程序必须将数组设置为零。

7.3.5. 返回值

成功时返回 0，失败时返回 -1，并且会设置 errno 变量。通用错误代码在 通用错误代码 一章中描述。

ENOMEM

没有足够的内存来为 内存映射 I/O 分配缓冲区。

EINVAL

缓冲区类型（format.type 字段）、请求的 I/O 方法（memory）或格式（format 字段）无效。