ARTICLE · 1370892
V4L2 源码深度解析(二十):从 Entity 到 Pad、Link——Linux 怎样描述一条图像处理链路?
开篇:先回答一个问题
在 Linux 摄像头系统中,Sensor、CSI 接收器、ISP、Scaler 和 Capture 节点可能由不同驱动实现。内核需要一种统一方式描述它们是什么、每个模块从哪里接收数据、从哪里输出数据,以及模块之间怎样连接。这就是 Media Controller(媒体控制器) 要解决的问题。
Media Controller 并不负责搬运像素,也不分配图像缓冲区。它建立的是一张可查询、可遍历、可配置的媒体拓扑图。真正的数据仍由硬件链路、驱动和 DMA/VB2 路径处理。
本篇从三个基本对象开始:Entity 描述功能模块,Pad 描述模块端口,Link 描述端口之间的关系。 随后结合源码中的 mc-entity.c 和 VIMC,追踪对象如何初始化、登记和建链。

1. 为什么需要 Media Controller
只看 /dev/videoX,通常只能知道系统提供了哪些视频接口,却无法完整表达视频接口背后的处理路径。例如一帧 RAW 图像可能经过 Sensor、CSI 接收器、ISP、后处理模块,最后进入 Capture 节点。不同 SoC 的模块数量、连接方式和可切换路径也可能不同。
如果只用一个平面列表描述设备,就无法准确表达:
一个处理模块有几个输入端口和输出端口; 哪个上游模块连接到哪个下游模块; 某条连接当前是否启用; 一个实体是否还关联了控制或辅助接口; 某个节点属于哪条媒体处理管线。
Media Controller 用图结构描述这些关系。图由节点和边组成:Entity 是功能节点,Pad 是 Entity 上的端口,Link 则连接端口或实体接口。
2. 先区分五个概念
media_device | ||
media_entity | ||
media_pad | ||
media_link | ||
media_interface | /dev/videoX/dev/v4l-subdevX 对应的接口 |
不要把它们混为一谈。尤其是 media_link 与 media_interface:前者表达媒体连接,后者表达如何访问某个实体。/dev/mediaX 则是整个媒体拓扑的查询和配置入口,不是某个 Entity 的数据端口。
3. Entity:媒体图中的功能模块
struct media_entity 表示媒体图中的一个功能实体。它通常对应一个实际硬件模块或逻辑处理模块,例如:
摄像头 Sensor; MIPI CSI-2 接收器; ISP; Debayer; Scaler; 视频采集节点。
Entity 的 function 字段描述模块功能类别,例如 Sensor、视频处理器或 V4L I/O。name 用于标识实体,pads 和 num_pads 描述端口数组及数量,links 组织与实体相关的连接,ops 则提供实体级操作,例如链路校验。
Entity 不是 v4l2_subdev 的同义词。很多 Sensor、ISP 子模块会通过 v4l2_subdev 携带一个 media_entity;Capture 视频节点则可以通过 video_device.entity 参与媒体图。也有非 V4L2 的媒体实体。因此应理解为:V4L2 Subdev 或 Video Device 可以承载媒体实体,但 Media Entity 是 Media Controller 自己的图对象。
4. Pad:Entity 上的数据端口
一个 Entity 可以只有一个 Pad,也可以有多个 Pad。Pad 通过 MEDIA_PAD_FL_SINK 和 MEDIA_PAD_FL_SOURCE 描述方向:
MEDIA_PAD_FL_SINK:数据进入该 Entity 的端口;MEDIA_PAD_FL_SOURCE:数据从该 Entity 流出的端口。
例如一个典型处理模块有一个输入和一个输出:
Processor Entity
+----------------------+
上游数据 → | Pad 0 Pad 1 | → 下游数据
| SINK SOURCE |
+----------------------+
Pad 的 index 是它在所属 Entity 的 pads[] 数组中的索引,从 0 开始。它不是全局编号,也不是媒体图对象 ID。
Pad 的方向是建链时的重要约束:数据 Link 的源端必须是 SOURCE Pad,目标端必须是 SINK Pad。不能把两个 SOURCE Pad 直接连成一条正常的数据链路,也不能把两个 SINK Pad 直接相连。

5. Link:把两个 Pad 连接起来
数据 Link 的方向具有明确含义:
Source Entity 的 SOURCE Pad
|
| media_link
v
Sink Entity 的 SINK Pad
例如:
IMX335 SOURCE Pad 0
|
v
CSI Receiver SINK Pad 0
这表示媒体拓扑中 Sensor 的输出连接到 CSI 接收器的输入。它不表示内核在两个模块之间复制了一帧图像,也不代表链路已经在硬件上完成了电气配置。
media_link 记录连接两端、标志位和反向关联等信息。对数据 Link 来说,框架还维护反向 Link,便于从任一端遍历图。反向 Link 是内核遍历辅助结构,不会作为另一条独立的数据连接重复呈现给媒体拓扑接口。
6. 三种 Link 不要混淆
Media Controller 中常见的 Link 类型包括:
6.1 Data Link
连接两个媒体 Pad,描述媒体数据路径。典型形式是 SOURCE Pad → SINK Pad。media_create_pad_link() 创建的就是这种 Link。
6.2 Interface Link
把一个 Entity 与一个 Interface 关联起来。例如某个 Capture Entity 与 /dev/videoX 对应的 V4L2 Video Interface 关联。它回答“通过哪个接口访问这个实体”,不是图像数据流向。
6.3 Ancillary Link
表示实体之间的辅助关联,例如 Sensor 与 Lens。它不是像素数据路径,也不使用 SOURCE/SINK Pad 来表达数据方向。
7. Link 标志:连接存在,不代表一定启用
常见标志:
MEDIA_LNK_FL_ENABLED | |
MEDIA_LNK_FL_IMMUTABLE | |
MEDIA_LNK_FL_DYNAMIC | |
MEDIA_LNK_FL_DATA_LINK | |
MEDIA_LNK_FL_INTERFACE_LINK | |
MEDIA_LNK_FL_ANCILLARY_LINK |
Link 被创建,不代表它一定启用。驱动可以在创建时给出初始标志。对于非动态 Link,如果相关 Pad 已经处于 Streaming 管线中,修改 Link 状态可能返回 -EBUSY。不可变 Link 则不能被改成与其固定状态不同的标志。
动态 Link 的语义不是“自动切换”,而是允许驱动在符合框架约束的运行场景中管理动态连接;是否能切换仍取决于驱动的 link_setup、设备状态和框架校验。
8. 从源码看 Pad 如何初始化:media_entity_pads_init()
源码位置:drivers/media/mc/mc-entity.c。
该函数主要做几件事:
检查 Pad 数量是否超过实现上限; 将 num_pads保存到 Entity;保存调用者提供的 pads数组指针;遍历每个 Pad,设置 pad->entity和pad->index;如果 Entity 已经关联 media_device,则为 Pad 创建媒体图对象。
关键点:它不分配 Pad 数组,也不创建 Entity 到其他 Entity 的 Link。 Pad 数组通常由驱动对象内嵌或单独分配,必须保证在 Entity 使用期间一直有效。
源码中的核心逻辑可概括为:
entity->num_pads = num_pads;
entity->pads = pads;
media_entity_for_each_pad(entity, iter) {
iter->entity = entity;
iter->index = i++;
if (mdev)
media_gobj_create(mdev, MEDIA_GRAPH_PAD,
&iter->graph_obj);
}
一个容易忽略的时序细节来自 VIMC:Subdev 的 media_entity_pads_init() 发生在 v4l2_device_register_subdev() 之前。此时 Entity 可能还没有关联到 media_device,因此 pads_init() 只建立 Entity 与 Pad 的内存关系,不创建 Pad 的 graph object。随后 media_device_register_entity() 将 Entity 登记到 media_device 时,会统一创建 Entity 和它的 Pad 对应的 graph object。
Capture 节点也有类似的分阶段过程:先初始化 video_device.entity 的 Pad,后续视频节点注册路径再将 Entity 接入媒体设备。
9. Entity 如何进入 media_device:media_device_register_entity()
源码位置:drivers/media/mc/mc-device.c。
登记过程的关键步骤:
检查 Entity 的 function是否有效,必要时给出警告;将 entity->graph_obj.mdev指向目标media_device;初始化 Entity 的 Link 链表和 Link 计数; 使用 IDA 分配内部索引 internal_idx;在 graph_mutex保护下创建 Entity graph object;遍历 Entity 的 Pad,为每个 Pad 创建 graph object; 通知已经注册的 Entity Notify 回调; 必要时扩展电源状态图遍历所需的图结构。
media_gobj_create() 会设置 graph object 所属的 media_device,生成带类型信息的对象 ID,将对象挂入对应链表,并递增 topology_version。
这里需要区分两个 ID:
对外媒体图对象 ID:由 graph object 管理,用于拓扑描述; internal_idx:用于内核内部 Entity 枚举和图遍历位图。
它们不是同一个编号。
10. 从源码看数据 Link 怎样创建:media_create_pad_link()
源码位置:drivers/media/mc/mc-entity.c。
该函数首先拒绝调用者传入 Link 类型位,因为它自己会把类型设置为 MEDIA_LNK_FL_DATA_LINK。随后检查:
source 和 sink Entity 是否有效; source_pad、sink_pad 是否越界; 源端 Pad 是否设置 MEDIA_PAD_FL_SOURCE;目标 Pad 是否设置 MEDIA_PAD_FL_SINK。
检查通过后,函数为源 Entity 分配一个 Link,填写 source、sink 和 flags,并创建 Link graph object。接着为目标 Entity 建立反向 Link,设置 is_backlink,让正向与反向 Link 互相指向,并更新 Entity 与 Pad 的 Link 计数。
简化后的结构关系:
source->links sink->links
| |
v v
正向 Link -------------------------- 反向 Link
| |
+------------- reverse --------------+
正向 Link: is_backlink = false
反向 Link: is_backlink = true
反向 Link 不是第二条独立的媒体数据路径。它是为了支持从 Sink 一侧也能遍历到上游连接。源码注释明确说明,backlink 用于图遍历辅助,不向应用层重复报告。
11. Link 删除:为什么需要同时处理反向 Link
media_entity_remove_links() 会在媒体图锁保护下调用内部删除逻辑。对于 Data Link,删除时不仅要从当前 Entity 的链表移除正向 Link,还要找到远端 Entity 中的反向 Link,一并删除对应 graph object,并更新 Entity/Pad 的 Link 计数。
因此,不能只 list_del() 一侧就认为数据连接已经完整删除。正反向 Link、graph object 和计数必须保持一致。
12. Link 状态修改:media_entity_setup_link()
外部配置 Link 时,通常通过 Media Controller ioctl 到达相应接口,内核最终调用 media_entity_setup_link()。该函数获取 graph_mutex,再进入内部实现。
内部实现会检查:
Link 指针是否有效; 不允许修改的 Link 标志是否被改变; IMMUTABLE Link 是否被尝试改变; Link 状态是否本来就相同; 非 DYNAMIC Link 的两端 Pad 是否正在 Streaming; media_device_ops.link_notify是否要求在变更前拒绝操作;调用源、目标 Entity 的 link_setup回调;更新正向和反向 Link 的 flags。
如果目标 Entity 的 link_setup 拒绝修改,框架会按实现尝试恢复另一端先前的状态。驱动的 link_setup 是设备相关约束的重要入口,不能认为 Media Controller 只改一个内存标志就完成了所有硬件切换。
12.1 link_setup 与 link_validate 不是一回事
media_entity_operations 可以提供 Entity 级操作,其中常见的两个回调职责不同:
link_setup:链路启用或禁用状态发生变化时,驱动检查是否允许该变化,并可执行设备相关配置。link_validate:在媒体管线准备运行、需要验证链路两端格式时,检查连接两端的格式是否兼容。
VIMC 的 Subdev Entity 操作表使用 v4l2_subdev_link_validate;Capture Entity 使用 vimc_vdev_link_validate。这说明“链路创建成功”与“链路两端格式一定兼容”是两个不同阶段。
12.2 media_create_pad_link() 的调用前提
源码中的 media_create_pad_link() 检查 Entity、Pad 索引和 Pad 方向,并使用源端、目标端 Entity 的 graph_obj.mdev 创建正向与反向 Link graph object;函数体本身没有显式获取 graph_mutex,也没有显式比较两端 mdev 是否相同。因此调用方应保证两端 Entity 已经正确登记到同一个 media_device,并遵守对应拓扑构建阶段的并发约束。VIMC 在 vimc_register_devices() 中先登记所有实体,再在媒体设备对外发布前集中调用 vimc_create_links()。不能把这个函数误读为“内部自动完成全部锁保护和跨设备校验”。
13. 用 VIMC 看完整对象怎样组织
VIMC 是 Linux Media 测试驱动,适合观察 Entity、Pad、Link 的组织机制。当前源码中,vimc-core.c 用配置数组描述实体和连接:
ent_config[]:定义 Sensor A/B、Debayer A/B、Raw Capture、Scaler、RGB/YUV Capture、Lens 等实体;data_links[]:描述数据链路的源实体、源 Pad、目标实体、目标 Pad 和初始 flags;ancillary_links[]:描述 Sensor 与 Lens 的辅助关联。
部分数据 Link 初始启用且不可变,部分 Link 初始启用但可配置,还有部分 Link 初始禁用。它清楚说明:拓扑连接可以预先存在,但启用状态是另一层信息。
本份配置中的数据 Link 可整理为:
另有两条 Ancillary Link:Sensor A 与 Lens A、Sensor B 与 Lens B。

13.1 VIMC 的注册顺序
vimc_probe() 先建立 vimc_device,将 v4l2_dev.mdev 指向 mdev,初始化 media_device,然后进入 vimc_register_devices()。
该函数的主要顺序是:
v4l2_device_register();分配 ent_devs[];vimc_add_subdevs():按配置创建各实体;vimc_create_links():按数据链路和辅助链路配置建链;media_device_register():发布媒体设备节点;v4l2_device_register_subdev_nodes():发布符合条件的 Subdev 节点。
因此,VIMC 的媒体图不是由一次函数调用自动生成,而是由实体注册和显式建链步骤逐步建立。

13.2 Subdev Entity 的初始化
vimc_ent_sd_register() 的主要顺序是:
将 ved->ent指向sd->entity;调用 v4l2_subdev_init();设置 Entity function、Entity ops、Subdev owner/name 和私有数据; 设置 V4L2_SUBDEV_FL_HAS_DEVNODE;调用 media_entity_pads_init();调用 v4l2_device_register_subdev()。
在 v4l2_device_register_subdev() 中,如果 v4l2_dev->mdev 存在,就调用 media_device_register_entity()。这正是前面提到的“先初始化 Pad,再登记 Entity 并创建 graph object”的实际例子。
13.3 Capture Entity 的初始化
VIMC Capture 不是 Subdev。vimc_capture_add() 初始化 video_device.entity,设置 MEDIA_ENT_F_IO_V4L,将其 Pad 标记为 SINK,然后调用 media_entity_pads_init()。之后初始化 VB2 队列,并最终注册 video_device。视频节点注册路径会将 Capture Entity 接入 Media Controller。
这说明 Media Entity 并不只属于 Subdev:Video 节点也可以直接拥有 Entity。
14. 真实摄像头驱动中如何套用这套模型
以典型摄像头链路为例:
IMX335 Sensor
SOURCE Pad 0
|
v
MIPI CSI-2 Receiver
SINK Pad 0 / SOURCE Pad 1
|
v
CIF 或 ISP
SINK Pad / SOURCE Pad
|
v
Capture Video Entity
SINK Pad 0
|
v
/dev/videoX
Sensor 驱动通常提供自己的 v4l2_subdev 和 media_entity,并通过 media_entity_pads_init() 声明输出 Pad。接收端驱动在异步匹配、绑定等流程中识别上游 Subdev,并在合适的阶段建立媒体连接。Capture 节点则通过 video_device.entity 表示视频采集实体。
这张图只表示常见逻辑关系,不意味着所有 Rockchip SoC 都是 Sensor → MIPI → CIF → ISP → Capture 的固定串行结构。某些平台存在 ISP 直连、旁路、多个虚拟通道、在线/离线路径或不同 Capture 节点,必须以目标 SoC、DTS 和 BSP 实际拓扑为准。
15. 常见理解错误
media_entity_pads_init() | |
16. 调试时如何验证媒体图
可以使用以下命令观察系统导出的媒体拓扑:
# 查看系统中的媒体设备
ls -l /dev/media*
# 打印指定媒体设备的拓扑
media-ctl -p -d /dev/media0
# 查询媒体设备信息
media-ctl -d /dev/media0 --print-dot
重点检查:
Entity 是否存在,名称和 function 是否符合预期; 每个 Entity 的 Pad 数量、编号和 SOURCE/SINK 方向是否正确; Link 的 source/sink 端点是否正确; Link 是否启用,是否不可变; Video Interface 是否关联到预期 Capture Entity; 是否存在缺失 Link、方向反接或不符合硬件拓扑的连接。
media-ctl -p 显示的是内核媒体图状态,不等于硬件正在输出有效像素。若拓扑正确但无图像,还需要继续检查格式、链路时钟、接收错误、中断、DMA 地址和 VB2 完成路径。
结语
Media Controller 用一套统一的图模型描述媒体设备:Entity 表示功能模块,Pad 表示模块端口,Link 表示端口之间的连接。接口对象负责把实体与 /dev/videoX、/dev/v4l-subdevX 等访问入口关联起来。
理解这三个对象后,再看 media_entity_pads_init()、media_device_register_entity() 和 media_create_pad_link(),就能清楚地知道一条媒体链路是怎样从驱动私有对象逐步变成 /dev/mediaX 可查询的拓扑结构。















































































