Based on kernel version 4.9. Page generated on 2016-12-21 14:37 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_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 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 如果你使用 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 591 void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd); 592 593 基于外部因素（例如某个板卡已被使用），在不创建新结构体的情况下，你想 594 要关闭 v4l2_ioctl_ops 中某个特性往往需要这个机制。 595 596 v4l2_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 607 pads 数组必须预先初始化。没有必要手动设置 media_entity 的 type 和 608 name 域。 609 610 当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。 611 612 v4l2_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 队列初始化函数；如 637 videobuf 必须等待一帧的到达，则可临时解锁并在这之后重新上锁。如果驱动 638 也在代码执行期间等待，则可做同样的工作（临时解锁，再上锁）让其他进程 639 可以在第一个进程阻塞时访问设备节点。 640 641 在使用 videobuf2 的情况下，必须实现 wait_prepare 和 wait_finish 回调 642 在适当的时候解锁/加锁。进一步来说，如果你在 video_device 结构体中使用 643 锁，则必须在 wait_prepare 和 wait_finish 中对这个互斥锁进行解锁/加锁。 644 645 热插拔的断开实现也必须在调用 v4l2_device_disconnect 前获得锁。 646 647 video_device注册 648 --------------- 649 650 接下来你需要注册视频设备：这会为你创建一个字符设备。 651 652 err = video_register_device(vdev, VFL_TYPE_GRABBER, -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 663 VFL_TYPE_GRABBER: 用于视频输入/输出设备的 videoX 664 VFL_TYPE_VBI: 用于垂直消隐数据的 vbiX (例如，隐藏式字幕，图文电视) 665 VFL_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 由于这种情况下，你会忽略无法选择特定设备节点号的警告，则可调用 681 video_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() 来释放已分配的 701 video_device 结构体；如果 video_device 是嵌入在自己创建的结构体中， 702 你也必须释放它。vdev->release() 回调不会在注册失败之后被调用， 703 你也不应试图在注册失败后注销设备。 704 705 706 video_device 注销 707 ---------------- 708 709 当视频设备节点已被移除，不论是卸载驱动还是USB设备断开，你都应注销 710 它们： 711 712 video_unregister_device(vdev); 713 714 这个操作将从 sysfs 中移除设备节点（导致 udev 将其从 /dev 中移除）。 715 716 video_unregister_device() 返回之后，就无法完成打开操作。尽管如此， 717 USB 设备的情况则不同，某些应用程序可能依然打开着其中一个已注销设备 718 节点。所以在注销之后，所有文件操作（当然除了 release ）也应返回错误值。 719 720 当最后一个视频设备节点的用户退出，则 vdev->release() 回调会被调用， 721 并且你可以做最后的清理操作。 722 723 不要忘记清理与视频设备相关的媒体入口（如果被初始化过）： 724 725 media_entity_cleanup(&vdev->entity); 726 727 这可以在 release 回调中完成。 728 729 730 video_device 辅助函数 731 --------------------- 732 733 一些有用的辅助函数如下： 734 735 - file/video_device 私有数据 736 737 你可以用以下函数在 video_device 结构体中设置/获取驱动私有数据： 738 739 void *video_get_drvdata(struct video_device *vdev); 740 void video_set_drvdata(struct video_device *vdev, void *data); 741 742 注意：在调用 video_register_device() 前执行 video_set_drvdata() 743 是安全的。 744 745 而以下函数： 746 747 struct video_device *video_devdata(struct file *file); 748 749 返回 file 结构体中拥有的的 video_device 指针。 750 751 video_drvdata 辅助函数结合了 video_get_drvdata 和 video_devdata 752 的功能： 753 754 void *video_drvdata(struct file *file); 755 756 你可以使用如下代码从 video_device 结构体中获取 v4l2_device 结构体 757 指针： 758 759 struct v4l2_device *v4l2_dev = vdev->v4l2_dev; 760 761 - 设备节点名 762 763 video_device 设备节点在内核中的名称可以通过以下函数获得 764 765 const char *video_device_node_name(struct video_device *vdev); 766 767 这个名字被用户空间工具（例如 udev）作为提示信息使用。应尽可能使用 768 此功能，而非访问 video_device::num 和 video_device::minor 域。 769 770 771 视频缓冲辅助函数 772 --------------- 773 774 v4l2 核心 API 提供了一个处理视频缓冲的标准方法(称为“videobuf”)。 775 这些方法使驱动可以通过统一的方式实现 read()、mmap() 和 overlay()。 776 目前在设备上支持视频缓冲的方法有分散/聚集 DMA(videobuf-dma-sg)、 777 线性 DMA(videobuf-dma-contig)以及大多用于 USB 设备的用 vmalloc 778 分配的缓冲(videobuf-vmalloc)。 779 780 请参阅 Documentation/video4linux/videobuf，以获得更多关于 videobuf 781 层的使用信息。 782 783 v4l2_fh 结构体 784 ------------- 785 786 v4l2_fh 结构体提供一个保存用于 V4L2 框架的文件句柄特定数据的简单方法。 787 如果 video_device 标志，新驱动 788 必须使用 v4l2_fh 结构体，因为它也用于实现优先级处理（VIDIOC_G/S_PRIORITY）。 789 790 v4l2_fh 的用户（位于 V4l2 框架中，并非驱动）可通过测试 791 video_device->flags 中的 V4L2_FL_USES_V4L2_FH 位得知驱动是否使用 792 v4l2_fh 作为他的 file->private_data 指针。这个位会在调用 v4l2_fh_init() 793 时被设置。 794 795 v4l2_fh 结构体作为驱动自身文件句柄结构体的一部分被分配，且驱动在 796 其打开函数中将 file->private_data 指向它。 797 798 在许多情况下，v4l2_fh 结构体会嵌入到一个更大的结构体中。这钟情况下， 799 应该在 open() 中调用 v4l2_fh_init+v4l2_fh_add，并在 release() 中 800 调用 v4l2_fh_del+v4l2_fh_exit。 801 802 驱动可以通过使用 container_of 宏提取他们自己的文件句柄结构体。例如： 803 804 struct my_fh { 805 int blah; 806 struct v4l2_fh fh; 807 }; 808 809 ... 810 811 int my_open(struct file *file) 812 { 813 struct my_fh *my_fh; 814 struct video_device *vfd; 815 int ret; 816 817 ... 818 819 my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); 820 821 ... 822 823 v4l2_fh_init(&my_fh->fh, vfd); 824 825 ... 826 827 file->private_data = &my_fh->fh; 828 v4l2_fh_add(&my_fh->fh); 829 return 0; 830 } 831 832 int my_release(struct file *file) 833 { 834 struct v4l2_fh *fh = file->private_data; 835 struct my_fh *my_fh = container_of(fh, struct my_fh, fh); 836 837 ... 838 v4l2_fh_del(&my_fh->fh); 839 v4l2_fh_exit(&my_fh->fh); 840 kfree(my_fh); 841 return 0; 842 } 843 844 以下是 v4l2_fh 函数使用的简介： 845 846 void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev) 847 848 初始化文件句柄。这*必须*在驱动的 v4l2_file_operations->open() 849 函数中执行。 850 851 void v4l2_fh_add(struct v4l2_fh *fh) 852 853 添加一个 v4l2_fh 到 video_device 文件句柄列表。一旦文件句柄 854 初始化完成就必须调用。 855 856 void v4l2_fh_del(struct v4l2_fh *fh) 857 858 从 video_device() 中解除文件句柄的关联。文件句柄的退出函数也 859 将被调用。 860 861 void v4l2_fh_exit(struct v4l2_fh *fh) 862 863 清理文件句柄。在清理完 v4l2_fh 后，相关内存会被释放。 864 865 866 如果 v4l2_fh 不是嵌入在其他结构体中的，则可以用这些辅助函数： 867 868 int v4l2_fh_open(struct file *filp) 869 870 分配一个 v4l2_fh 结构体空间，初始化并将其添加到 file 结构体相关的 871 video_device 结构体中。 872 873 int v4l2_fh_release(struct file *filp) 874 875 从 file 结构体相关的 video_device 结构体中删除 v4l2_fh ，清理 876 v4l2_fh 并释放空间。 877 878 这两个函数可以插入到 v4l2_file_operation 的 open() 和 release() 879 操作中。 880 881 882 某些驱动需要在第一个文件句柄打开和最后一个文件句柄关闭的时候做些 883 工作。所以加入了两个辅助函数以检查 v4l2_fh 结构体是否是相关设备 884 节点打开的唯一文件句柄。 885 886 int v4l2_fh_is_singular(struct v4l2_fh *fh) 887 888 如果此文件句柄是唯一打开的文件句柄，则返回 1 ，否则返回 0 。 889 890 int v4l2_fh_is_singular_file(struct file *filp) 891 892 功能相同，但通过 filp->private_data 调用 v4l2_fh_is_singular。 893 894 895 V4L2 事件机制 896 ----------- 897 898 V4L2 事件机制提供了一个通用的方法将事件传递到用户空间。驱动必须使用 899 v4l2_fh 才能支持 V4L2 事件机制。 900 901 902 事件通过一个类型和选择 ID 来定义。ID 对应一个 V4L2 对象，例如 903 一个控制 ID。如果未使用，则 ID 为 0。 904 905 当用户订阅一个事件，驱动会为此分配一些 kevent 结构体。所以每个 906 事件组（类型、ID）都会有自己的一套 kevent 结构体。这保证了如果 907 一个驱动短时间内产生了许多同类事件，不会覆盖其他类型的事件。 908 909 但如果你收到的事件数量大于同类事件 kevent 的保存数量，则最早的 910 事件将被丢弃，并加入新事件。 911 912 此外，v4l2_subscribed_event 结构体内部有可供驱动设置的 merge() 和 913 replace() 回调，这些回调会在新事件产生且没有多余空间的时候被调用。 914 replace() 回调让你可以将早期事件的净荷替换为新事件的净荷，将早期 915 净荷的相关数据合并到替换进来的新净荷中。当该类型的事件仅分配了一个 916 kevent 结构体时，它将被调用。merge() 回调让你可以合并最早的事件净荷 917 到在它之后的那个事件净荷中。当该类型的事件分配了两个或更多 kevent 918 结构体时，它将被调用。 919 920 这种方法不会有状态信息丢失，只会导致中间步骤信息丢失。 921 922 923 关于 replace/merge 回调的一个不错的例子在 v4l2-event.c 中：用于 924 控制事件的 ctrls_replace() 和 ctrls_merge() 回调。 925 926 注意：这些回调可以在中断上下文中调用，所以它们必须尽快完成并退出。 927 928 有用的函数： 929 930 void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev) 931 932 将事件加入视频设备的队列。驱动仅负责填充 type 和 data 域。 933 其他域由 V4L2 填充。 934 935 int v4l2_event_subscribe(struct v4l2_fh *fh, 936 struct v4l2_event_subscription *sub, unsigned elems, 937 const struct v4l2_subscribed_event_ops *ops) 938 939 video_device->ioctl_ops->vidioc_subscribe_event 必须检测驱动能 940 产生特定 id 的事件。然后调用 v4l2_event_subscribe() 来订阅该事件。 941 942 elems 参数是该事件的队列大小。若为 0，V4L2 框架将会（根据事件类型） 943 填充默认值。 944 945 ops 参数允许驱动指定一系列回调： 946 * add: 当添加一个新监听者时调用（重复订阅同一个事件，此回调 947 仅被执行一次）。 948 * del: 当一个监听者停止监听时调用。 949 * replace: 用‘新’事件替换‘早期‘事件。 950 * merge: 将‘早期‘事件合并到‘新’事件中。 951 这四个调用都是可选的，如果不想指定任何回调，则 ops 可为 NULL。 952 953 int v4l2_event_unsubscribe(struct v4l2_fh *fh, 954 struct v4l2_event_subscription *sub) 955 956 v4l2_ioctl_ops 结构体中的 vidioc_unsubscribe_event 回调函数。 957 驱动程序可以直接使用 v4l2_event_unsubscribe() 实现退订事件过程。 958 959 特殊的 V4L2_EVENT_ALL 类型，可用于退订所有事件。驱动可能在特殊 960 情况下需要做此操作。 961 962 int v4l2_event_pending(struct v4l2_fh *fh) 963 964 返回未决事件的数量。有助于实现轮询（poll）操作。 965 966 事件通过 poll 系统调用传递到用户空间。驱动可用 967 v4l2_fh->wait (wait_queue_head_t 类型)作为参数调用 poll_wait()。 968 969 事件分为标准事件和私有事件。新的标准事件必须使用可用的最小事件类型 970 编号。驱动必须从他们本类型的编号起始处分配事件。类型的编号起始为 971 V4L2_EVENT_PRIVATE_START + n * 1000 ，其中 n 为可用最小编号。每个 972 类型中的第一个事件类型编号是为以后的使用保留的，所以第一个可用事件 973 类型编号是‘class base + 1’。 974 975 V4L2 事件机制的使用实例可以在 OMAP3 ISP 的驱动 976 (drivers/media/video/omap3isp)中找到。