About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / zh_CN / video4linux / v4l2-framework.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:41 EST.

1	Chinese translated version of Documentation/video4linux/v4l2-framework.txt
2	
3	If you have any comment or update to the content, please contact the
4	original document maintainer directly.  However, if you have a problem
5	communicating in English you can also ask the Chinese maintainer for
6	help.  Contact the Chinese maintainer if this translation is outdated
7	or if there is a problem with the translation.
8	
9	Maintainer: Mauro Carvalho Chehab <mchehab@infradead.org>
10	Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
11	---------------------------------------------------------------------
12	Documentation/video4linux/v4l2-framework.txt 的中文翻译
13	
14	如果想评论或更新本文的内容,请直接联系原文档的维护者。如果你使用英文
15	交流有困难的话,也可以向中文版维护者求助。如果本翻译更新不及时或者翻
16	译存在问题,请联系中文版维护者。
17	英文版维护者: Mauro Carvalho Chehab <mchehab@infradead.org>
18	中文版维护者: 傅炜 Fu Wei <tekkamanninja@gmail.com>
19	中文版翻译者: 傅炜 Fu Wei <tekkamanninja@gmail.com>
20	中文版校译者: 傅炜 Fu Wei <tekkamanninja@gmail.com>
21	
22	
23	以下为正文
24	---------------------------------------------------------------------
25	V4L2 驱动框架概览
26	==============
27	
28	本文档描述 V4L2 框架所提供的各种结构和它们之间的关系。
29	
30	
31	介绍
32	----
33	
34	大部分现代 V4L2 设备由多个 IC 组成,在 /dev 下导出多个设备节点,
35	并同时创建非 V4L2 设备(如 DVB、ALSA、FB、I2C 和红外输入设备)。
36	由于这种硬件的复杂性,V4L2 驱动也变得非常复杂。
37	
38	尤其是 V4L2 必须支持 IC 实现音视频的多路复用和编解码,这就更增加了其
39	复杂性。通常这些 IC 通过一个或多个 I2C 总线连接到主桥驱动器,但也可
40	使用其他总线。这些设备称为“子设备”。
41	
42	长期以来,这个框架仅限于通过 video_device 结构体创建 V4L 设备节点,
43	并使用 video_buf 处理视频缓冲(注:本文不讨论 video_buf 框架)。
44	
45	这意味着所有驱动必须自己设置设备实例并连接到子设备。其中一部分要正确地
46	完成是比较复杂的,使得许多驱动都没有正确地实现。
47	
48	由于框架的缺失,有很多通用代码都不可重复利用。
49	
50	因此,这个框架构建所有驱动都需要的基本结构块,而统一的框架将使通用代码
51	创建成实用函数并在所有驱动中共享变得更加容易。
52	
53	
54	驱动结构
55	-------
56	
57	所有 V4L2 驱动都有如下结构:
58	
59	1) 每个设备实例的结构体--包含其设备状态。
60	
61	2) 初始化和控制子设备的方法(如果有)。
62	
63	3) 创建 V4L2 设备节点 (/dev/videoX、/dev/vbiX 和 /dev/radioX)
64	   并跟踪设备节点的特定数据。
65	
66	4) 特定文件句柄结构体--包含每个文件句柄的数据。
67	
68	5) 视频缓冲处理。
69	
70	以下是它们的初略关系图:
71	
72	    device instances(设备实例)
73	      |
74	      +-sub-device instances(子设备实例)
75	      |
76	      \-V4L2 device nodes(V4L2 设备节点)
77		  |
78		  \-filehandle instances(文件句柄实例)
79	
80	
81	框架结构
82	-------
83	
84	该框架非常类似驱动结构:它有一个 v4l2_device 结构用于保存设备
85	实例的数据;一个 v4l2_subdev 结构体代表子设备实例;video_device
86	结构体保存 V4L2 设备节点的数据;将来 v4l2_fh 结构体将跟踪文件句柄
87	实例(暂未尚未实现)。
88	
89	V4L2 框架也可与媒体框架整合(可选的)。如果驱动设置了 v4l2_device
90	结构体的 mdev 域,子设备和视频节点的入口将自动出现在媒体框架中。
91	
92	
93	v4l2_device 结构体
94	----------------
95	
96	每个设备实例都通过 v4l2_device (v4l2-device.h)结构体来表示。
97	简单设备可以仅分配这个结构体,但在大多数情况下,都会将这个结构体
98	嵌入到一个更大的结构体中。
99	
100	你必须注册这个设备实例:
101	
102		v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
103	
104	注册操作将会初始化 v4l2_device 结构体。如果 dev->driver_data 域
105	为 NULL,就将其指向 v4l2_dev。
106	
107	需要与媒体框架整合的驱动必须手动设置 dev->driver_data,指向包含
108	v4l2_device 结构体实例的驱动特定设备结构体。这可以在注册 V4L2 设备
109	实例前通过 dev_set_drvdata() 函数完成。同时必须设置 v4l2_device
110	结构体的 mdev 域,指向适当的初始化并注册过的 media_device 实例。
111	
112	如果 v4l2_dev->name 为空,则它将被设置为从 dev 中衍生出的值(为了
113	更加精确,形式为驱动名后跟 bus_id)。如果你在调用 v4l2_device_register
114	前已经设置好了,则不会被修改。如果 dev 为 NULL,则你*必须*在调用
115	v4l2_device_register 前设置 v4l2_dev->name。
116	
117	你可以基于驱动名和驱动的全局 atomic_t 类型的实例编号,通过
118	v4l2_device_set_name() 设置 name。这样会生成类似 ivtv0、ivtv1 等
119	名字。若驱动名以数字结尾,则会在编号和驱动名间插入一个破折号,如:
120	cx18-0、cx18-1 等。此函数返回实例编号。
121	
122	第一个 “dev” 参数通常是一个指向 pci_dev、usb_interface 或
123	platform_device 的指针。很少使其为 NULL,除非是一个ISA设备或者
124	当一个设备创建了多个 PCI 设备,使得 v4l2_dev 无法与一个特定的父设备
125	关联。
126	
127	你也可以提供一个 notify() 回调,使子设备可以调用它实现事件通知。
128	但这个设置与子设备相关。子设备支持的任何通知必须在
129	include/media/<subdevice>.h 中定义一个消息头。
130	
131	注销 v4l2_device 使用如下函数:
132	
133		v4l2_device_unregister(struct v4l2_device *v4l2_dev);
134	
135	如果 dev->driver_data 域指向 v4l2_dev,将会被重置为 NULL。注销同时
136	会自动从设备中注销所有子设备。
137	
138	如果你有一个热插拔设备(如USB设备),则当断开发生时,父设备将无效。
139	由于 v4l2_device 有一个指向父设备的指针必须被清除,同时标志父设备
140	已消失,所以必须调用以下函数:
141	
142		v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
143	
144	这个函数并*不*注销子设备,因此你依然要调用 v4l2_device_unregister()
145	函数。如果你的驱动器并非热插拔的,就没有必要调用 v4l2_device_disconnect()。
146	
147	有时你需要遍历所有被特定驱动注册的设备。这通常发生在多个设备驱动使用
148	同一个硬件的情况下。如:ivtvfb 驱动是一个使用 ivtv 硬件的帧缓冲驱动,
149	同时 alsa 驱动也使用此硬件。
150	
151	你可以使用如下例程遍历所有注册的设备:
152	
153	static int callback(struct device *dev, void *p)
154	{
155		struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
156	
157		/* 测试这个设备是否已经初始化 */
158		if (v4l2_dev == NULL)
159			return 0;
160		...
161		return 0;
162	}
163	
164	int iterate(void *p)
165	{
166		struct device_driver *drv;
167		int err;
168	
169		/* 在PCI 总线上查找ivtv驱动。
170		   pci_bus_type是全局的. 对于USB总线使用usb_bus_type。 */
171		drv = driver_find("ivtv", &pci_bus_type);
172		/* 遍历所有的ivtv设备实例 */
173		err = driver_for_each_device(drv, NULL, p, callback);
174		put_driver(drv);
175		return err;
176	}
177	
178	有时你需要一个设备实例的运行计数。这个通常用于映射一个设备实例到一个
179	模块选择数组的索引。
180	
181	推荐方法如下:
182	
183	static atomic_t drv_instance = ATOMIC_INIT(0);
184	
185	static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
186	{
187		...
188		state->instance = atomic_inc_return(&drv_instance) - 1;
189	}
190	
191	如果你有多个设备节点,对于热插拔设备,知道何时注销 v4l2_device 结构体
192	就比较困难。为此 v4l2_device 有引用计数支持。当调用 video_register_device
193	时增加引用计数,而设备节点释放时减小引用计数。当引用计数为零,则
194	v4l2_device 的release() 回调将被执行。你就可以在此时做最后的清理工作。
195	
196	如果创建了其他设备节点(比如 ALSA),则你可以通过以下函数手动增减
197	引用计数:
198	
199	void v4l2_device_get(struct v4l2_device *v4l2_dev);
200	
201	或:
202	
203	int v4l2_device_put(struct v4l2_device *v4l2_dev);
204	
205	由于引用技术初始化为 1 ,你也需要在 disconnect() 回调(对于 USB 设备)中
206	调用 v4l2_device_put,或者 remove() 回调(例如对于 PCI 设备),否则
207	引用计数将永远不会为 0 。
208	
209	v4l2_subdev结构体
210	------------------
211	
212	许多驱动需要与子设备通信。这些设备可以完成各种任务,但通常他们负责
213	音视频复用和编解码。如网络摄像头的子设备通常是传感器和摄像头控制器。
214	
215	这些一般为 I2C 接口设备,但并不一定都是。为了给驱动提供调用子设备的
216	统一接口,v4l2_subdev 结构体(v4l2-subdev.h)产生了。
217	
218	每个子设备驱动都必须有一个 v4l2_subdev 结构体。这个结构体可以单独
219	代表一个简单的子设备,也可以嵌入到一个更大的结构体中,与更多设备状态
220	信息保存在一起。通常有一个下级设备结构体(比如:i2c_client)包含了
221	内核创建的设备数据。建议使用 v4l2_set_subdevdata() 将这个结构体的
222	指针保存在 v4l2_subdev 的私有数据域(dev_priv)中。这使得通过 v4l2_subdev
223	找到实际的低层总线特定设备数据变得容易。
224	
225	你同时需要一个从低层结构体获取 v4l2_subdev 指针的方法。对于常用的
226	i2c_client 结构体,i2c_set_clientdata() 函数可用于保存一个 v4l2_subdev
227	指针;对于其他总线你可能需要使用其他相关函数。
228	
229	桥驱动中也应保存每个子设备的私有数据,比如一个指向特定桥的各设备私有
230	数据的指针。为此 v4l2_subdev 结构体提供主机私有数据域(host_priv),
231	并可通过 v4l2_get_subdev_hostdata() 和 v4l2_set_subdev_hostdata()
232	访问。
233	
234	从总线桥驱动的视角,驱动加载子设备模块并以某种方式获得 v4l2_subdev
235	结构体指针。对于 i2c 总线设备相对简单:调用 i2c_get_clientdata()。
236	对于其他总线也需要做类似的操作。针对 I2C 总线上的子设备辅助函数帮你
237	完成了大部分复杂的工作。
238	
239	每个 v4l2_subdev 都包含子设备驱动需要实现的函数指针(如果对此设备
240	不适用,可为NULL)。由于子设备可完成许多不同的工作,而在一个庞大的
241	函数指针结构体中通常仅有少数有用的函数实现其功能肯定不合适。所以,
242	函数指针根据其实现的功能被分类,每一类都有自己的函数指针结构体。
243	
244	顶层函数指针结构体包含了指向各类函数指针结构体的指针,如果子设备驱动
245	不支持该类函数中的任何一个功能,则指向该类结构体的指针为NULL。
246	
247	这些结构体定义如下:
248	
249	struct v4l2_subdev_core_ops {
250		int (*log_status)(struct v4l2_subdev *sd);
251		int (*init)(struct v4l2_subdev *sd, u32 val);
252		...
253	};
254	
255	struct v4l2_subdev_tuner_ops {
256		...
257	};
258	
259	struct v4l2_subdev_audio_ops {
260		...
261	};
262	
263	struct v4l2_subdev_video_ops {
264		...
265	};
266	
267	struct v4l2_subdev_pad_ops {
268		...
269	};
270	
271	struct v4l2_subdev_ops {
272		const struct v4l2_subdev_core_ops  *core;
273		const struct v4l2_subdev_tuner_ops *tuner;
274		const struct v4l2_subdev_audio_ops *audio;
275		const struct v4l2_subdev_video_ops *video;
276		const struct v4l2_subdev_pad_ops *video;
277	};
278	
279	其中 core(核心)函数集通常可用于所有子设备,其他类别的实现依赖于
280	子设备。如视频设备可能不支持音频操作函数,反之亦然。
281	
282	这样的设置在限制了函数指针数量的同时,还使增加新的操作函数和分类
283	变得较为容易。
284	
285	子设备驱动可使用如下函数初始化 v4l2_subdev 结构体:
286	
287		v4l2_subdev_init(sd, &ops);
288	
289	然后,你必须用一个唯一的名字初始化 subdev->name,并初始化模块的
290	owner 域。若使用 i2c 辅助函数,这些都会帮你处理好。
291	
292	若需同媒体框架整合,你必须调用 media_entity_init() 初始化 v4l2_subdev
293	结构体中的 media_entity 结构体(entity 域):
294	
295		struct media_pad *pads = &my_sd->pads;
296		int err;
297	
298		err = media_entity_init(&sd->entity, npads, pads, 0);
299	
300	pads 数组必须预先初始化。无须手动设置 media_entity 的 type 和
301	name 域,但如有必要,revision 域必须初始化。
302	
303	当(任何)子设备节点被打开/关闭,对 entity 的引用将被自动获取/释放。
304	
305	在子设备被注销之后,不要忘记清理 media_entity 结构体:
306	
307		media_entity_cleanup(&sd->entity);
308	
309	如果子设备驱动趋向于处理视频并整合进了媒体框架,必须使用 v4l2_subdev_pad_ops
310	替代 v4l2_subdev_video_ops 实现格式相关的功能。
311	
312	这种情况下,子设备驱动应该设置 link_validate 域,以提供它自身的链接
313	验证函数。链接验证函数应对管道(两端链接的都是 V4L2 子设备)中的每个
314	链接调用。驱动还要负责验证子设备和视频节点间格式配置的正确性。
315	
316	如果 link_validate 操作没有设置,默认的 v4l2_subdev_link_validate_default()
317	函数将会被调用。这个函数保证宽、高和媒体总线像素格式在链接的收发两端
318	都一致。子设备驱动除了它们自己的检测外,也可以自由使用这个函数以执行
319	上面提到的检查。
320	
321	设备(桥)驱动程序必须向 v4l2_device 注册 v4l2_subdev:
322	
323		int err = v4l2_device_register_subdev(v4l2_dev, sd);
324	
325	如果子设备模块在它注册前消失,这个操作可能失败。在这个函数成功返回后,
326	subdev->dev 域就指向了 v4l2_device。
327	
328	如果 v4l2_device 父设备的 mdev 域为非 NULL 值,则子设备实体将被自动
329	注册为媒体设备。
330	
331	注销子设备则可用如下函数:
332	
333		v4l2_device_unregister_subdev(sd);
334	
335	此后,子设备模块就可卸载,且 sd->dev == NULL。
336	
337	注册之设备后,可通过以下方式直接调用其操作函数:
338	
339		err = sd->ops->core->g_std(sd, &norm);
340	
341	但使用如下宏会比较容易且合适:
342	
343		err = v4l2_subdev_call(sd, core, g_std, &norm);
344	
345	这个宏将会做 NULL 指针检查,如果 subdev 为 NULL,则返回-ENODEV;如果
346	subdev->core 或 subdev->core->g_std 为 NULL,则返回 -ENOIOCTLCMD;
347	否则将返回 subdev->ops->core->g_std ops 调用的实际结果。
348	
349	有时也可能同时调用所有或一系列子设备的某个操作函数:
350	
351		v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm);
352	
353	任何不支持此操作的子设备都会被跳过,并忽略错误返回值。但如果你需要
354	检查出错码,则可使用如下函数:
355	
356		err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm);
357	
358	除 -ENOIOCTLCMD 外的任何错误都会跳出循环并返回错误值。如果(除 -ENOIOCTLCMD
359	外)没有错误发生,则返回 0。
360	
361	对于以上两个函数的第二个参数为组 ID。如果为 0,则所有子设备都会执行
362	这个操作。如果为非 0 值,则只有那些组 ID 匹配的子设备才会执行此操作。
363	在桥驱动注册一个子设备前,可以设置 sd->grp_id 为任何期望值(默认值为
364	0)。这个值属于桥驱动,且子设备驱动将不会修改和使用它。
365	
366	组 ID 赋予了桥驱动更多对于如何调用回调的控制。例如,电路板上有多个
367	音频芯片,每个都有改变音量的能力。但当用户想要改变音量的时候,通常
368	只有一个会被实际使用。你可以对这样的子设备设置组 ID 为(例如 AUDIO_CONTROLLER)
369	并在调用 v4l2_device_call_all() 时指定它为组 ID 值。这就保证了只有
370	需要的子设备才会执行这个回调。
371	
372	如果子设备需要通知它的 v4l2_device 父设备一个事件,可以调用
373	v4l2_subdev_notify(sd, notification, arg)。这个宏检查是否有一个
374	notify() 回调被注册,如果没有,返回 -ENODEV。否则返回 notify() 调用
375	结果。
376	
377	使用 v4l2_subdev 的好处在于它是一个通用结构体,且不包含任何底层硬件
378	信息。所有驱动可以包含多个 I2C 总线的子设备,但也有子设备是通过 GPIO
379	控制。这个区别仅在配置设备时有关系,一旦子设备注册完成,对于 v4l2
380	子系统来说就完全透明了。
381	
382	
383	V4L2 子设备用户空间API
384	--------------------
385	
386	除了通过 v4l2_subdev_ops 结构导出的内核 API,V4L2 子设备也可以直接
387	通过用户空间应用程序来控制。
388	
389	可以在 /dev 中创建名为 v4l-subdevX 设备节点,以通过其直接访问子设备。
390	如果子设备支持用户空间直接配置,必须在注册前设置 V4L2_SUBDEV_FL_HAS_DEVNODE
391	标志。
392	
393	注册子设备之后, v4l2_device 驱动会通过调用 v4l2_device_register_subdev_nodes()
394	函数为所有已注册并设置了 V4L2_SUBDEV_FL_HAS_DEVNODE 的子设备创建
395	设备节点。这些设备节点会在子设备注销时自动删除。
396	
397	这些设备节点处理 V4L2 API 的一个子集。
398	
399	VIDIOC_QUERYCTRL
400	VIDIOC_QUERYMENU
401	VIDIOC_G_CTRL
402	VIDIOC_S_CTRL
403	VIDIOC_G_EXT_CTRLS
404	VIDIOC_S_EXT_CTRLS
405	VIDIOC_TRY_EXT_CTRLS
406	
407		这些 ioctls 控制与 V4L2 中定义的一致。他们行为相同,唯一的
408		不同是他们只处理子设备的控制实现。根据驱动程序,这些控制也
409		可以通过一个(或多个) V4L2 设备节点访问。
410	
411	VIDIOC_DQEVENT
412	VIDIOC_SUBSCRIBE_EVENT
413	VIDIOC_UNSUBSCRIBE_EVENT
414	
415		这些  ioctls 事件与 V4L2 中定义的一致。他们行为相同,唯一的
416		不同是他们只处理子设备产生的事件。根据驱动程序,这些事件也
417		可以通过一个(或多个) V4L2 设备节点上报。
418	
419		要使用事件通知的子设备驱动,在注册子设备前必须在 v4l2_subdev::flags
420		中设置 V4L2_SUBDEV_USES_EVENTS 并在 v4l2_subdev::nevents
421		中初始化事件队列深度。注册完成后,事件会在 v4l2_subdev::devnode
422		设备节点中像通常一样被排队。
423	
424		为正确支持事件机制,poll() 文件操作也应被实现。
425	
426	私有 ioctls
427	
428		不在以上列表中的所有 ioctls 会通过 core::ioctl 操作直接传递
429		给子设备驱动。
430	
431	
432	I2C 子设备驱动
433	-------------
434	
435	由于这些驱动很常见,所以内特提供了特定的辅助函数(v4l2-common.h)让这些
436	设备的使用更加容易。
437	
438	添加 v4l2_subdev 支持的推荐方法是让 I2C 驱动将 v4l2_subdev 结构体
439	嵌入到为每个 I2C 设备实例创建的状态结构体中。而最简单的设备没有状态
440	结构体,此时可以直接创建一个 v4l2_subdev 结构体。
441	
442	一个典型的状态结构体如下所示(‘chipname’用芯片名代替):
443	
444	struct chipname_state {
445		struct v4l2_subdev sd;
446		...  /* 附加的状态域*/
447	};
448	
449	初始化 v4l2_subdev 结构体的方法如下:
450	
451		v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
452	
453	这个函数将填充 v4l2_subdev 结构体中的所有域,并保证 v4l2_subdev 和
454	i2c_client 都指向彼此。
455	
456	同时,你也应该为从 v4l2_subdev 指针找到 chipname_state 结构体指针
457	添加一个辅助内联函数。
458	
459	static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
460	{
461		return container_of(sd, struct chipname_state, sd);
462	}
463	
464	使用以下函数可以通过 v4l2_subdev 结构体指针获得 i2c_client 结构体
465	指针:
466	
467		struct i2c_client *client = v4l2_get_subdevdata(sd);
468	
469	而以下函数则相反,通过 i2c_client 结构体指针获得 v4l2_subdev 结构体
470	指针:
471	
472		struct v4l2_subdev *sd = i2c_get_clientdata(client);
473	
474	当 remove()函数被调用前,必须保证先调用 v4l2_device_unregister_subdev(sd)。
475	此操作将会从桥驱动中注销子设备。即使子设备没有注册,调用此函数也是
476	安全的。
477	
478	必须这样做的原因是:当桥驱动注销 i2c 适配器时,remove()回调函数
479	会被那个适配器上的 i2c 设备调用。此后,相应的 v4l2_subdev 结构体
480	就不存在了,所有它们必须先被注销。在 remove()回调函数中调用
481	v4l2_device_unregister_subdev(sd),可以保证执行总是正确的。
482	
483	
484	桥驱动也有一些辅组函数可用:
485	
486	struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
487		       "module_foo", "chipid", 0x36, NULL);
488	
489	这个函数会加载给定的模块(如果没有模块需要加载,可以为 NULL),
490	并用给定的 i2c 适配器结构体指针(i2c_adapter)和 器件地址(chip/address)
491	作为参数调用 i2c_new_device()。如果一切顺利,则就在 v4l2_device
492	中注册了子设备。
493	
494	你也可以利用 v4l2_i2c_new_subdev()的最后一个参数,传递一个可能的
495	I2C 地址数组,让函数自动探测。这些探测地址只有在前一个参数为 0 的
496	情况下使用。非零参数意味着你知道准确的 i2c 地址,所以此时无须进行
497	探测。
498	
499	如果出错,两个函数都返回 NULL。
500	
501	注意:传递给 v4l2_i2c_new_subdev()的 chipid 通常与模块名一致。
502	它允许你指定一个芯片的变体,比如“saa7114”或“saa7115”。一般通过
503	i2c 驱动自动探测。chipid 的使用是在今后需要深入了解的事情。这个与
504	i2c 驱动不同,较容易混淆。要知道支持哪些芯片变体,你可以查阅 i2c
505	驱动代码的 i2c_device_id 表,上面列出了所有可能支持的芯片。
506	
507	还有两个辅助函数:
508	
509	v4l2_i2c_new_subdev_cfg:这个函数添加新的 irq 和 platform_data
510	参数,并有‘addr’和‘probed_addrs’参数:如果 addr 非零,则被使用
511	(不探测变体),否则 probed_addrs 中的地址将用于自动探测。
512	
513	例如:以下代码将会探测地址(0x10):
514	
515	struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
516		       "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
517	
518	v4l2_i2c_new_subdev_board 使用一个 i2c_board_info 结构体,将其
519	替代 irq、platform_data 和 add r参数传递给 i2c 驱动。
520	
521	如果子设备支持 s_config 核心操作,这个操作会在子设备配置好之后以 irq 和
522	platform_data 为参数调用。早期的 v4l2_i2c_new_(probed_)subdev 函数
523	同样也会调用 s_config,但仅在 irq 为 0 且 platform_data 为 NULL 时。
524	
525	video_device结构体
526	-----------------
527	
528	在 /dev 目录下的实际设备节点根据 video_device 结构体(v4l2-dev.h)
529	创建。此结构体既可以动态分配也可以嵌入到一个更大的结构体中。
530	
531	动态分配方法如下:
532	
533		struct video_device *vdev = video_device_alloc();
534	
535		if (vdev == NULL)
536			return -ENOMEM;
537	
538		vdev->release = video_device_release;
539	
540	如果将其嵌入到一个大结构体中,则必须自己实现 release()回调。
541	
542		struct video_device *vdev = &my_vdev->vdev;
543	
544		vdev->release = my_vdev_release;
545	
546	release()回调必须被设置,且在最后一个 video_device 用户退出之后
547	被调用。
548	
549	默认的 video_device_release()回调只是调用 kfree 来释放之前分配的
550	内存。
551	
552	你应该设置这些域:
553	
554	- v4l2_dev: 设置为 v4l2_device 父设备。
555	
556	- name: 设置为唯一的描述性设备名。
557	
558	- fops: 设置为已有的 v4l2_file_operations 结构体。
559	
560	- ioctl_ops: 如果你使用v4l2_ioctl_ops 来简化 ioctl 的维护
561	  (强烈建议使用,且将来可能变为强制性的!),然后设置你自己的
562	  v4l2_ioctl_ops 结构体.
563	
564	- lock: 如果你要在驱动中实现所有的锁操作,则设为 NULL 。否则
565	  就要设置一个指向 struct mutex_lock 结构体的指针,这个锁将
566	  在 unlocked_ioctl 文件操作被调用前由内核获得,并在调用返回后
567	  释放。详见下一节。
568	
569	- prio: 保持对优先级的跟踪。用于实现 VIDIOC_G/S_PRIORITY。如果
570	  设置为 NULL,则会使用 v4l2_device 中的 v4l2_prio_state 结构体。
571	  如果要对每个设备节点(组)实现独立的优先级,可以将其指向自己
572	  实现的 v4l2_prio_state 结构体。
573	
574	- parent: 仅在使用 NULL 作为父设备结构体参数注册 v4l2_device 时
575	  设置此参数。只有在一个硬件设备包含多一个 PCI 设备,共享同一个
576	  v4l2_device 核心时才会发生。
577	
578	  cx88 驱动就是一个例子:一个 v4l2_device 结构体核心,被一个裸的
579	  视频 PCI 设备(cx8800)和一个 MPEG PCI 设备(cx8802)共用。由于
580	  v4l2_device 无法与特定的 PCI 设备关联,所有没有设置父设备。但当
581	  video_device 配置后,就知道使用哪个父 PCI 设备了。
582	
583	- flags:可选。如果你要让框架处理设置 VIDIOC_G/S_PRIORITY ioctls,
584	  请设置 V4L2_FL_USE_FH_PRIO。这要求你使用 v4l2_fh 结构体。
585	  一旦所有驱动使用了核心的优先级处理,最终这个标志将消失。但现在它
586	  必须被显式设置。
587	
588	如果你使用 v4l2_ioctl_ops,则应该在 v4l2_file_operations 结构体中
589	设置 .unlocked_ioctl 指向 video_ioctl2。
590	
591	请勿使用 .ioctl!它已被废弃,今后将消失。
592	
593	某些情况下你要告诉核心:你在 v4l2_ioctl_ops 指定的某个函数应被忽略。
594	你可以在 video_device_register 被调用前通过以下函数标记这个 ioctls。
595	
596	void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd);
597	
598	基于外部因素(例如某个板卡已被使用),在不创建新结构体的情况下,你想
599	要关闭 v4l2_ioctl_ops 中某个特性往往需要这个机制。
600	
601	v4l2_file_operations 结构体是 file_operations 的一个子集。其主要
602	区别在于:因 inode 参数从未被使用,它将被忽略。
603	
604	如果需要与媒体框架整合,你必须通过调用 media_entity_init() 初始化
605	嵌入在 video_device 结构体中的 media_entity(entity 域)结构体:
606	
607		struct media_pad *pad = &my_vdev->pad;
608		int err;
609	
610		err = media_entity_init(&vdev->entity, 1, pad, 0);
611	
612	pads 数组必须预先初始化。没有必要手动设置 media_entity 的 type 和
613	name 域。
614	
615	当(任何)子设备节点被打开/关闭,对 entity 的引用将被自动获取/释放。
616	
617	v4l2_file_operations 与锁
618	--------------------------
619	
620	你可以在 video_device 结构体中设置一个指向 mutex_lock 的指针。通常
621	这既可是一个顶层互斥锁也可为设备节点自身的互斥锁。默认情况下,此锁
622	用于 unlocked_ioctl,但为了使用 ioctls 你通过以下函数可禁用锁定:
623	
624		void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd);
625	
626	例如: v4l2_disable_ioctl_locking(vdev, VIDIOC_DQBUF);
627	
628	你必须在注册 video_device 前调用这个函数。
629	
630	特别是对于 USB 驱动程序,某些命令(如设置控制)需要很长的时间,可能
631	需要自行为缓冲区队列的 ioctls 实现锁定。
632	
633	如果你需要更细粒度的锁,你必须设置 mutex_lock 为 NULL,并完全自己实现
634	锁机制。
635	
636	这完全由驱动开发者决定使用何种方法。然而,如果你的驱动存在长延时操作
637	(例如,改变 USB 摄像头的曝光时间可能需要较长时间),而你又想让用户
638	在等待长延时操作完成期间做其他的事,则你最好自己实现锁机制。
639	
640	如果指定一个锁,则所有 ioctl 操作将在这个锁的作用下串行执行。如果你
641	使用 videobuf,则必须将同一个锁传递给 videobuf 队列初始化函数;如
642	videobuf 必须等待一帧的到达,则可临时解锁并在这之后重新上锁。如果驱动
643	也在代码执行期间等待,则可做同样的工作(临时解锁,再上锁)让其他进程
644	可以在第一个进程阻塞时访问设备节点。
645	
646	在使用 videobuf2 的情况下,必须实现 wait_prepare 和 wait_finish 回调
647	在适当的时候解锁/加锁。进一步来说,如果你在 video_device 结构体中使用
648	锁,则必须在 wait_prepare 和 wait_finish 中对这个互斥锁进行解锁/加锁。
649	
650	热插拔的断开实现也必须在调用 v4l2_device_disconnect 前获得锁。
651	
652	video_device注册
653	---------------
654	
655	接下来你需要注册视频设备:这会为你创建一个字符设备。
656	
657		err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
658		if (err) {
659			video_device_release(vdev); /* or kfree(my_vdev); */
660			return err;
661		}
662	
663	如果 v4l2_device 父设备的 mdev 域为非 NULL 值,视频设备实体将自动
664	注册为媒体设备。
665	
666	注册哪种设备是根据类型(type)参数。存在以下类型:
667	
668	VFL_TYPE_GRABBER: 用于视频输入/输出设备的 videoX
669	VFL_TYPE_VBI: 用于垂直消隐数据的 vbiX (例如,隐藏式字幕,图文电视)
670	VFL_TYPE_RADIO: 用于广播调谐器的 radioX
671	
672	最后一个参数让你确定一个所控制设备的设备节点号数量(例如 videoX 中的 X)。
673	通常你可以传入-1,让 v4l2 框架自己选择第一个空闲的编号。但是有时用户
674	需要选择一个特定的节点号。驱动允许用户通过驱动模块参数选择一个特定的
675	设备节点号是很普遍的。这个编号将会传递给这个函数,且 video_register_device
676	将会试图选择这个设备节点号。如果这个编号被占用,下一个空闲的设备节点
677	编号将被选中,并向内核日志中发送一个警告信息。
678	
679	另一个使用场景是当驱动创建多个设备时。这种情况下,对不同的视频设备在
680	编号上使用不同的范围是很有用的。例如,视频捕获设备从 0 开始,视频
681	输出设备从 16 开始。所以你可以使用最后一个参数来指定设备节点号最小值,
682	而 v4l2 框架会试图选择第一个的空闲编号(等于或大于你提供的编号)。
683	如果失败,则它会就选择第一个空闲的编号。
684	
685	由于这种情况下,你会忽略无法选择特定设备节点号的警告,则可调用
686	video_register_device_no_warn() 函数避免警告信息的产生。
687	
688	只要设备节点被创建,一些属性也会同时创建。在 /sys/class/video4linux
689	目录中你会找到这些设备。例如进入其中的 video0 目录,你会看到‘name’和
690	‘index’属性。‘name’属性值就是 video_device 结构体中的‘name’域。
691	
692	‘index’属性值就是设备节点的索引值:每次调用 video_register_device(),
693	索引值都递增 1 。第一个视频设备节点总是从索引值 0 开始。
694	
695	用户可以设置 udev 规则,利用索引属性生成花哨的设备名(例如:用‘mpegX’
696	代表 MPEG 视频捕获设备节点)。
697	
698	在设备成功注册后,就可以使用这些域:
699	
700	- vfl_type: 传递给 video_register_device 的设备类型。
701	- minor: 已指派的次设备号。
702	- num: 设备节点编号 (例如 videoX 中的 X)。
703	- index: 设备索引号。
704	
705	如果注册失败,你必须调用 video_device_release() 来释放已分配的
706	video_device 结构体;如果 video_device 是嵌入在自己创建的结构体中,
707	你也必须释放它。vdev->release() 回调不会在注册失败之后被调用,
708	你也不应试图在注册失败后注销设备。
709	
710	
711	video_device 注销
712	----------------
713	
714	当视频设备节点已被移除,不论是卸载驱动还是USB设备断开,你都应注销
715	它们:
716	
717		video_unregister_device(vdev);
718	
719	这个操作将从 sysfs 中移除设备节点(导致 udev 将其从 /dev 中移除)。
720	
721	video_unregister_device() 返回之后,就无法完成打开操作。尽管如此,
722	USB 设备的情况则不同,某些应用程序可能依然打开着其中一个已注销设备
723	节点。所以在注销之后,所有文件操作(当然除了 release )也应返回错误值。
724	
725	当最后一个视频设备节点的用户退出,则 vdev->release() 回调会被调用,
726	并且你可以做最后的清理操作。
727	
728	不要忘记清理与视频设备相关的媒体入口(如果被初始化过):
729	
730		media_entity_cleanup(&vdev->entity);
731	
732	这可以在 release 回调中完成。
733	
734	
735	video_device 辅助函数
736	---------------------
737	
738	一些有用的辅助函数如下:
739	
740	- file/video_device 私有数据
741	
742	你可以用以下函数在 video_device 结构体中设置/获取驱动私有数据:
743	
744	void *video_get_drvdata(struct video_device *vdev);
745	void video_set_drvdata(struct video_device *vdev, void *data);
746	
747	注意:在调用 video_register_device() 前执行 video_set_drvdata()
748	是安全的。
749	
750	而以下函数:
751	
752	struct video_device *video_devdata(struct file *file);
753	
754	返回 file 结构体中拥有的的 video_device 指针。
755	
756	video_drvdata 辅助函数结合了 video_get_drvdata 和 video_devdata
757	的功能:
758	
759	void *video_drvdata(struct file *file);
760	
761	你可以使用如下代码从 video_device 结构体中获取 v4l2_device 结构体
762	指针:
763	
764	struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
765	
766	- 设备节点名
767	
768	video_device 设备节点在内核中的名称可以通过以下函数获得
769	
770	const char *video_device_node_name(struct video_device *vdev);
771	
772	这个名字被用户空间工具(例如 udev)作为提示信息使用。应尽可能使用
773	此功能,而非访问 video_device::num 和 video_device::minor 域。
774	
775	
776	视频缓冲辅助函数
777	---------------
778	
779	v4l2 核心 API 提供了一个处理视频缓冲的标准方法(称为“videobuf”)。
780	这些方法使驱动可以通过统一的方式实现 read()、mmap() 和 overlay()。
781	目前在设备上支持视频缓冲的方法有分散/聚集 DMA(videobuf-dma-sg)、
782	线性 DMA(videobuf-dma-contig)以及大多用于 USB 设备的用 vmalloc
783	分配的缓冲(videobuf-vmalloc)。
784	
785	请参阅 Documentation/video4linux/videobuf,以获得更多关于 videobuf
786	层的使用信息。
787	
788	v4l2_fh 结构体
789	-------------
790	
791	v4l2_fh 结构体提供一个保存用于 V4L2 框架的文件句柄特定数据的简单方法。
792	如果 video_device 的 flag 设置了 V4L2_FL_USE_FH_PRIO 标志,新驱动
793	必须使用 v4l2_fh 结构体,因为它也用于实现优先级处理(VIDIOC_G/S_PRIORITY)。
794	
795	v4l2_fh 的用户(位于 V4l2 框架中,并非驱动)可通过测试
796	video_device->flags 中的 V4L2_FL_USES_V4L2_FH 位得知驱动是否使用
797	v4l2_fh 作为他的 file->private_data 指针。这个位会在调用 v4l2_fh_init()
798	时被设置。
799	
800	v4l2_fh 结构体作为驱动自身文件句柄结构体的一部分被分配,且驱动在
801	其打开函数中将 file->private_data 指向它。
802	
803	在许多情况下,v4l2_fh 结构体会嵌入到一个更大的结构体中。这钟情况下,
804	应该在 open() 中调用 v4l2_fh_init+v4l2_fh_add,并在 release() 中
805	调用 v4l2_fh_del+v4l2_fh_exit。
806	
807	驱动可以通过使用 container_of 宏提取他们自己的文件句柄结构体。例如:
808	
809	struct my_fh {
810		int blah;
811		struct v4l2_fh fh;
812	};
813	
814	...
815	
816	int my_open(struct file *file)
817	{
818		struct my_fh *my_fh;
819		struct video_device *vfd;
820		int ret;
821	
822		...
823	
824		my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
825	
826		...
827	
828		v4l2_fh_init(&my_fh->fh, vfd);
829	
830		...
831	
832		file->private_data = &my_fh->fh;
833		v4l2_fh_add(&my_fh->fh);
834		return 0;
835	}
836	
837	int my_release(struct file *file)
838	{
839		struct v4l2_fh *fh = file->private_data;
840		struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
841	
842		...
843		v4l2_fh_del(&my_fh->fh);
844		v4l2_fh_exit(&my_fh->fh);
845		kfree(my_fh);
846		return 0;
847	}
848	
849	以下是 v4l2_fh 函数使用的简介:
850	
851	void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
852	
853	  初始化文件句柄。这*必须*在驱动的 v4l2_file_operations->open()
854	  函数中执行。
855	
856	void v4l2_fh_add(struct v4l2_fh *fh)
857	
858	  添加一个 v4l2_fh 到 video_device 文件句柄列表。一旦文件句柄
859	  初始化完成就必须调用。
860	
861	void v4l2_fh_del(struct v4l2_fh *fh)
862	
863	  从 video_device() 中解除文件句柄的关联。文件句柄的退出函数也
864	  将被调用。
865	
866	void v4l2_fh_exit(struct v4l2_fh *fh)
867	
868	  清理文件句柄。在清理完 v4l2_fh 后,相关内存会被释放。
869	
870	
871	如果 v4l2_fh 不是嵌入在其他结构体中的,则可以用这些辅助函数:
872	
873	int v4l2_fh_open(struct file *filp)
874	
875	  分配一个 v4l2_fh 结构体空间,初始化并将其添加到 file 结构体相关的
876	  video_device 结构体中。
877	
878	int v4l2_fh_release(struct file *filp)
879	
880	  从 file 结构体相关的 video_device 结构体中删除 v4l2_fh ,清理
881	  v4l2_fh 并释放空间。
882	
883	这两个函数可以插入到 v4l2_file_operation 的 open() 和 release()
884	操作中。
885	
886	
887	某些驱动需要在第一个文件句柄打开和最后一个文件句柄关闭的时候做些
888	工作。所以加入了两个辅助函数以检查 v4l2_fh 结构体是否是相关设备
889	节点打开的唯一文件句柄。
890	
891	int v4l2_fh_is_singular(struct v4l2_fh *fh)
892	
893	  如果此文件句柄是唯一打开的文件句柄,则返回 1 ,否则返回 0 。
894	
895	int v4l2_fh_is_singular_file(struct file *filp)
896	
897	  功能相同,但通过 filp->private_data 调用 v4l2_fh_is_singular。
898	
899	
900	V4L2 事件机制
901	-----------
902	
903	V4L2 事件机制提供了一个通用的方法将事件传递到用户空间。驱动必须使用
904	v4l2_fh 才能支持 V4L2 事件机制。
905	
906	
907	事件通过一个类型和选择 ID 来定义。ID 对应一个 V4L2 对象,例如
908	一个控制 ID。如果未使用,则 ID 为 0。
909	
910	当用户订阅一个事件,驱动会为此分配一些 kevent 结构体。所以每个
911	事件组(类型、ID)都会有自己的一套 kevent 结构体。这保证了如果
912	一个驱动短时间内产生了许多同类事件,不会覆盖其他类型的事件。
913	
914	但如果你收到的事件数量大于同类事件 kevent 的保存数量,则最早的
915	事件将被丢弃,并加入新事件。
916	
917	此外,v4l2_subscribed_event 结构体内部有可供驱动设置的 merge() 和
918	replace() 回调,这些回调会在新事件产生且没有多余空间的时候被调用。
919	replace() 回调让你可以将早期事件的净荷替换为新事件的净荷,将早期
920	净荷的相关数据合并到替换进来的新净荷中。当该类型的事件仅分配了一个
921	kevent 结构体时,它将被调用。merge() 回调让你可以合并最早的事件净荷
922	到在它之后的那个事件净荷中。当该类型的事件分配了两个或更多 kevent
923	结构体时,它将被调用。
924	
925	这种方法不会有状态信息丢失,只会导致中间步骤信息丢失。
926	
927	
928	关于 replace/merge 回调的一个不错的例子在 v4l2-event.c 中:用于
929	控制事件的 ctrls_replace() 和 ctrls_merge() 回调。
930	
931	注意:这些回调可以在中断上下文中调用,所以它们必须尽快完成并退出。
932	
933	有用的函数:
934	
935	void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev)
936	
937	  将事件加入视频设备的队列。驱动仅负责填充 type 和 data 域。
938	  其他域由 V4L2 填充。
939	
940	int v4l2_event_subscribe(struct v4l2_fh *fh,
941				 struct v4l2_event_subscription *sub, unsigned elems,
942				 const struct v4l2_subscribed_event_ops *ops)
943	
944	  video_device->ioctl_ops->vidioc_subscribe_event 必须检测驱动能
945	  产生特定 id 的事件。然后调用 v4l2_event_subscribe() 来订阅该事件。
946	
947	  elems 参数是该事件的队列大小。若为 0,V4L2 框架将会(根据事件类型)
948	  填充默认值。
949	
950	  ops 参数允许驱动指定一系列回调:
951	  * add:     当添加一个新监听者时调用(重复订阅同一个事件,此回调
952	             仅被执行一次)。
953	  * del:     当一个监听者停止监听时调用。
954	  * replace: 用‘新’事件替换‘早期‘事件。
955	  * merge:   将‘早期‘事件合并到‘新’事件中。
956	  这四个调用都是可选的,如果不想指定任何回调,则 ops 可为 NULL。
957	
958	int v4l2_event_unsubscribe(struct v4l2_fh *fh,
959				   struct v4l2_event_subscription *sub)
960	
961	  v4l2_ioctl_ops 结构体中的 vidioc_unsubscribe_event 回调函数。
962	  驱动程序可以直接使用 v4l2_event_unsubscribe() 实现退订事件过程。
963	
964	  特殊的 V4L2_EVENT_ALL 类型,可用于退订所有事件。驱动可能在特殊
965	  情况下需要做此操作。
966	
967	int v4l2_event_pending(struct v4l2_fh *fh)
968	
969	  返回未决事件的数量。有助于实现轮询(poll)操作。
970	
971	事件通过 poll 系统调用传递到用户空间。驱动可用
972	v4l2_fh->wait (wait_queue_head_t 类型)作为参数调用 poll_wait()。
973	
974	事件分为标准事件和私有事件。新的标准事件必须使用可用的最小事件类型
975	编号。驱动必须从他们本类型的编号起始处分配事件。类型的编号起始为
976	V4L2_EVENT_PRIVATE_START + n * 1000 ,其中 n 为可用最小编号。每个
977	类型中的第一个事件类型编号是为以后的使用保留的,所以第一个可用事件
978	类型编号是‘class base + 1’。
979	
980	V4L2 事件机制的使用实例可以在 OMAP3 ISP 的驱动
981	(drivers/media/video/omap3isp)中找到。
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.