1Chinese translated version of Documentation/driver-api/media/index.rst 2 3If you have any comment or update to the content, please contact the 4original document maintainer directly. However, if you have a problem 5communicating in English you can also ask the Chinese maintainer for 6help. Contact the Chinese maintainer if this translation is outdated 7or if there is a problem with the translation. 8 9Maintainer: Mauro Carvalho Chehab <mchehab@kernel.org> 10Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> 11--------------------------------------------------------------------- 12Documentation/driver-api/media/index.rst 的中文翻译 13 14如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 15交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 16译存在问题，请联系中文版维护者。 17英文版维护者： Mauro Carvalho Chehab <mchehab@kernel.org> 18中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> 19中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> 20中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> 21 22 23以下为正文 24--------------------------------------------------------------------- 25V4L2 驱动框架概览 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 591) 每个设备实例的结构体--包含其设备状态。 60 612) 初始化和控制子设备的方法（如果有）。 62 633) 创建 V4L2 设备节点 (/dev/videoX、/dev/vbiX 和 /dev/radioX) 64 并跟踪设备节点的特定数据。 65 664) 特定文件句柄结构体--包含每个文件句柄的数据。 67 685) 视频缓冲处理。 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 89V4L2 框架也可与媒体框架整合（可选的）。如果驱动设置了 v4l2_device 90结构体的 mdev 域，子设备和视频节点的入口将自动出现在媒体框架中。 91 92 93v4l2_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，指向包含 108v4l2_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，则你*必须*在调用 115v4l2_device_register 前设置 v4l2_dev->name。 116 117你可以基于驱动名和驱动的全局 atomic_t 类型的实例编号，通过 118v4l2_device_set_name() 设置 name。这样会生成类似 ivtv0、ivtv1 等 119名字。若驱动名以数字结尾，则会在编号和驱动名间插入一个破折号，如： 120cx18-0、cx18-1 等。此函数返回实例编号。 121 122第一个 “dev” 参数通常是一个指向 pci_dev、usb_interface 或 123platform_device 的指针。很少使其为 NULL，除非是一个ISA设备或者 124当一个设备创建了多个 PCI 设备，使得 v4l2_dev 无法与一个特定的父设备 125关联。 126 127你也可以提供一个 notify() 回调，使子设备可以调用它实现事件通知。 128但这个设置与子设备相关。子设备支持的任何通知必须在 129include/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 153static 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 164int 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 183static atomic_t drv_instance = ATOMIC_INIT(0); 184 185static 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时增加引用计数，而设备节点释放时减小引用计数。当引用计数为零，则 194v4l2_device 的release() 回调将被执行。你就可以在此时做最后的清理工作。 195 196如果创建了其他设备节点（比如 ALSA），则你可以通过以下函数手动增减 197引用计数： 198 199void v4l2_device_get(struct v4l2_device *v4l2_dev); 200 201或: 202 203int v4l2_device_put(struct v4l2_device *v4l2_dev); 204 205由于引用技术初始化为 1 ，你也需要在 disconnect() 回调（对于 USB 设备）中 206调用 v4l2_device_put，或者 remove() 回调（例如对于 PCI 设备），否则 207引用计数将永远不会为 0 。 208 209v4l2_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 指针的方法。对于常用的 226i2c_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 249struct v4l2_subdev_core_ops { 250 int (*log_status)(struct v4l2_subdev *sd); 251 int (*init)(struct v4l2_subdev *sd, u32 val); 252 ... 253}; 254 255struct v4l2_subdev_tuner_ops { 256 ... 257}; 258 259struct v4l2_subdev_audio_ops { 260 ... 261}; 262 263struct v4l2_subdev_video_ops { 264 ... 265}; 266 267struct v4l2_subdev_pad_ops { 268 ... 269}; 270 271struct 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，并初始化模块的 290owner 域。若使用 i2c 辅助函数，这些都会帮你处理好。 291 292若需同媒体框架整合，你必须调用 media_entity_pads_init() 初始化 v4l2_subdev 293结构体中的 media_entity 结构体（entity 域）： 294 295 struct media_pad *pads = &my_sd->pads; 296 int err; 297 298 err = media_entity_pads_init(&sd->entity, npads, pads); 299 300pads 数组必须预先初始化。无须手动设置 media_entity 的 type 和 301name 域，但如有必要，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如果子设备模块在它注册前消失，这个操作可能失败。在这个函数成功返回后， 326subdev->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；如果 346subdev->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 为任何期望值（默认值为 3640）。这个值属于桥驱动，且子设备驱动将不会修改和使用它。 365 366组 ID 赋予了桥驱动更多对于如何调用回调的控制。例如，电路板上有多个 367音频芯片，每个都有改变音量的能力。但当用户想要改变音量的时候，通常 368只有一个会被实际使用。你可以对这样的子设备设置组 ID 为（例如 AUDIO_CONTROLLER） 369并在调用 v4l2_device_call_all() 时指定它为组 ID 值。这就保证了只有 370需要的子设备才会执行这个回调。 371 372如果子设备需要通知它的 v4l2_device 父设备一个事件，可以调用 373v4l2_subdev_notify(sd, notification, arg)。这个宏检查是否有一个 374notify() 回调被注册，如果没有，返回 -ENODEV。否则返回 notify() 调用 375结果。 376 377使用 v4l2_subdev 的好处在于它是一个通用结构体，且不包含任何底层硬件 378信息。所有驱动可以包含多个 I2C 总线的子设备，但也有子设备是通过 GPIO 379控制。这个区别仅在配置设备时有关系，一旦子设备注册完成，对于 v4l2 380子系统来说就完全透明了。 381 382 383V4L2 子设备用户空间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 399VIDIOC_QUERYCTRL 400VIDIOC_QUERYMENU 401VIDIOC_G_CTRL 402VIDIOC_S_CTRL 403VIDIOC_G_EXT_CTRLS 404VIDIOC_S_EXT_CTRLS 405VIDIOC_TRY_EXT_CTRLS 406 407 这些 ioctls 控制与 V4L2 中定义的一致。他们行为相同，唯一的 408 不同是他们只处理子设备的控制实现。根据驱动程序，这些控制也 409 可以通过一个（或多个） V4L2 设备节点访问。 410 411VIDIOC_DQEVENT 412VIDIOC_SUBSCRIBE_EVENT 413VIDIOC_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 432I2C 子设备驱动 433------------- 434 435由于这些驱动很常见，所以内特提供了特定的辅助函数(v4l2-common.h)让这些 436设备的使用更加容易。 437 438添加 v4l2_subdev 支持的推荐方法是让 I2C 驱动将 v4l2_subdev 结构体 439嵌入到为每个 I2C 设备实例创建的状态结构体中。而最简单的设备没有状态 440结构体，此时可以直接创建一个 v4l2_subdev 结构体。 441 442一个典型的状态结构体如下所示（‘chipname’用芯片名代替）： 443 444struct 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 和 454i2c_client 都指向彼此。 455 456同时，你也应该为从 v4l2_subdev 指针找到 chipname_state 结构体指针 457添加一个辅助内联函数。 458 459static 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()回调函数中调用 481v4l2_device_unregister_subdev(sd)，可以保证执行总是正确的。 482 483 484桥驱动也有一些辅组函数可用： 485 486struct 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_client_device()。如果一切顺利，则就在 v4l2_device 492中注册了子设备。 493 494你也可以利用 v4l2_i2c_new_subdev()的最后一个参数，传递一个可能的 495I2C 地址数组，让函数自动探测。这些探测地址只有在前一个参数为 0 的 496情况下使用。非零参数意味着你知道准确的 i2c 地址，所以此时无须进行 497探测。 498 499如果出错，两个函数都返回 NULL。 500 501注意：传递给 v4l2_i2c_new_subdev()的 chipid 通常与模块名一致。 502它允许你指定一个芯片的变体，比如“saa7114”或“saa7115”。一般通过 503i2c 驱动自动探测。chipid 的使用是在今后需要深入了解的事情。这个与 504i2c 驱动不同，较容易混淆。要知道支持哪些芯片变体，你可以查阅 i2c 505驱动代码的 i2c_device_id 表，上面列出了所有可能支持的芯片。 506 507还有两个辅助函数： 508 509v4l2_i2c_new_subdev_cfg：这个函数添加新的 irq 和 platform_data 510参数，并有‘addr’和‘probed_addrs’参数：如果 addr 非零，则被使用 511（不探测变体），否则 probed_addrs 中的地址将用于自动探测。 512 513例如：以下代码将会探测地址（0x10）： 514 515struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter, 516 "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10)); 517 518v4l2_i2c_new_subdev_board 使用一个 i2c_board_info 结构体，将其 519替代 irq、platform_data 和 add r参数传递给 i2c 驱动。 520 521如果子设备支持 s_config 核心操作，这个操作会在子设备配置好之后以 irq 和 522platform_data 为参数调用。早期的 v4l2_i2c_new_(probed_)subdev 函数 523同样也会调用 s_config，但仅在 irq 为 0 且 platform_data 为 NULL 时。 524 525video_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 546release()回调必须被设置，且在最后一个 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如果你使用 v4l2_ioctl_ops，则应该在 v4l2_file_operations 结构体中 584设置 .unlocked_ioctl 指向 video_ioctl2。 585 586请勿使用 .ioctl！它已被废弃，今后将消失。 587 588某些情况下你要告诉核心：你在 v4l2_ioctl_ops 指定的某个函数应被忽略。 589你可以在 video_device_register 被调用前通过以下函数标记这个 ioctls。 590 591void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd); 592 593基于外部因素（例如某个板卡已被使用），在不创建新结构体的情况下，你想 594要关闭 v4l2_ioctl_ops 中某个特性往往需要这个机制。 595 596v4l2_file_operations 结构体是 file_operations 的一个子集。其主要 597区别在于：因 inode 参数从未被使用，它将被忽略。 598 599如果需要与媒体框架整合，你必须通过调用 media_entity_pads_init() 初始化 600嵌入在 video_device 结构体中的 media_entity（entity 域）结构体： 601 602 struct media_pad *pad = &my_vdev->pad; 603 int err; 604 605 err = media_entity_pads_init(&vdev->entity, 1, pad); 606 607pads 数组必须预先初始化。没有必要手动设置 media_entity 的 type 和 608name 域。 609 610当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。 611 612v4l2_file_operations 与锁 613-------------------------- 614 615你可以在 video_device 结构体中设置一个指向 mutex_lock 的指针。通常 616这既可是一个顶层互斥锁也可为设备节点自身的互斥锁。默认情况下，此锁 617用于 unlocked_ioctl，但为了使用 ioctls 你通过以下函数可禁用锁定： 618 619 void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd); 620 621例如: v4l2_disable_ioctl_locking(vdev, VIDIOC_DQBUF); 622 623你必须在注册 video_device 前调用这个函数。 624 625特别是对于 USB 驱动程序，某些命令（如设置控制）需要很长的时间，可能 626需要自行为缓冲区队列的 ioctls 实现锁定。 627 628如果你需要更细粒度的锁，你必须设置 mutex_lock 为 NULL，并完全自己实现 629锁机制。 630 631这完全由驱动开发者决定使用何种方法。然而，如果你的驱动存在长延时操作 632（例如，改变 USB 摄像头的曝光时间可能需要较长时间），而你又想让用户 633在等待长延时操作完成期间做其他的事，则你最好自己实现锁机制。 634 635如果指定一个锁，则所有 ioctl 操作将在这个锁的作用下串行执行。如果你 636使用 videobuf，则必须将同一个锁传递给 videobuf 队列初始化函数；如 637videobuf 必须等待一帧的到达，则可临时解锁并在这之后重新上锁。如果驱动 638也在代码执行期间等待，则可做同样的工作（临时解锁，再上锁）让其他进程 639可以在第一个进程阻塞时访问设备节点。 640 641在使用 videobuf2 的情况下，必须实现 wait_prepare 和 wait_finish 回调 642在适当的时候解锁/加锁。进一步来说，如果你在 video_device 结构体中使用 643锁，则必须在 wait_prepare 和 wait_finish 中对这个互斥锁进行解锁/加锁。 644 645热插拔的断开实现也必须在调用 v4l2_device_disconnect 前获得锁。 646 647video_device注册 648--------------- 649 650接下来你需要注册视频设备：这会为你创建一个字符设备。 651 652 err = video_register_device(vdev, VFL_TYPE_VIDEO, -1); 653 if (err) { 654 video_device_release(vdev); /* or kfree(my_vdev); */ 655 return err; 656 } 657 658如果 v4l2_device 父设备的 mdev 域为非 NULL 值，视频设备实体将自动 659注册为媒体设备。 660 661注册哪种设备是根据类型（type）参数。存在以下类型： 662 663VFL_TYPE_VIDEO: 用于视频输入/输出设备的 videoX 664VFL_TYPE_VBI: 用于垂直消隐数据的 vbiX (例如，隐藏式字幕，图文电视) 665VFL_TYPE_RADIO: 用于广播调谐器的 radioX 666 667最后一个参数让你确定一个所控制设备的设备节点号数量(例如 videoX 中的 X)。 668通常你可以传入-1，让 v4l2 框架自己选择第一个空闲的编号。但是有时用户 669需要选择一个特定的节点号。驱动允许用户通过驱动模块参数选择一个特定的 670设备节点号是很普遍的。这个编号将会传递给这个函数，且 video_register_device 671将会试图选择这个设备节点号。如果这个编号被占用，下一个空闲的设备节点 672编号将被选中，并向内核日志中发送一个警告信息。 673 674另一个使用场景是当驱动创建多个设备时。这种情况下，对不同的视频设备在 675编号上使用不同的范围是很有用的。例如，视频捕获设备从 0 开始，视频 676输出设备从 16 开始。所以你可以使用最后一个参数来指定设备节点号最小值， 677而 v4l2 框架会试图选择第一个的空闲编号（等于或大于你提供的编号）。 678如果失败，则它会就选择第一个空闲的编号。 679 680由于这种情况下，你会忽略无法选择特定设备节点号的警告，则可调用 681video_register_device_no_warn() 函数避免警告信息的产生。 682 683只要设备节点被创建，一些属性也会同时创建。在 /sys/class/video4linux 684目录中你会找到这些设备。例如进入其中的 video0 目录，你会看到‘name’和 685‘index’属性。‘name’属性值就是 video_device 结构体中的‘name’域。 686 687‘index’属性值就是设备节点的索引值：每次调用 video_register_device()， 688索引值都递增 1 。第一个视频设备节点总是从索引值 0 开始。 689 690用户可以设置 udev 规则，利用索引属性生成花哨的设备名（例如：用‘mpegX’ 691代表 MPEG 视频捕获设备节点）。 692 693在设备成功注册后，就可以使用这些域： 694 695- vfl_type: 传递给 video_register_device 的设备类型。 696- minor: 已指派的次设备号。 697- num: 设备节点编号 (例如 videoX 中的 X)。 698- index: 设备索引号。 699 700如果注册失败，你必须调用 video_device_release() 来释放已分配的 701video_device 结构体；如果 video_device 是嵌入在自己创建的结构体中， 702你也必须释放它。vdev->release() 回调不会在注册失败之后被调用， 703你也不应试图在注册失败后注销设备。 704 705 706video_device 注销 707---------------- 708 709当视频设备节点已被移除，不论是卸载驱动还是USB设备断开，你都应注销 710它们： 711 712 video_unregister_device(vdev); 713 714这个操作将从 sysfs 中移除设备节点（导致 udev 将其从 /dev 中移除）。 715 716video_unregister_device() 返回之后，就无法完成打开操作。尽管如此， 717USB 设备的情况则不同，某些应用程序可能依然打开着其中一个已注销设备 718节点。所以在注销之后，所有文件操作（当然除了 release ）也应返回错误值。 719 720当最后一个视频设备节点的用户退出，则 vdev->release() 回调会被调用， 721并且你可以做最后的清理操作。 722 723不要忘记清理与视频设备相关的媒体入口（如果被初始化过）： 724 725 media_entity_cleanup(&vdev->entity); 726 727这可以在 release 回调中完成。 728 729 730video_device 辅助函数 731--------------------- 732 733一些有用的辅助函数如下： 734 735- file/video_device 私有数据 736 737你可以用以下函数在 video_device 结构体中设置/获取驱动私有数据： 738 739void *video_get_drvdata(struct video_device *vdev); 740void video_set_drvdata(struct video_device *vdev, void *data); 741 742注意：在调用 video_register_device() 前执行 video_set_drvdata() 743是安全的。 744 745而以下函数： 746 747struct video_device *video_devdata(struct file *file); 748 749返回 file 结构体中拥有的的 video_device 指针。 750 751video_drvdata 辅助函数结合了 video_get_drvdata 和 video_devdata 752的功能： 753 754void *video_drvdata(struct file *file); 755 756你可以使用如下代码从 video_device 结构体中获取 v4l2_device 结构体 757指针： 758 759struct v4l2_device *v4l2_dev = vdev->v4l2_dev; 760 761- 设备节点名 762 763video_device 设备节点在内核中的名称可以通过以下函数获得 764 765const char *video_device_node_name(struct video_device *vdev); 766 767这个名字被用户空间工具（例如 udev）作为提示信息使用。应尽可能使用 768此功能，而非访问 video_device::num 和 video_device::minor 域。 769 770 771v4l2_fh 结构体 772------------- 773 774v4l2_fh 结构体提供一个保存用于 V4L2 框架的文件句柄特定数据的简单方法。 775如果 video_device 标志，新驱动 776必须使用 v4l2_fh 结构体，因为它也用于实现优先级处理（VIDIOC_G/S_PRIORITY）。 777 778v4l2_fh 的用户（位于 V4l2 框架中，并非驱动）可通过测试 779video_device->flags 中的 V4L2_FL_USES_V4L2_FH 位得知驱动是否使用 780v4l2_fh 作为他的 file->private_data 指针。这个位会在调用 v4l2_fh_init() 781时被设置。 782 783v4l2_fh 结构体作为驱动自身文件句柄结构体的一部分被分配，且驱动在 784其打开函数中将 file->private_data 指向它。 785 786在许多情况下，v4l2_fh 结构体会嵌入到一个更大的结构体中。这钟情况下， 787应该在 open() 中调用 v4l2_fh_init+v4l2_fh_add，并在 release() 中 788调用 v4l2_fh_del+v4l2_fh_exit。 789 790驱动可以通过使用 container_of 宏提取他们自己的文件句柄结构体。例如： 791 792struct my_fh { 793 int blah; 794 struct v4l2_fh fh; 795}; 796 797... 798 799int my_open(struct file *file) 800{ 801 struct my_fh *my_fh; 802 struct video_device *vfd; 803 int ret; 804 805 ... 806 807 my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); 808 809 ... 810 811 v4l2_fh_init(&my_fh->fh, vfd); 812 813 ... 814 815 file->private_data = &my_fh->fh; 816 v4l2_fh_add(&my_fh->fh); 817 return 0; 818} 819 820int my_release(struct file *file) 821{ 822 struct v4l2_fh *fh = file->private_data; 823 struct my_fh *my_fh = container_of(fh, struct my_fh, fh); 824 825 ... 826 v4l2_fh_del(&my_fh->fh); 827 v4l2_fh_exit(&my_fh->fh); 828 kfree(my_fh); 829 return 0; 830} 831 832以下是 v4l2_fh 函数使用的简介： 833 834void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev) 835 836 初始化文件句柄。这*必须*在驱动的 v4l2_file_operations->open() 837 函数中执行。 838 839void v4l2_fh_add(struct v4l2_fh *fh) 840 841 添加一个 v4l2_fh 到 video_device 文件句柄列表。一旦文件句柄 842 初始化完成就必须调用。 843 844void v4l2_fh_del(struct v4l2_fh *fh) 845 846 从 video_device() 中解除文件句柄的关联。文件句柄的退出函数也 847 将被调用。 848 849void v4l2_fh_exit(struct v4l2_fh *fh) 850 851 清理文件句柄。在清理完 v4l2_fh 后，相关内存会被释放。 852 853 854如果 v4l2_fh 不是嵌入在其他结构体中的，则可以用这些辅助函数： 855 856int v4l2_fh_open(struct file *filp) 857 858 分配一个 v4l2_fh 结构体空间，初始化并将其添加到 file 结构体相关的 859 video_device 结构体中。 860 861int v4l2_fh_release(struct file *filp) 862 863 从 file 结构体相关的 video_device 结构体中删除 v4l2_fh ，清理 864 v4l2_fh 并释放空间。 865 866这两个函数可以插入到 v4l2_file_operation 的 open() 和 release() 867操作中。 868 869 870某些驱动需要在第一个文件句柄打开和最后一个文件句柄关闭的时候做些 871工作。所以加入了两个辅助函数以检查 v4l2_fh 结构体是否是相关设备 872节点打开的唯一文件句柄。 873 874int v4l2_fh_is_singular(struct v4l2_fh *fh) 875 876 如果此文件句柄是唯一打开的文件句柄，则返回 1 ，否则返回 0 。 877 878int v4l2_fh_is_singular_file(struct file *filp) 879 880 功能相同，但通过 filp->private_data 调用 v4l2_fh_is_singular。 881 882 883V4L2 事件机制 884----------- 885 886V4L2 事件机制提供了一个通用的方法将事件传递到用户空间。驱动必须使用 887v4l2_fh 才能支持 V4L2 事件机制。 888 889 890事件通过一个类型和选择 ID 来定义。ID 对应一个 V4L2 对象，例如 891一个控制 ID。如果未使用，则 ID 为 0。 892 893当用户订阅一个事件，驱动会为此分配一些 kevent 结构体。所以每个 894事件组（类型、ID）都会有自己的一套 kevent 结构体。这保证了如果 895一个驱动短时间内产生了许多同类事件，不会覆盖其他类型的事件。 896 897但如果你收到的事件数量大于同类事件 kevent 的保存数量，则最早的 898事件将被丢弃，并加入新事件。 899 900此外，v4l2_subscribed_event 结构体内部有可供驱动设置的 merge() 和 901replace() 回调，这些回调会在新事件产生且没有多余空间的时候被调用。 902replace() 回调让你可以将早期事件的净荷替换为新事件的净荷，将早期 903净荷的相关数据合并到替换进来的新净荷中。当该类型的事件仅分配了一个 904kevent 结构体时，它将被调用。merge() 回调让你可以合并最早的事件净荷 905到在它之后的那个事件净荷中。当该类型的事件分配了两个或更多 kevent 906结构体时，它将被调用。 907 908这种方法不会有状态信息丢失，只会导致中间步骤信息丢失。 909 910 911关于 replace/merge 回调的一个不错的例子在 v4l2-event.c 中：用于 912控制事件的 ctrls_replace() 和 ctrls_merge() 回调。 913 914注意：这些回调可以在中断上下文中调用，所以它们必须尽快完成并退出。 915 916有用的函数： 917 918void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev) 919 920 将事件加入视频设备的队列。驱动仅负责填充 type 和 data 域。 921 其他域由 V4L2 填充。 922 923int v4l2_event_subscribe(struct v4l2_fh *fh, 924 struct v4l2_event_subscription *sub, unsigned elems, 925 const struct v4l2_subscribed_event_ops *ops) 926 927 video_device->ioctl_ops->vidioc_subscribe_event 必须检测驱动能 928 产生特定 id 的事件。然后调用 v4l2_event_subscribe() 来订阅该事件。 929 930 elems 参数是该事件的队列大小。若为 0，V4L2 框架将会（根据事件类型） 931 填充默认值。 932 933 ops 参数允许驱动指定一系列回调： 934 * add: 当添加一个新监听者时调用（重复订阅同一个事件，此回调 935 仅被执行一次）。 936 * del: 当一个监听者停止监听时调用。 937 * replace: 用‘新’事件替换‘早期‘事件。 938 * merge: 将‘早期‘事件合并到‘新’事件中。 939 这四个调用都是可选的，如果不想指定任何回调，则 ops 可为 NULL。 940 941int v4l2_event_unsubscribe(struct v4l2_fh *fh, 942 struct v4l2_event_subscription *sub) 943 944 v4l2_ioctl_ops 结构体中的 vidioc_unsubscribe_event 回调函数。 945 驱动程序可以直接使用 v4l2_event_unsubscribe() 实现退订事件过程。 946 947 特殊的 V4L2_EVENT_ALL 类型，可用于退订所有事件。驱动可能在特殊 948 情况下需要做此操作。 949 950int v4l2_event_pending(struct v4l2_fh *fh) 951 952 返回未决事件的数量。有助于实现轮询（poll）操作。 953 954事件通过 poll 系统调用传递到用户空间。驱动可用 955v4l2_fh->wait (wait_queue_head_t 类型)作为参数调用 poll_wait()。 956 957事件分为标准事件和私有事件。新的标准事件必须使用可用的最小事件类型 958编号。驱动必须从他们本类型的编号起始处分配事件。类型的编号起始为 959V4L2_EVENT_PRIVATE_START + n * 1000 ，其中 n 为可用最小编号。每个 960类型中的第一个事件类型编号是为以后的使用保留的，所以第一个可用事件 961类型编号是‘class base + 1’。 962 963V4L2 事件机制的使用实例可以在 OMAP3 ISP 的驱动 964(drivers/media/video/omap3isp)中找到。 965