本文对 V4L2 的运行时数据流设备管理做一个详细的介绍,包括什么叫「运行时设备管理」,它是干什么用的,怎么使用等等。本文的目标是掌握 media device 的编码使用方法以及功能运用。
01 - V4L2框架-v4l2 device
00 - V4L2框架概述
media framework
-
简介
相关的控制 API 在Documentation/DocBook/media/v4l/media-controller.xml
,本文档聚焦于内核测的media框架实现。注意:直接查看是看不出啥的,在内核的根目录下make htmldocs
或者其它格式的都行,易于查看。 -
运行时设备控制
也就是设备启动之后的数据流线路控制,就像一个工厂流水线一样,流水线上面的一个个节点(贴商标、喷丝印、打包)就形同于输入设备中的一个个子设备,运行时设备控制就是要达到能够控制节点的效果,比如贴商标的机器有好几台,应该选择哪一台进行此次流水线处理,要不要把喷丝印加上去,加哪一个机子等等。 -
作用
提供实时的 pipeline 管理,pipeline 就理解为管道,想象一下水管,里面的水就是数据流,输入设备中的 csi->isp->video 就组成了一个 pipeline 线路。media framework 提供 pipeline 的开启、关停、效果控制、节点控制等功能。 -
如何使用
内核当中主要利用四个结构体把众多的节点组织起来:media_device
,media_entity
,media_link
,media_pad
。整个 media framework 都是围绕这四个结构体来进行使用的,下文会对这些进行详细介绍。 -
抽象设备模型
media framework 其中一个目的是:在运行时状态下发现设备拓扑并对其进行配置。为了达到这个目的,media framework将硬件设备抽象为一个个的entity,它们之间通过links连接。
- entity:硬件设备模块抽象(类比电路板上面的各个元器件、芯片)
- pad:硬件设备端口抽象(类比元器件、芯片上面的管脚)
- link:硬件设备的连线抽象,link的两端是pad(类比元器件管脚之间的连线)
#------------# #------------#
| __|__ __|__ |
| | | | link | | | |
| | pad |<-------->| pad | |
| |__|__| |__|__| |
| | | |
| entity | | entity |
#------------# #------------#
可以想象一下,如果各个 entity 之间需要建立连接的话,就需要在 pad 中存储 link 以及 entity 信息,link 中需要存储 pad 与 entity 信息,entity 里面需要存储 link 与 pad 信息,属于你中有我,我中有你的情况。
media 设备
一个 media 设备用一个 media_device
结构体来表示,通常情况下该结构体要嵌入到一个更大的设备自定义的结构体里面,并且大多数时候 media_device
与 v4l2_device
是处于并列的级别,还是以 omap3isp 的代码为例:
struct isp_device {
struct v4l2_device v4l2_dev;
struct v4l2_async_notifier notifier;
struct media_device media_dev;
struct device *dev;
u32 revision;
... ...
}
使用以下函数进行 meida 设备的注册:media_device_register(struct media_device *mdev);
函数的调用者需要在注册之前设置以下结构体成员(提前初始化该结构体是调用者的责任):
- dev:必须指向一个父设备,通常是平台设备的device成员。
- model:模型名字。
以下的成员是可选的: - serial:序列号,必须是唯一的
- bus_info:总线信息,如果是PCI设备的话就可以设置成"PCI:"
- hw_revision:硬件版本。可以的话,应该用KERNEL_VERSION宏定义进行格式化
- driver_version:驱动版本。最终生成的设备节点的名称是media[0-9],节点号由内核自动生成。
使用以下函数进行设备卸载:media_device_unregister(struct media_device *mdev);
需要注意的是,卸载一个并没有注册过的设备是***不安全的***。个人查看代码猜想不安全的原因主要有几个:1. 如果没有被注册,那么 media_device
内部的 entity 成员就有可能没有被初始化,如果其值为一个不确定的值,那么就会引起非法访问;2. 如果没有注册,内部的 devnode
成员就没有初始化,卸载时就会出现问题。
「entities、pads、links」
entities
entities 用一个 media_entity
结构体来表示,该结构体通常被嵌入到一个更大的结构体里面,比如 v4l2_subdev
或者 video_device
结构体(不必自行分配空间,结构体内部已经包含),当然也可以直接分配一个 entities。使用以下函数对 entity 进行初始化:
media_entity_init(struct media_entity *entity, u16 num_pads, struct
media_pad *pads, u16 extra_links);
在执行初始化函数之前需要注意的参数有:
- num_pads:pad的数量,与驱动子设备结构相关。
- pads:media_pad结构体数组,通常pad被嵌入到驱动自定义的结构体里面,数组地址被传递给该参数,pad需提前初始化。
- extra_links:该函数会根据num_pads分配link数目,该参数则指明除了预分配的数量之外还需要多少额外的links。
- entity:
media_entity
的name、type、flags、revision和group_id
需要在初始化之前或者之后进行设置,如果结构体被嵌入到更高级的结构体里面,这些成员也可能被更高级的框架代码所设置,entity的id在注册的时候被填充(如果提前设置了id成员,则注册的时候就保持预设的值)。entity有相关的标志位「flags」来标识它的状态与功能,MEDIA_ENT_FL_DEFAULT
就表示这是一个默认的 entity。可以设置多个 entity 的组 ID 为同一个整数来标识它们是属于同一类别的,对于内核来说,组ID是没有用处的,但是组 ID 会在枚举 entity 的时候被传递到用户空间,可能在用户空间的某种情况下用得上。
pads
pad 使用一个 media_pad
结构体来表示,pads 数据被驱动程序管理(数组形式)。pads 使用 entity 与数组下标来进行唯一标识,entity 内部的 id 不会重复,但是不同 entity 之间的 pad id 可能会重复,所以 pad 的索引要 entity 与 id 联合确认。
由于 pads 的数量是提前获知的(你做的芯片,你肯定知道它有几个管脚),所以 media_pad
结构体不再动态分配,并且驱动应负责对该结构体数组进行管理(避免动态分配)。驱动必须在 media_entity_init
函数被调用之前对 pads 的方向属性进行设置,pads 有 flags
位来标识它的属性,在初始化的时候仅需要设置该成员即可,其余的交由 media_entity_init
函数来完成:
MEDIA_PAD_FL_SINK:目的pad
MEDIA_PAD_FL_SOURCE:源pad
links
links 用一个 media_link
结构体来表示,每一个 entity 的所有 pads 里面都存储了与之相关的所有 links,一个 link 会分别被源 pad 以及目的 pad 存储,以便实现正反两个方向的遍历。使用以下函数创建 links:
media_entity_create_link(struct media_entity *source, u16 source_pad,
struct media_entity *sink, u16 sink_pad, u32 flags);
links 有一些 flags
位来标识其属性:
MEDIA_LNK_FL_ENABLED:link被使能,可以用来传输数据,多个link连接到同一个sink pad时,只有一个link可以被使能。
MEDIA_LNK_FL_IMMUTABLE:link的使能状态不能在运行时被改变,一般情况下这两个标志位同时被设置。
MEDIA_LNK_FL_DYNAMIC:link的状态是动态可变的。
和 pads 不一样,links 的数量并不总是提前确定的(电路板上面有时候你也无法完全确认需要管脚连到多少个设备上面,极有可能出现临时变更的情况),所以 media_entity_init
函数根据传入的参数预分配一定数量的 media_link
结构体,如果不够用的话会在 media_entity_create_link
中动态分配(如果 link 数量大于等于 max_link 的话就会扩充 link 数量)。
注册与卸载
驱动需要使用以下函数对 entity 进行注册与卸载(不需要手动执行,在 v4l2_device_un/register_subdev
函数里面完成):
media_device_register_entity(struct media_device *mdev, struct
media_entity *entity);
media_device_unregister_entity(struct media_entity *entity);
内核里面使用一个唯一的正整数来表示每一个 entity(同一个 media_device
下唯一),驱动也可以通过填充 media_entity->id
成员来指定 entity 的 ID 值,但是必须保证唯一。如果 ID 由内核自动生成,则不能保证它们是连续的,事实上内核自动生成的 id 是由 entity 的 media_device->entity_id++
来实现赋值的,该值在 media_device_register
函数里面被初始化为1。
在卸载 entity 之后需要调用以下函数来释放申请到的相关资源,主要是释放动态分配的 media_link
结构体内存:
media_entity_cleanup(struct media_entity *entity); //与media_entity_init结对使用
要想遍历 entities 可以在用户空间进行 MEDIA_IOC_ENUM_ENTITIES
系统调用,需要设置 media_entity_desc
的 id 为 (0|MEDIA_ENT_ID_FLAG_NEXT)
,循环的过程中只需要设置 id |= MEDIA_ENT_ID_FLAG_NEXT
即可完成 entity 的遍历过程,如果需要枚举指定的 entitiy,需要设置 id 为指定 entity 的 id 值(内核 entity 的 id 是从1开始),这个在 entity 注册函数里面可以看到。代码实例如下,我尽量精简了贴出来的代码,防止占用过大篇幅:
int enum_media_device_entities(int iFd)
{
int iRet;
struct media_entity_desc desc;
desc.id = 0 | MEDIA_ENT_ID_FLAG_NEXT;
while (1) {
iRet = ioctl(iFd, MEDIA_IOC_ENUM_ENTITIES, &desc);
if (iRet < 0) {
MODULE_WRN("enum media entities end\n");
break;
}
MODULE_DBG("entity name[%s]\n", desc.name);
desc.id |= MEDIA_ENT_ID_FLAG_NEXT;
}
return 0;
}
int main(int argc, char *argv[])
{
int iErr = 0, ivFd;
ivFd = open("/dev/media0", O_RDWR);
iErr = enum_media_device_entities(ivFd);
close(ivFd);
open_err:
return iErr;
}
图遍历(深度优先)
图遍历是干嘛的?它为我们提供在运行时访问每一个、指定的 entities 的方法,至于为什么需要访问,是因为我们可能会需要在运行时去管理它们。
可以使用下面的函数对同属于一个media设备的entities进行遍历(线性遍历,非典型图遍历,也就是跟链表一样的遍历方式):
struct media_entity *entity;
media_device_for_each_entity(entity, mdev) {
/* entity will point to each entity in turn */
...
}
驱动可能需要从一个给定的 entity,通过使能的 links 对所有的可访问到的 entities 进行遍历,meida 框架提供了一个深度优先的 API 来完成这个任务。需要注意的是,要避免对闭环的图进行遍历,否则会陷入死循环,为了避免这种情况,函数限制了最大遍历深度为 MEDIA_ENTITY_ENUM_MAX_DEPTH
,该宏最新的定义是16**「截至 Linux-4.4.138」**。
media_entity_graph_walk_start(struct media_entity_graph *graph,
struct media_entity *entity);
media_entity_graph_walk_next(struct media_entity_graph *graph);
使用时先用第一个函数初始化图,然后循环调用第二个函数进行遍历,遍历全部完成之后第二个函数会返回NULL。遍历过程可以在任意一个时刻中断,并且无需调用清理函数。
有相应的帮助函数用来寻找两个给定的 pads 的 link,或者通过一个 pad 来找到与之相连的另一个 pad。
media_entity_find_link(struct media_pad *source, struct media_pad *sink);
media_entity_remote_pad(struct media_pad *pad);
补充 links 的设置
link 的属性可以在运行时被改变,调用以下函数即可完成:media_entity_setup_link(struct media_link *link, u32 flags);
flags
参数用来设置指定的 link 的属性,允许被配置的属性是从 MEDIA_LNK_FL_ENABLED
属性到 MEDIA_LNK_FL_ENABLE
或者 MEDIA_LNK_FL_DISABLE
标志,如果 link 设置了 MEDIA_LNK_FL_IMMUTABLE
标志的话,就不能够使能或者关闭。当一个 link 使能或者关闭时,meida framework 会分两次调用 sink 以及 source 端的 link_setup
来进行相关的设置,如果第二次调用失败的话,第一个调用也会被复原。
media 设备驱动可以设置 media_device->link_notify
指向一个回调函数,此函数会在 link_setup
操作完成之后被调用。如果有任何的 link 是 non-immutable 的话,entity 驱动就需要自己实现 link_setup
操作。一个 link 的配置不应该影响到其他 link,如果一个 link 连接在 sink pad 上,并且该 link 被使能了,那么其他连接到该 pad 的 link 就不能再被使能,此时应该返回 -EBUSY
。
- pipeline与media流
pipeline 的概念前面已经介绍过了,不再重复,这里给一副说明图(其实这个不是非常的清晰易懂,还有更加清晰易懂的由于某些原因不能放出,请读者发挥想象,根据图中以及上面的描述自行抽象出来一个图,只要紧紧围绕一点-pipeline 就是数据流链路的抽象,我相信你):
当开启 streaming 时,驱动应当通知 pipeline 上所有的 entity 来维护当前状态不被改变,可以调用下面的函数完成通知(该函数只会调用 sink 端的 validate 回调):
media_entity_pipeline_start(struct media_entity *entity, struct media_pipeline *pipe);
该函数将会标记所有的处在使能 link 连线上的 entity 为 streaming 状态,不管是直接还是间接。第二个参数指向的 media_pipeline 结构体会被传递给 pipeline 上面的所有 entity,驱动需要把 media_pipeline 结构体嵌入到一个更高级的结构体里面,并且可以从 media_entity 结构体访问到 pipeline。等到需要停止 streaming 时,需要调用:
media_entity_pipeline_stop(struct media_entity *entity);
由于start函数可以嵌套调用,所以与之对应,stop函数也应该保持相应数量的调用。media_entity_pipeline_start
函数会进行 link 有效性的检验,此时 media_entity
的 link_validate
成员会被调用用来完成检验。下面一幅图是遍历的说明:
上图中的圆圈序号指的是访问的先后顺序。值得一提的是内核关于广度优先图遍历的实现很耐人寻味,很具有参考价值,值得自己去找到内核代码探究一番。其中用到了栈、位图等概念。具体的代码在 media-entity.c/media_entity_pipeline_start
函数里面。
由于上面的遍历是广度优先的,并且是全部遍历,也就是说如果你的 isp 有两个输入源,那这两个输入源可能会同时被打开,更多时候我们并不希望这种情况发生,我们期望的是指定的输入源、指定的单链路的 pipeline 被打开,此时就需要自行去管理 pipeline,可以实现一个自己的 pipeline 结构体进行相关的管理。实现方式就很简单,这个 pipeline 结构体类似下面:
struct spec_pipeline {
struct list_head entities; // pipeline 线上的 entity 链表头
struct media_entity entities[PIPE_LENGTH]; //与上一个类似,随自己想法去实现
int (*open_fun)(struct media_entity entity, int onoff);
int (*s_stream)(struct media_entity entity, int onoff);
... ...
};
接下来就不用多说了吧,思维赶紧发散一下、扩展一下,很容易实现一个易用的自己特定的 pipeline,可以实现指定同源不同目的的数据流区分管理,不同源不同目的的数据流区分管理等等。
Tips
- 从
media_entity
找到v4l2_subdev
可以使用media_entity_to_v4l2_subdev
函数来完成。 - 可以在 video 模块的 streamon 部分加入对link的使能标记,
media_entity_pipeline_start
函数会对entity.stream_count
成员进行增值操作,并且会将第二个参数中的 pipe 传递给 link 线上的entity.pipe
成员。使能标记完成之后可以对各个 entity 进行图遍历来调用其set_stream
成员开启 stream。事实上在s_param,s_fmt
等 ioctl 调用时就需要进行图遍历以调用整个 pipeline 上面的各个 entity 的回调函数进行相关的设置。 - 在子设备节点都注册完毕之后可以通过
media_entity_create_link
来完成各个 entity 的连接,以待之后整个数据流的开启。 - 为什么要有 media framework?因为仅仅有 subdev 的话,各个子设备类是处于平级状态,并没有数据流的流向之分,如果需要建立数据流 pipeline 的话需要自行去实现,这样会比较麻烦,而有了 media framework 的话这些管理就会方便很多,因为它提供了 pipeline 的一切管理操作,这样就可以把众多的 subdev 串联成为一个完整的数据流,从而进行正确、有向的数据传递。
v4l2_subdev
与video_device
内部都有一个media_entity
结构体(非指针类型),video_device
内部的entity会随着video 设备的注册而注册,名字沿用video_deivce
的名字,这两个是有所区别的,使用的时候需要特别注意下。
结束语:本文到此结束,希望你已经能够完成一个完整功能的 pipeline,能够进行 open/close, s_stream 等操作了,并且可以实现自定义的设备数据流串联,实时管理等功能。下文预告-videobuf2 的实现与使用。
![](https://i-blog.csdnimg.cn/blog_migrate/73f9221b425e89d5b68b55981a0a0493.png)