2.2.6 V4L2 File handlers

struct v4l2_fh提供了一种方便的方法来保留文件句柄特定的数据，该数据由V4L2框架使用。
注意：新的驱动程序必须使用struct v4l2_fh，因为它也用于实现优先处理（ioctl VIDIOC_G_PRIORITY，VIDIOC_S_PRIORITY）。
v4l2_fh的用户（在V4L2框架中，而不是驱动程序中）通过测试video_device->flags中的V4L2_FL_USES_V4L2_FH位来确定驱动程序是否将v4l2_fh用作其file->private_data指针。每当调用v4l2_fh_init()时，就会设置此位。
struct v4l2_fh作为驱动程序自己的文件句柄结构的一部分分配，并且在驱动程序的open()函数中将file->private_data设置为它。
在许多情况下，struct v4l2_fh将嵌入到较大的结构中。在这种情况下，您应该调用：
1）在open()中调用v4l2_fh_init()和v4l2_fh_add()。
2）在release()中调用v4l2_fh_del()和v4l2_fh_exit()。
驱动程序可以使用container_of宏提取其自己的文件句柄结构。
示例：

struct my_fh {
int blah;
struct v4l2_fh fh;
};
...
int my_open(struct file *file)
{
struct my_fh *my_fh;
struct video_device *vfd;
int ret;
...
my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
...
v4l2_fh_init(&my_fh->fh, vfd);
...
file->private_data = &my_fh->fh;
v4l2_fh_add(&my_fh->fh);
return 0;
}
int my_release(struct file *file)
{
struct v4l2_fh *fh = file->private_data;
struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
...
v4l2_fh_del(&my_fh->fh);
v4l2_fh_exit(&my_fh->fh);
kfree(my_fh);
return 0;
}

上面是使用的v4l2_fh函数的简要描述：
v4l2_fh_init(fh, vdev)
• 初始化文件句柄。必须在驱动程序的v4l2_file_operations->open()处理程序中执行此操作。
v4l2_fh_add(fh)
• 将v4l2_fh添加到video_device文件句柄列表中。必须在文件句柄完全初始化后调用。
v4l2_fh_del(fh)
• 将文件句柄与video_device分离。现在可以调用文件句柄退出函数。
v4l2_fh_exit(fh)
• 取消初始化文件句柄。取消初始化v4l2_fh内存后可以释放。
如果未嵌入struct v4l2_fh，则可以使用以下辅助函数：
v4l2_fh_open(struct file *filp)
• 这将分配一个struct v4l2_fh，初始化它并将其添加到与文件结构相关联的struct video_device。
v4l2_fh_release(struct file *filp)
• 这将从与文件结构相关联的struct video_device中删除它，取消初始化v4l2_fh并释放它。
这两个函数可以插入v4l2_file_operation的open()和release()操作中。
多个驱动程序需要在打开第一个文件句柄和关闭最后一个文件句柄时执行某些操作。添加了两个辅助函数来检查v4l2_fh结构是否是关联设备节点的唯一打开文件句柄：
v4l2_fh_is_singular(fh)
• 如果文件句柄是唯一打开的文件句柄，则返回1，否则返回0。
v4l2_fh_is_singular_file(struct file *filp)
• 相同，但它使用filp->private_data调用v4l2_fh_is_singular。
2.2.6.1 V4L2 fh functions and data structures
struct v4l2_fh
描述了V4L2文件句柄
定义

struct v4l2_fh {
struct list_head list;
struct video_device *vdev;
struct v4l2_ctrl_handler *ctrl_handler;
enum v4l2_priority prio;
wait_queue_head_t wait;
struct mutex subscribe_lock;
struct list_head subscribed;
struct list_head available;
unsigned int navailable;
u32 sequence;
struct v4l2_m2m_ctx *m2m_ctx;
};

成员
list文件句柄列表
vdev指向struct video_device的指针
ctrl_handler指向struct v4l2_ctrl_handler的指针
prio文件句柄的优先级，由enum v4l2_priority定义
wait事件的等待队列
subscribe_lock对订阅列表进行串行化更改；保证添加和del事件回调有序调用
subscribed订阅事件列表
available等待出队的事件列表
navailable可用事件数在可用列表中
sequence事件序列号
m2m_ctx指向struct v4l2_m2m_ctx的指针
void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
初始化文件句柄。
参数
struct v4l2_fh *fh 指向struct v4l2_fh的指针
struct video_device *vdev 指向struct video_device的指针
描述
使用文件句柄的V4L2框架的部分应在此函数中进行初始化。如果驱动程序使用struct v4l2_fh，则必须从驱动程序的v4l2_file_operations->open()处理程序中调用它。
void v4l2_fh_add(struct v4l2_fh *fh)
将fh添加到video_device的文件句柄列表中。
参数
struct v4l2_fh *fh 指向struct v4l2_fh的指针
描述
注意：必须先初始化fh文件句柄。
int v4l2_fh_open(struct file *filp)
可以用作v4l2_file_operations的open()操作的辅助程序。
参数
struct file *filp 指向struct file的指针
描述
它分配一个v4l2_fh并将其初始化并添加到与文件指针关联的struct video_device中。
void v4l2_fh_del(struct v4l2_fh *fh)
从文件句柄列表中删除文件句柄。
参数
struct v4l2_fh *fh 指向struct v4l2_fh的指针
描述
如果出现错误，filp->private_data将为NULL，否则它将指向struct v4l2_fh。注意：如果驱动程序使用struct v4l2_fh，则必须在v4l2_file_operations->release()处理程序中调用它。
void v4l2_fh_exit(struct v4l2_fh *fh)
释放与文件句柄相关的资源。
参数
struct v4l2_fh *fh 指向struct v4l2_fh的指针
描述
使用v4l2_fh的V4L2框架的部分也必须在此处释放它们的资源。注意：如果驱动程序使用struct v4l2_fh，则必须在v4l2_file_operations->release()处理程序中调用它。
int v4l2_fh_release(struct file *filp)
可以用作v4l2_file_operations的release()操作的辅助程序。
参数
struct file *filp 指向struct file的指针
描述
它删除并退出与文件指针关联的v4l2_fh，并释放它。如果filp->private_data（指向v4l2_fh结构的指针）为NULL，则不执行任何操作。
此函数始终返回0。
int v4l2_fh_is_singular(struct v4l2_fh *fh)
如果此文件句柄是与之关联的video_device打开的唯一文件句柄，则返回1。
参数
struct v4l2_fh *fh 指向struct v4l2_fh的指针
描述
如果fh为NULL，则返回0。
int v4l2_fh_is_singular_file(struct file *filp)
如果此文件句柄是与之关联的video_device打开的唯一文件句柄，则返回1。
参数
struct file *filp 指向struct file的指针
描述
这是使用struct file作为参数的v4l2_fh_is_singular()的辅助函数变体。如果filp->private_data为NULL，则它将返回0。