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 可能小于请求的数量。

类型 v4l2_create_buffers

结构体 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，则驱动程序不支持 capabilities。 在这种情况下，您所知道的是驱动程序保证支持 V4L2_MEMORY_MMAP 并且可能支持其他 v4l2_memory 类型。 它将不支持任何其他 capabilities。 有关 capabilities 的列表，请参阅 此处。 如果您只想查询 capabilities 而不做任何其他更改，请将 count 设置为 0，memory 设置为 V4L2_MEMORY_MMAP，并将 format.type 设置为缓冲区类型。
__u32	flags	指定其他缓冲区管理属性。 请参阅 内存一致性标志。
__u32	max_num_buffers	如果设置了 V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS capability 标志，则此字段指示此队列的最大可能缓冲区数量。
__u32	reserved[5]	未来扩展的占位符。 驱动程序和应用程序必须将数组设置为零。

7.3.5. 返回值

成功时返回 0，出错时返回 -1 并且 errno 变量会进行适当设置。 通用错误代码在 通用错误代码 章节中进行了描述。

ENOMEM

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

EINVAL

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