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_FMTVIDIOC_G_FMT ioctl 完成,以确保驱动程序支持请求的格式。 根据格式的 type 字段,请求的缓冲区大小(对于单平面)或平面大小(对于多平面格式)将用于分配的缓冲区。 如果硬件不支持这些大小(通常是因为它们太小),驱动程序可能会返回错误。

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

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

类型 v4l2_create_buffers
结构体 v4l2_create_buffers

__u32

index

驱动程序返回的起始缓冲区索引。

__u32

count

请求或授予的缓冲区数量。 如果 count == 0,则 ioctl VIDIOC_CREATE_BUFS 会将 index 设置为当前已创建的缓冲区数量,并检查 memoryformat.type 的有效性。 如果这些无效,则返回 -1 并且 errno 设置为 EINVAL 错误代码,否则 ioctl VIDIOC_CREATE_BUFS 返回 0。 在这种特定情况下,它永远不会将 errno 设置为 EBUSY 错误代码。

__u32

memory

应用程序将此字段设置为 V4L2_MEMORY_MMAPV4L2_MEMORY_DMABUFV4L2_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 字段)无效。