Documentation / zh_CN / video4linux / v4l2-framework.txt

Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:17 EST.

	Chinese translated version of Documentation/video4linux/v4l2-framework.txt
	
	If you have any comment or update to the content, please contact the
	original document maintainer directly.  However, if you have a problem
	communicating in English you can also ask the Chinese maintainer for
	help.  Contact the Chinese maintainer if this translation is outdated
	or if there is a problem with the translation.
	
	Maintainer: Mauro Carvalho Chehab <mchehab@infradead.org>
	Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
	---------------------------------------------------------------------
	Documentation/video4linux/v4l2-framework.txt 的中文翻译
	
	如果想评论或更新本文的内容，请直接�系原文档的维护者。如果你使用英文
	交�有困难的�，也�以�中文版维护者求助。如果本翻译更新��时或者翻
	译存在问题，请�系中文版维护者。
	英文版维护者： Mauro Carvalho Chehab <mchehab@infradead.org>
	中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
	中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
	中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com>
	
	
	以下为正文
	---------------------------------------------------------------------
	V4L2 驱动框架概览
	==============
	
	本文档�述 V4L2 框架所�供的��结构和它们之间的关系。
	
	
	介�
	----
	
	大部分现代 V4L2 设备由多个 IC 组�，在 /dev 下导出多个设备节点，
	并�时创建� V4L2 设备（如 DVB�ALSA�FB�I2C 和红外输入设备）。
	由于这�硬件的��性，V4L2 驱动也�得�常��。
	
	尤其是 V4L2 必须支� IC 实现音视频的多路�用和编解�，这就更增加了其
	��性。通常这些 IC 通过一个或多个 I2C 总线连接到主桥驱动器，但也�
	使用其他总线。这些设备称为“�设备�。
	
	长期以�，这个框架仅�于通过 video_device 结构体创建 V4L 设备节点，
	并使用 video_buf 处�视频缓冲（注：本文�讨论 video_buf 框架）。
	
	这�味�所有驱动必须自己设置设备实例并连接到�设备。其中一部分�正确地
	完�是比较��的，使得许多驱动都没有正确地实现。
	
	由于框架的缺失，有很多通用代�都����利用。
	
	因此，这个框架构建所有驱动都需�的基本结构�，而统一的框架将使通用代�
	创建�实用函数并在所有驱动中共享�得更加容易。
	
	
	驱动结构
	-------
	
	所有 V4L2 驱动都有如下结构：
	
	1) �个设备实例的结构体--包�其设备状�。
	
	2) �始化和控制�设备的方法（如果有）。
	
	3) 创建 V4L2 设备节点 (/dev/videoX�/dev/vbiX 和 /dev/radioX)
	   并跟踪设备节点的特定数�。
	
	4) 特定文件�柄结构体--包��个文件�柄的数�。
	
	5) 视频缓冲处�。
	
	以下是它们的�略关系图：
	
	    device instances（设备实例）
	      |
	      +-sub-device instances（�设备实例）
	      |
	      \-V4L2 device nodes（V4L2 设备节点）
		  |
		  \-filehandle instances（文件�柄实例）
	
	
	框架结构
	-------
	
	该框架�常类似驱动结构：它有一个 v4l2_device 结构用于�存设备
	实例的数�；一个 v4l2_subdev 结构体代表�设备实例；video_device
	结构体�存 V4L2 设备节点的数�；将� v4l2_fh 结构体将跟踪文件�柄
	实例（暂未尚未实现）。
	
	V4L2 框架也�与媒体框架整�（�选的）。如果驱动设置了 v4l2_device
	结构体的 mdev 域，�设备和视频节点的入�将自动出现在媒体框架中。
	
	
	v4l2_device 结构体
	----------------
	
	�个设备实例都通过 v4l2_device (v4l2-device.h)结构体�表示。
	简�设备�以仅分�这个结构体，但在大多数情况下，都会将这个结构体
	嵌入到一个更大的结构体中。
	
	你必须注册这个设备实例：
	
		v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
	
	注册�作将会�始化 v4l2_device 结构体。如果 dev->driver_data 域
	为 NULL，就将其指� v4l2_dev。
	
	需�与媒体框架整�的驱动必须手动设置 dev->driver_data，指�包�
	v4l2_device 结构体实例的驱动特定设备结构体。这�以在注册 V4L2 设备
	实例�通过 dev_set_drvdata() 函数完�。�时必须设置 v4l2_device
	结构体的 mdev 域，指�适当的�始化并注册过的 media_device 实例。
	
	如果 v4l2_dev->name 为空，则它将被设置为从 dev 中�生出的值（为了
	更加精确，形�为驱动��跟 bus_id）。如果你在调用 v4l2_device_register
	�已�设置好了，则�会被修改。如果 dev 为 NULL，则你*必须*在调用
	v4l2_device_register �设置 v4l2_dev->name。
	
	你�以基于驱动�和驱动的全局 atomic_t 类型的实例编�，通过
	v4l2_device_set_name() 设置 name。这样会生�类似 ivtv0�ivtv1 等
	�字。若驱动�以数字结尾，则会在编�和驱动�间�入一个破折�，如：
	cx18-0�cx18-1 等。此函数返回实例编�。
	
	第一个 “dev� �数通常是一个指� pci_dev�usb_interface 或
	platform_device 的指针。很少使其为 NULL，除�是一个ISA设备或者
	当一个设备创建了多个 PCI 设备，使得 v4l2_dev 无法与一个特定的父设备
	关�。
	
	你也�以�供一个 notify() 回调，使�设备�以调用它实现事件通知。
	但这个设置与�设备相关。�设备支�的任何通知必须在
	include/media/<subdevice>.h 中定义一个消�头。
	
	注销 v4l2_device 使用如下函数：
	
		v4l2_device_unregister(struct v4l2_device *v4l2_dev);
	
	如果 dev->driver_data 域指� v4l2_dev，将会被�置为 NULL。注销�时
	会自动从设备中注销所有�设备。
	
	如果你有一个热�拔设备（如USB设备），则当断开�生时，父设备将无效。
	由于 v4l2_device 有一个指�父设备的指针必须被清除，�时标志父设备
	已消失，所以必须调用以下函数：
	
		v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
	
	这个函数并*�*注销�设备，因此你�然�调用 v4l2_device_unregister()
	函数。如果你的驱动器并�热�拔的，就没有必�调用 v4l2_device_disconnect()。
	
	有时你需��历所有被特定驱动注册的设备。这通常�生在多个设备驱动使用
	�一个硬件的情况下。如：ivtvfb 驱动是一个使用 ivtv 硬件的帧缓冲驱动，
	�时 alsa 驱动也使用此硬件。
	
	你�以使用如下例程�历所有注册的设备：
	
	static int callback(struct device *dev, void *p)
	{
		struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
	
		/* 测试这个设备是�已��始化 */
		if (v4l2_dev == NULL)
			return 0;
		...
		return 0;
	}
	
	int iterate(void *p)
	{
		struct device_driver *drv;
		int err;
	
		/* 在PCI 总线上查找ivtv驱动。
		   pci_bus_type是全局的. 对于USB总线使用usb_bus_type。 */
		drv = driver_find("ivtv", &pci_bus_type);
		/* �历所有的ivtv设备实例 */
		err = driver_for_each_device(drv, NULL, p, callback);
		put_driver(drv);
		return err;
	}
	
	有时你需�一个设备实例的�行计数。这个通常用于映射一个设备实例到一个
	模�选择数组的索引。
	
	推�方法如下：
	
	static atomic_t drv_instance = ATOMIC_INIT(0);
	
	static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
	{
		...
		state->instance = atomic_inc_return(&drv_instance) - 1;
	}
	
	如果你有多个设备节点，对于热�拔设备，知�何时注销 v4l2_device 结构体
	就比较困难。为此 v4l2_device 有引用计数支�。当调用 video_register_device
	时增加引用计数，而设备节点释放时��引用计数。当引用计数为零，则
	v4l2_device 的release() 回调将被执行。你就�以在此时�最�的清�工作。
	
	如果创建了其他设备节点（比如 ALSA），则你�以通过以下函数手动增�
	引用计数：
	
	void v4l2_device_get(struct v4l2_device *v4l2_dev);
	
	或:
	
	int v4l2_device_put(struct v4l2_device *v4l2_dev);
	
	由于引用技术�始化为 1 ，你也需�在 disconnect() 回调（对于 USB 设备）中
	调用 v4l2_device_put，或者 remove() 回调（例如对于 PCI 设备），�则
	引用计数将永远�会为 0 。
	
	v4l2_subdev结构体
	------------------
	
	许多驱动需�与�设备通信。这些设备�以完���任务，但通常他们负责
	音视频�用和编解�。如网络摄�头的�设备通常是传感器和摄�头控制器。
	
	这些一般为 I2C 接�设备，但并�一定都是。为了给驱动�供调用�设备的
	统一接�，v4l2_subdev 结构体（v4l2-subdev.h）产生了。
	
	�个�设备驱动都必须有一个 v4l2_subdev 结构体。这个结构体�以�独
	代表一个简�的�设备，也�以嵌入到一个更大的结构体中，与更多设备状�
	信��存在一起。通常有一个下级设备结构体（比如：i2c_client）包�了
	内核创建的设备数�。建议使用 v4l2_set_subdevdata() 将这个结构体的
	指针�存在 v4l2_subdev 的�有数�域(dev_priv)中。这使得通过 v4l2_subdev
	找到实际的低层总线特定设备数��得容易。
	
	你�时需�一个从低层结构体获� v4l2_subdev 指针的方法。对于常用的
	i2c_client 结构体，i2c_set_clientdata() 函数�用于�存一个 v4l2_subdev
	指针；对于其他总线你�能需�使用其他相关函数。
	
	桥驱动中也应�存�个�设备的�有数�，比如一个指�特定桥的�设备�有
	数�的指针。为此 v4l2_subdev 结构体�供主机�有数�域(host_priv)，
	并�通过 v4l2_get_subdev_hostdata() 和 v4l2_set_subdev_hostdata()
	访问。
	
	从总线桥驱动的视角，驱动加载�设备模�并以��方�获得 v4l2_subdev
	结构体指针。对于 i2c 总线设备相对简�：调用 i2c_get_clientdata()。
	对于其他总线也需��类似的�作。针对 I2C 总线上的�设备辅助函数帮你
	完�了大部分��的工作。
	
	�个 v4l2_subdev 都包��设备驱动需�实现的函数指针（如果对此设备
	�适用，�为NULL）。由于�设备�完�许多��的工作，而在一个庞大的
	函数指针结构体中通常仅有少数有用的函数实现其功能肯定��适。所以，
	函数指针根�其实现的功能被分类，�一类都有自己的函数指针结构体。
	
	顶层函数指针结构体包�了指��类函数指针结构体的指针，如果�设备驱动
	�支�该类函数中的任何一个功能，则指�该类结构体的指针为NULL。
	
	这些结构体定义如下：
	
	struct v4l2_subdev_core_ops {
		int (*g_chip_ident)(struct v4l2_subdev *sd, struct v4l2_dbg_chip_ident *chip);
		int (*log_status)(struct v4l2_subdev *sd);
		int (*init)(struct v4l2_subdev *sd, u32 val);
		...
	};
	
	struct v4l2_subdev_tuner_ops {
		...
	};
	
	struct v4l2_subdev_audio_ops {
		...
	};
	
	struct v4l2_subdev_video_ops {
		...
	};
	
	struct v4l2_subdev_pad_ops {
		...
	};
	
	struct v4l2_subdev_ops {
		const struct v4l2_subdev_core_ops  *core;
		const struct v4l2_subdev_tuner_ops *tuner;
		const struct v4l2_subdev_audio_ops *audio;
		const struct v4l2_subdev_video_ops *video;
		const struct v4l2_subdev_pad_ops *video;
	};
	
	其中 core（核心）函数集通常�用于所有�设备，其他类别的实现�赖于
	�设备。如视频设备�能�支�音频�作函数，�之亦然。
	
	这样的设置在�制了函数指针数�的�时，还使增加新的�作函数和分类
	�得较为容易。
	
	�设备驱动�使用如下函数�始化 v4l2_subdev 结构体：
	
		v4l2_subdev_init(sd, &ops);
	
	然�，你必须用一个唯一的�字�始化 subdev->name，并�始化模�的
	owner 域。若使用 i2c 辅助函数，这些都会帮你处�好。
	
	若需�媒体框架整�，你必须调用 media_entity_init() �始化 v4l2_subdev
	结构体中的 media_entity 结构体（entity 域）：
	
		struct media_pad *pads = &my_sd->pads;
		int err;
	
		err = media_entity_init(&sd->entity, npads, pads, 0);
	
	pads 数组必须预先�始化。无须手动设置 media_entity 的 type 和
	name 域，但如有必�，revision 域必须�始化。
	
	当（任何）�设备节点被打开/关闭，对 entity 的引用将被自动获�/释放。
	
	在�设备被注销之�，��忘记清� media_entity 结构体：
	
		media_entity_cleanup(&sd->entity);
	
	如果�设备驱动趋�于处�视频并整�进了媒体框架，必须使用 v4l2_subdev_pad_ops
	替代 v4l2_subdev_video_ops 实现格�相关的功能。
	
	这�情况下，�设备驱动应该设置 link_validate 域，以�供它自身的链接
	验�函数。链接验�函数应对管�（两端链接的都是 V4L2 �设备）中的�个
	链接调用。驱动还�负责验��设备和视频节点间格��置的正确性。
	
	如果 link_validate �作没有设置，默认的 v4l2_subdev_link_validate_default()
	函数将会被调用。这个函数��宽�高和媒体总线�素格�在链接的收�两端
	都一致。�设备驱动除了它们自己的检测外，也�以自由使用这个函数以执行
	上��到的检查。
	
	设备（桥）驱动程�必须� v4l2_device 注册 v4l2_subdev：
	
		int err = v4l2_device_register_subdev(v4l2_dev, sd);
	
	如果�设备模�在它注册�消失，这个�作�能失败。在这个函数�功返回�，
	subdev->dev 域就指�了 v4l2_device。
	
	如果 v4l2_device 父设备的 mdev 域为� NULL 值，则�设备实体将被自动
	注册为媒体设备。
	
	注销�设备则�用如下函数：
	
		v4l2_device_unregister_subdev(sd);
	
	此�，�设备模�就��载，且 sd->dev == NULL。
	
	注册之设备�，�通过以下方�直接调用其�作函数：
	
		err = sd->ops->core->g_chip_ident(sd, &chip);
	
	但使用如下�会比较容易且�适：
	
		err = v4l2_subdev_call(sd, core, g_chip_ident, &chip);
	
	这个�将会� NULL 指针检查，如果 subdev 为 NULL，则返回-ENODEV；如果
	subdev->core 或 subdev->core->g_chip_ident 为 NULL，则返回 -ENOIOCTLCMD；
	�则将返回 subdev->ops->core->g_chip_ident ops 调用的实际结果。
	
	有时也�能�时调用所有或一系列�设备的�个�作函数：
	
		v4l2_device_call_all(v4l2_dev, 0, core, g_chip_ident, &chip);
	
	任何�支�此�作的�设备都会被跳过，并忽略错误返回值。但如果你需�
	检查出错�，则�使用如下函数：
	
		err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_chip_ident, &chip);
	
	除 -ENOIOCTLCMD 外的任何错误都会跳出循环并返回错误值。如果（除 -ENOIOCTLCMD
	外）没有错误�生，则返回 0。
	
	对于以上两个函数的第二个�数为组 ID。如果为 0，则所有�设备都会执行
	这个�作。如果为� 0 值，则�有那些组 ID 匹�的�设备�会执行此�作。
	在桥驱动注册一个�设备�，�以设置 sd->grp_id 为任何期望值（默认值为
	0）。这个值属于桥驱动，且�设备驱动将�会修改和使用它。
	
	组 ID 赋予了桥驱动更多对于如何调用回调的控制。例如，电路�上有多个
	音频芯片，�个都有改�音�的能力。但当用户想�改�音�的时候，通常
	�有一个会被实际使用。你�以对这样的�设备设置组 ID 为（例如 AUDIO_CONTROLLER）
	并在调用 v4l2_device_call_all() 时指定它为组 ID 值。这就��了�有
	需�的�设备�会执行这个回调。
	
	如果�设备需�通知它的 v4l2_device 父设备一个事件，�以调用
	v4l2_subdev_notify(sd, notification, arg)。这个�检查是�有一个
	notify() 回调被注册，如果没有，返回 -ENODEV。�则返回 notify() 调用
	结果。
	
	使用 v4l2_subdev 的好处在于它是一个通用结构体，且�包�任何底层硬件
	信�。所有驱动�以包�多个 I2C 总线的�设备，但也有�设备是通过 GPIO
	控制。这个区别仅在�置设备时有关系，一旦�设备注册完�，对于 v4l2
	�系统�说就完全�明了。
	
	
	V4L2 �设备用户空间API
	--------------------
	
	除了通过 v4l2_subdev_ops 结构导出的内核 API，V4L2 �设备也�以直接
	通过用户空间应用程��控制。
	
	�以在 /dev 中创建�为 v4l-subdevX 设备节点，以通过其直接访问�设备。
	如果�设备支�用户空间直接�置，必须在注册�设置 V4L2_SUBDEV_FL_HAS_DEVNODE
	标志。
	
	注册�设备之�， v4l2_device 驱动会通过调用 v4l2_device_register_subdev_nodes()
	函数为所有已注册并设置了 V4L2_SUBDEV_FL_HAS_DEVNODE 的�设备创建
	设备节点。这些设备节点会在�设备注销时自动删除。
	
	这些设备节点处� V4L2 API 的一个�集。
	
	VIDIOC_QUERYCTRL
	VIDIOC_QUERYMENU
	VIDIOC_G_CTRL
	VIDIOC_S_CTRL
	VIDIOC_G_EXT_CTRLS
	VIDIOC_S_EXT_CTRLS
	VIDIOC_TRY_EXT_CTRLS
	
		这些 ioctls 控制与 V4L2 中定义的一致。他们行为相�，唯一的
		��是他们�处��设备的控制实现。根�驱动程�，这些控制也
		�以通过一个（或多个） V4L2 设备节点访问。
	
	VIDIOC_DQEVENT
	VIDIOC_SUBSCRIBE_EVENT
	VIDIOC_UNSUBSCRIBE_EVENT
	
		这些  ioctls 事件与 V4L2 中定义的一致。他们行为相�，唯一的
		��是他们�处��设备产生的事件。根�驱动程�，这些事件也
		�以通过一个（或多个） V4L2 设备节点上报。
	
		�使用事件通知的�设备驱动，在注册�设备�必须在 v4l2_subdev::flags
		中设置 V4L2_SUBDEV_USES_EVENTS 并在 v4l2_subdev::nevents
		中�始化事件队列深度。注册完��，事件会在 v4l2_subdev::devnode
		设备节点中�通常一样被排队。
	
		为正确支�事件机制，poll() 文件�作也应被实现。
	
	�有 ioctls
	
		�在以上列表中的所有 ioctls 会通过 core::ioctl �作直接传递
		给�设备驱动。
	
	
	I2C �设备驱动
	-------------
	
	由于这些驱动很常�，所以内特�供了特定的辅助函数(v4l2-common.h)让这些
	设备的使用更加容易。
	
	添加 v4l2_subdev 支�的推�方法是让 I2C 驱动将 v4l2_subdev 结构体
	嵌入到为�个 I2C 设备实例创建的状�结构体中。而最简�的设备没有状�
	结构体，此时�以直接创建一个 v4l2_subdev 结构体。
	
	一个典型的状�结构体如下所示（‘chipname’用芯片�代替）：
	
	struct chipname_state {
		struct v4l2_subdev sd;
		...  /* 附加的状�域*/
	};
	
	�始化 v4l2_subdev 结构体的方法如下：
	
		v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
	
	这个函数将填充 v4l2_subdev 结构体中的所有域，并�� v4l2_subdev 和
	i2c_client 都指�彼此。
	
	�时，你也应该为从 v4l2_subdev 指针找到 chipname_state 结构体指针
	添加一个辅助内�函数。
	
	static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
	{
		return container_of(sd, struct chipname_state, sd);
	}
	
	使用以下函数�以通过 v4l2_subdev 结构体指针获得 i2c_client 结构体
	指针：
	
		struct i2c_client *client = v4l2_get_subdevdata(sd);
	
	而以下函数则相�，通过 i2c_client 结构体指针获得 v4l2_subdev 结构体
	指针：
	
		struct v4l2_subdev *sd = i2c_get_clientdata(client);
	
	当 remove()函数被调用�，必须��先调用 v4l2_device_unregister_subdev(sd)。
	此�作将会从桥驱动中注销�设备。�使�设备没有注册，调用此函数也是
	安全的。
	
	必须这样�的原因是：当桥驱动注销 i2c 适�器时，remove()回调函数
	会被那个适�器上的 i2c 设备调用。此�，相应的 v4l2_subdev 结构体
	就�存在了，所有它们必须先被注销。在 remove()回调函数中调用
	v4l2_device_unregister_subdev(sd)，�以��执行总是正确的。
	
	
	桥驱动也有一些辅组函数�用：
	
	struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
		       "module_foo", "chipid", 0x36, NULL);
	
	这个函数会加载给定的模�（如果没有模�需�加载，�以为 NULL），
	并用给定的 i2c 适�器结构体指针（i2c_adapter）和 器件地�（chip/address）
	作为�数调用 i2c_new_device()。如果一切顺利，则就在 v4l2_device
	中注册了�设备。
	
	你也�以利用 v4l2_i2c_new_subdev()的最�一个�数，传递一个�能的
	I2C 地�数组，让函数自动探测。这些探测地��有在�一个�数为 0 的
	情况下使用。�零�数�味�你知�准确的 i2c 地�，所以此时无须进行
	探测。
	
	如果出错，两个函数都返回 NULL。
	
	注�：传递给 v4l2_i2c_new_subdev()的 chipid 通常与模��一致。
	它�许你指定一个芯片的�体，比如“saa7114�或“saa7115�。一般通过
	i2c 驱动自动探测。chipid 的使用是在今�需�深入了解的事情。这个与
	i2c 驱动��，较容易混淆。�知�支�哪些芯片�体，你�以查阅 i2c
	驱动代�的 i2c_device_id 表，上�列出了所有�能支�的芯片。
	
	还有两个辅助函数：
	
	v4l2_i2c_new_subdev_cfg：这个函数添加新的 irq 和 platform_data
	�数，并有‘addr’和‘probed_addrs’�数：如果 addr �零，则被使用
	（�探测�体），�则 probed_addrs 中的地�将用于自动探测。
	
	例如：以下代�将会探测地�（0x10）：
	
	struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
		       "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
	
	v4l2_i2c_new_subdev_board 使用一个 i2c_board_info 结构体，将其
	替代 irq�platform_data 和 add r�数传递给 i2c 驱动。
	
	如果�设备支� s_config 核心�作，这个�作会在�设备�置好之�以 irq 和
	platform_data 为�数调用。早期的 v4l2_i2c_new_(probed_)subdev 函数
	�样也会调用 s_config，但仅在 irq 为 0 且 platform_data 为 NULL 时。
	
	video_device结构体
	-----------------
	
	在 /dev 目录下的实际设备节点根� video_device 结构体(v4l2-dev.h)
	创建。此结构体既�以动�分�也�以嵌入到一个更大的结构体中。
	
	动�分�方法如下：
	
		struct video_device *vdev = video_device_alloc();
	
		if (vdev == NULL)
			return -ENOMEM;
	
		vdev->release = video_device_release;
	
	如果将其嵌入到一个大结构体中，则必须自己实现 release()回调。
	
		struct video_device *vdev = &my_vdev->vdev;
	
		vdev->release = my_vdev_release;
	
	release()回调必须被设置，且在最�一个 video_device 用户退出之�
	被调用。
	
	默认的 video_device_release()回调�是调用 kfree �释放之�分�的
	内存。
	
	你应该设置这些域：
	
	- v4l2_dev: 设置为 v4l2_device 父设备。
	
	- name: 设置为唯一的�述性设备�。
	
	- fops: 设置为已有的 v4l2_file_operations 结构体。
	
	- ioctl_ops: 如果你使用v4l2_ioctl_ops �简化 ioctl 的维护
	  (强烈建议使用，且将��能�为强制性的!)，然�设置你自己的
	  v4l2_ioctl_ops 结构体.
	
	- lock: 如果你�在驱动中实现所有的��作，则设为 NULL 。�则
	  就�设置一个指� struct mutex_lock 结构体的指针，这个�将
	  在 unlocked_ioctl 文件�作被调用�由内核获得，并在调用返回�
	  释放。详�下一节。
	
	- prio: ��对优先级的跟踪。用于实现 VIDIOC_G/S_PRIORITY。如果
	  设置为 NULL，则会使用 v4l2_device 中的 v4l2_prio_state 结构体。
	  如果�对�个设备节点（组）实现独立的优先级，�以将其指�自己
	  实现的 v4l2_prio_state 结构体。
	
	- parent: 仅在使用 NULL 作为父设备结构体�数注册 v4l2_device 时
	  设置此�数。�有在一个硬件设备包�多一个 PCI 设备，共享�一个
	  v4l2_device 核心时�会�生。
	
	  cx88 驱动就是一个例�：一个 v4l2_device 结构体核心，被一个裸的
	  视频 PCI 设备(cx8800)和一个 MPEG PCI 设备(cx8802)共用。由于
	  v4l2_device 无法与特定的 PCI 设备关�，所有没有设置父设备。但当
	  video_device �置�，就知�使用哪个父 PCI 设备了。
	
	- flags：�选。如果你�让框架处�设置 VIDIOC_G/S_PRIORITY ioctls，
	  请设置 V4L2_FL_USE_FH_PRIO。这�求你使用 v4l2_fh 结构体。
	  一旦所有驱动使用了核心的优先级处�，最终这个标志将消失。但现在它
	  必须被显�设置。
	
	如果你使用 v4l2_ioctl_ops，则应该在 v4l2_file_operations 结构体中
	设置 .unlocked_ioctl 指� video_ioctl2。
	
	请勿使用 .ioctl�它已被废弃，今�将消失。
	
	�些情况下你�告诉核心：你在 v4l2_ioctl_ops 指定的�个函数应被忽略。
	你�以在 video_device_register 被调用�通过以下函数标记这个 ioctls。
	
	void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd);
	
	基于外部因素（例如�个��已被使用），在�创建新结构体的情况下，你想
	�关闭 v4l2_ioctl_ops 中�个特性往往需�这个机制。
	
	v4l2_file_operations 结构体是 file_operations 的一个�集。其主�
	区别在于：因 inode �数从未被使用，它将被忽略。
	
	如果需�与媒体框架整�，你必须通过调用 media_entity_init() �始化
	嵌入在 video_device 结构体中的 media_entity（entity 域）结构体：
	
		struct media_pad *pad = &my_vdev->pad;
		int err;
	
		err = media_entity_init(&vdev->entity, 1, pad, 0);
	
	pads 数组必须预先�始化。没有必�手动设置 media_entity 的 type 和
	name 域。
	
	当（任何）�设备节点被打开/关闭，对 entity 的引用将被自动获�/释放。
	
	v4l2_file_operations 与�
	--------------------------
	
	你�以在 video_device 结构体中设置一个指� mutex_lock 的指针。通常
	这既�是一个顶层互斥�也�为设备节点自身的互斥�。默认情况下，此�
	用于 unlocked_ioctl，但为了使用 ioctls 你通过以下函数��用�定：
	
		void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd);
	
	例如: v4l2_disable_ioctl_locking(vdev, VIDIOC_DQBUF);
	
	你必须在注册 video_device �调用这个函数。
	
	特别是对于 USB 驱动程�，�些命令（如设置控制）需�很长的时间，�能
	需�自行为缓冲区队列的 ioctls 实现�定。
	
	如果你需�更细粒度的�，你必须设置 mutex_lock 为 NULL，并完全自己实现
	�机制。
	
	这完全由驱动开�者决定使用何�方法。然而，如果你的驱动存在长延时�作
	（例如，改� USB 摄�头的�光时间�能需�较长时间），而你�想让用户
	在等待长延时�作完�期间�其他的事，则你最好自己实现�机制。
	
	如果指定一个�，则所有 ioctl �作将在这个�的作用下串行执行。如果你
	使用 videobuf，则必须将�一个�传递给 videobuf 队列�始化函数；如
	videobuf 必须等待一帧的到达，则�临时解�并在这之��新上�。如果驱动
	也在代�执行期间等待，则���样的工作（临时解�，�上�）让其他进程
	�以在第一个进程阻塞时访问设备节点。
	
	在使用 videobuf2 的情况下，必须实现 wait_prepare 和 wait_finish 回调
	在适当的时候解�/加�。进一步�说，如果你在 video_device 结构体中使用
	�，则必须在 wait_prepare 和 wait_finish 中对这个互斥�进行解�/加�。
	
	热�拔的断开实现也必须在调用 v4l2_device_disconnect �获得�。
	
	video_device注册
	---------------
	
	接下�你需�注册视频设备：这会为你创建一个字符设备。
	
		err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
		if (err) {
			video_device_release(vdev); /* or kfree(my_vdev); */
			return err;
		}
	
	如果 v4l2_device 父设备的 mdev 域为� NULL 值，视频设备实体将自动
	注册为媒体设备。
	
	注册哪�设备是根�类型（type）�数。存在以下类型：
	
	VFL_TYPE_GRABBER: 用于视频输入/输出设备的 videoX
	VFL_TYPE_VBI: 用于垂直消�数�的 vbiX (例如，���字幕，图文电视)
	VFL_TYPE_RADIO: 用于广播调�器的 radioX
	
	最�一个�数让你确定一个所控制设备的设备节点�数�(例如 videoX 中的 X)。
	通常你�以传入-1，让 v4l2 框架自己选择第一个空闲的编�。但是有时用户
	需�选择一个特定的节点�。驱动�许用户通过驱动模��数选择一个特定的
	设备节点�是很普�的。这个编�将会传递给这个函数，且 video_register_device
	将会试图选择这个设备节点�。如果这个编�被�用，下一个空闲的设备节点
	编�将被选中，并�内核日志中��一个警告信�。
	
	�一个使用场景是当驱动创建多个设备时。这�情况下，对��的视频设备在
	编�上使用��的范围是很有用的。例如，视频�获设备从 0 开始，视频
	输出设备从 16 开始。所以你�以使用最�一个�数�指定设备节点�最�值，
	而 v4l2 框架会试图选择第一个的空闲编�（等于或大于你�供的编�）。
	如果失败，则它会就选择第一个空闲的编�。
	
	由于这�情况下，你会忽略无法选择特定设备节点�的警告，则�调用
	video_register_device_no_warn() 函数��警告信�的产生。
	
	��设备节点被创建，一些属性也会�时创建。在 /sys/class/video4linux
	目录中你会找到这些设备。例如进入其中的 video0 目录，你会看到‘name’和
	‘index’属性。‘name’属性值就是 video_device 结构体中的‘name’域。
	
	‘index’属性值就是设备节点的索引值：�次调用 video_register_device()，
	索引值都递增 1 。第一个视频设备节点总是从索引值 0 开始。
	
	用户�以设置 udev 规则，利用索引属性生�花哨的设备�（例如：用‘mpegX’
	代表 MPEG 视频�获设备节点）。
	
	在设备�功注册�，就�以使用这些域：
	
	- vfl_type: 传递给 video_register_device 的设备类型。
	- minor: 已指派的次设备�。
	- num: 设备节点编� (例如 videoX 中的 X)。
	- index: 设备索引�。
	
	如果注册失败，你必须调用 video_device_release() �释放已分�的
	video_device 结构体；如果 video_device 是嵌入在自己创建的结构体中，
	你也必须释放它。vdev->release() 回调�会在注册失败之�被调用，
	你也�应试图在注册失败�注销设备。
	
	
	video_device 注销
	----------------
	
	当视频设备节点已被移除，�论是�载驱动还是USB设备断开，你都应注销
	它们：
	
		video_unregister_device(vdev);
	
	这个�作将从 sysfs 中移除设备节点（导致 udev 将其从 /dev 中移除）。
	
	video_unregister_device() 返回之�，就无法完�打开�作。尽管如此，
	USB 设备的情况则��，�些应用程��能�然打开�其中一个已注销设备
	节点。所以在注销之�，所有文件�作（当然除了 release ）也应返回错误值。
	
	当最�一个视频设备节点的用户退出，则 vdev->release() 回调会被调用，
	并且你�以�最�的清��作。
	
	��忘记清�与视频设备相关的媒体入�（如果被�始化过）：
	
		media_entity_cleanup(&vdev->entity);
	
	这�以在 release 回调中完�。
	
	
	video_device 辅助函数
	---------------------
	
	一些有用的辅助函数如下：
	
	- file/video_device �有数�
	
	你�以用以下函数在 video_device 结构体中设置/获�驱动�有数�：
	
	void *video_get_drvdata(struct video_device *vdev);
	void video_set_drvdata(struct video_device *vdev, void *data);
	
	注�：在调用 video_register_device() �执行 video_set_drvdata()
	是安全的。
	
	而以下函数：
	
	struct video_device *video_devdata(struct file *file);
	
	返回 file 结构体中拥有的的 video_device 指针。
	
	video_drvdata 辅助函数结�了 video_get_drvdata 和 video_devdata
	的功能：
	
	void *video_drvdata(struct file *file);
	
	你�以使用如下代�从 video_device 结构体中获� v4l2_device 结构体
	指针：
	
	struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
	
	- 设备节点�
	
	video_device 设备节点在内核中的�称�以通过以下函数获得
	
	const char *video_device_node_name(struct video_device *vdev);
	
	这个�字被用户空间工具（例如 udev）作为�示信�使用。应尽�能使用
	此功能，而�访问 video_device::num 和 video_device::minor 域。
	
	
	视频缓冲辅助函数
	---------------
	
	v4l2 核心 API �供了一个处�视频缓冲的标准方法(称为“videobuf�)。
	这些方法使驱动�以通过统一的方�实现 read()�mmap() 和 overlay()。
	目�在设备上支�视频缓冲的方法有分散/�集 DMA(videobuf-dma-sg)�
	线性 DMA(videobuf-dma-contig)以�大多用于 USB 设备的用 vmalloc
	分�的缓冲(videobuf-vmalloc)。
	
	请�阅 Documentation/video4linux/videobuf，以获得更多关于 videobuf
	层的使用信�。
	
	v4l2_fh 结构体
	-------------
	
	v4l2_fh 结构体�供一个�存用于 V4L2 框架的文件�柄特定数�的简�方法。
	如果 video_device 的 flag 设置了 V4L2_FL_USE_FH_PRIO 标志，新驱动
	必须使用 v4l2_fh 结构体，因为它也用于实现优先级处�（VIDIOC_G/S_PRIORITY）。
	
	v4l2_fh 的用户（�于 V4l2 框架中，并�驱动）�通过测试
	video_device->flags 中的 V4L2_FL_USES_V4L2_FH �得知驱动是�使用
	v4l2_fh 作为他的 file->private_data 指针。这个�会在调用 v4l2_fh_init()
	时被设置。
	
	v4l2_fh 结构体作为驱动自身文件�柄结构体的一部分被分�，且驱动在
	其打开函数中将 file->private_data 指�它。
	
	在许多情况下，v4l2_fh 结构体会嵌入到一个更大的结构体中。这钟情况下，
	应该在 open() 中调用 v4l2_fh_init+v4l2_fh_add，并在 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 函数使用的简介：
	
	void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
	
	  �始化文件�柄。这*必须*在驱动的 v4l2_file_operations->open()
	  函数中执行。
	
	void v4l2_fh_add(struct v4l2_fh *fh)
	
	  添加一个 v4l2_fh 到 video_device 文件�柄列表。一旦文件�柄
	  �始化完�就必须调用。
	
	void v4l2_fh_del(struct v4l2_fh *fh)
	
	  从 video_device() 中解除文件�柄的关�。文件�柄的退出函数也
	  将被调用。
	
	void v4l2_fh_exit(struct v4l2_fh *fh)
	
	  清�文件�柄。在清�完 v4l2_fh �，相关内存会被释放。
	
	
	如果 v4l2_fh �是嵌入在其他结构体中的，则�以用这些辅助函数：
	
	int v4l2_fh_open(struct file *filp)
	
	  分�一个 v4l2_fh 结构体空间，�始化并将其添加到 file 结构体相关的
	  video_device 结构体中。
	
	int v4l2_fh_release(struct file *filp)
	
	  从 file 结构体相关的 video_device 结构体中删除 v4l2_fh ，清�
	  v4l2_fh 并释放空间。
	
	这两个函数�以�入到 v4l2_file_operation 的 open() 和 release()
	�作中。
	
	
	�些驱动需�在第一个文件�柄打开和最�一个文件�柄关闭的时候�些
	工作。所以加入了两个辅助函数以检查 v4l2_fh 结构体是�是相关设备
	节点打开的唯一文件�柄。
	
	int v4l2_fh_is_singular(struct v4l2_fh *fh)
	
	  如果此文件�柄是唯一打开的文件�柄，则返回 1 ，�则返回 0 。
	
	int v4l2_fh_is_singular_file(struct file *filp)
	
	  功能相�，但通过 filp->private_data 调用 v4l2_fh_is_singular。
	
	
	V4L2 事件机制
	-----------
	
	V4L2 事件机制�供了一个通用的方法将事件传递到用户空间。驱动必须使用
	v4l2_fh �能支� V4L2 事件机制。
	
	
	事件通过一个类型和选择 ID �定义。ID 对应一个 V4L2 对象，例如
	一个控制 ID。如果未使用，则 ID 为 0。
	
	当用户订阅一个事件，驱动会为此分�一些 kevent 结构体。所以�个
	事件组（类型�ID）都会有自己的一套 kevent 结构体。这��了如果
	一个驱动短时间内产生了许多�类事件，�会覆盖其他类型的事件。
	
	但如果你收到的事件数�大于�类事件 kevent 的�存数�，则最早的
	事件将被丢弃，并加入新事件。
	
	此外，v4l2_subscribed_event 结构体内部有�供驱动设置的 merge() 和
	replace() 回调，这些回调会在新事件产生且没有多余空间的时候被调用。
	replace() 回调让你�以将早期事件的净�替�为新事件的净�，将早期
	净�的相关数��并到替�进�的新净�中。当该类型的事件仅分�了一个
	kevent 结构体时，它将被调用。merge() 回调让你�以�并最早的事件净�
	到在它之�的那个事件净�中。当该类型的事件分�了两个或更多 kevent
	结构体时，它将被调用。
	
	这�方法�会有状�信�丢失，�会导致中间步骤信�丢失。
	
	
	关于 replace/merge 回调的一个�错的例�在 v4l2-event.c 中：用于
	控制事件的 ctrls_replace() 和 ctrls_merge() 回调。
	
	注�：这些回调�以在中断上下文中调用，所以它们必须尽快完�并退出。
	
	有用的函数：
	
	void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev)
	
	  将事件加入视频设备的队列。驱动仅负责填充 type 和 data 域。
	  其他域由 V4L2 填充。
	
	int v4l2_event_subscribe(struct v4l2_fh *fh,
				 struct v4l2_event_subscription *sub, unsigned elems,
				 const struct v4l2_subscribed_event_ops *ops)
	
	  video_device->ioctl_ops->vidioc_subscribe_event 必须检测驱动能
	  产生特定 id 的事件。然�调用 v4l2_event_subscribe() �订阅该事件。
	
	  elems �数是该事件的队列大�。若为 0，V4L2 框架将会（根�事件类型）
	  填充默认值。
	
	  ops �数�许驱动指定一系列回调：
	  * add:     当添加一个新监�者时调用（��订阅�一个事件，此回调
	             仅被执行一次）。
	  * del:     当一个监�者�止监�时调用。
	  * replace: 用‘新’事件替�‘早期‘事件。
	  * merge:   将‘早期‘事件�并到‘新’事件中。
	  这四个调用都是�选的，如果�想指定任何回调，则 ops �为 NULL。
	
	int v4l2_event_unsubscribe(struct v4l2_fh *fh,
				   struct v4l2_event_subscription *sub)
	
	  v4l2_ioctl_ops 结构体中的 vidioc_unsubscribe_event 回调函数。
	  驱动程��以直接使用 v4l2_event_unsubscribe() 实现退订事件过程。
	
	  特殊的 V4L2_EVENT_ALL 类型，�用于退订所有事件。驱动�能在特殊
	  情况下需��此�作。
	
	int v4l2_event_pending(struct v4l2_fh *fh)
	
	  返回未决事件的数�。有助于实现轮询（poll）�作。
	
	事件通过 poll 系统调用传递到用户空间。驱动�用
	v4l2_fh->wait (wait_queue_head_t 类型)作为�数调用 poll_wait()。
	
	事件分为标准事件和�有事件。新的标准事件必须使用�用的最�事件类型
	编�。驱动必须从他们本类型的编�起始处分�事件。类型的编�起始为
	V4L2_EVENT_PRIVATE_START + n * 1000 ，其中 n 为�用最�编�。�个
	类型中的第一个事件类型编�是为以�的使用�留的，所以第一个�用事件
	类型编�是‘class base + 1’。
	
	V4L2 事件机制的使用实例�以在 OMAP3 ISP 的驱动
	(drivers/media/video/omap3isp)中找到。

• [ video4linux ]
• omap3isp.txt
• v4l2-framework.txt
•