夜雨聆风学习资料网

ARTICLE · 1370892

V4L2 源码深度解析(二十):从 Entity 到 Pad、Link——Linux 怎样描述一条图像处理链路?

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
一个媒体功能模块
Sensor、CSI、ISP、Scaler、Capture
media_pad
Entity 的输入或输出端口
Sensor source pad、ISP sink pad
media_link
两个 Pad 或媒体对象之间的连接
Sensor Pad 0 → CSI Pad 0
media_interface
Entity 对外提供的访问接口
/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
当前 Link 已启用
MEDIA_LNK_FL_IMMUTABLE
Link 状态不可由普通链路配置操作修改
MEDIA_LNK_FL_DYNAMIC
标记动态 Link,影响流运行期间链路变更限制
MEDIA_LNK_FL_DATA_LINK
数据 Link 类型
MEDIA_LNK_FL_INTERFACE_LINK
接口 Link 类型
MEDIA_LNK_FL_ANCILLARY_LINK
辅助 Link 类型

Link 被创建,不代表它一定启用。驱动可以在创建时给出初始标志。对于非动态 Link,如果相关 Pad 已经处于 Streaming 管线中,修改 Link 状态可能返回 -EBUSY。不可变 Link 则不能被改成与其固定状态不同的标志。

动态 Link 的语义不是“自动切换”,而是允许驱动在符合框架约束的运行场景中管理动态连接;是否能切换仍取决于驱动的 link_setup、设备状态和框架校验。

8. 从源码看 Pad 如何初始化:media_entity_pads_init()

源码位置:drivers/media/mc/mc-entity.c。

该函数主要做几件事:

  1. 检查 Pad 数量是否超过实现上限;
  2. 将 num_pads 保存到 Entity;
  3. 保存调用者提供的 pads 数组指针;
  4. 遍历每个 Pad,设置 pad->entity 和 pad->index;
  5. 如果 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。

登记过程的关键步骤:

  1. 检查 Entity 的 function 是否有效,必要时给出警告;
  2. 将 entity->graph_obj.mdev 指向目标 media_device;
  3. 初始化 Entity 的 Link 链表和 Link 计数;
  4. 使用 IDA 分配内部索引 internal_idx;
  5. 在 graph_mutex 保护下创建 Entity graph object;
  6. 遍历 Entity 的 Pad,为每个 Pad 创建 graph object;
  7. 通知已经注册的 Entity Notify 回调;
  8. 必要时扩展电源状态图遍历所需的图结构。

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,再进入内部实现。

内部实现会检查:

  1. Link 指针是否有效;
  2. 不允许修改的 Link 标志是否被改变;
  3. IMMUTABLE Link 是否被尝试改变;
  4. Link 状态是否本来就相同;
  5. 非 DYNAMIC Link 的两端 Pad 是否正在 Streaming;
  6. media_device_ops.link_notify 是否要求在变更前拒绝操作;
  7. 调用源、目标 Entity 的 link_setup 回调;
  8. 更新正向和反向 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 可整理为:

源 Entity / Pad
目标 Entity / Pad
初始状态
Sensor A / 0
Debayer A / 0
ENABLED、IMMUTABLE
Sensor A / 0
Raw Capture 0 / 0
ENABLED、IMMUTABLE
Sensor B / 0
Debayer B / 0
ENABLED、IMMUTABLE
Sensor B / 0
Raw Capture 1 / 0
ENABLED、IMMUTABLE
Debayer A / 1
Scaler / 0
ENABLED,可配置
Debayer B / 1
Scaler / 0
初始禁用
RGB/YUV Input / 0
Scaler / 0
初始禁用
Scaler / 1
RGB/YUV Capture / 0
ENABLED、IMMUTABLE

另有两条 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()。

该函数的主要顺序是:

  1. v4l2_device_register();
  2. 分配 ent_devs[];
  3. vimc_add_subdevs():按配置创建各实体;
  4. vimc_create_links():按数据链路和辅助链路配置建链;
  5. media_device_register():发布媒体设备节点;
  6. v4l2_device_register_subdev_nodes():发布符合条件的 Subdev 节点。

因此,VIMC 的媒体图不是由一次函数调用自动生成,而是由实体注册和显式建链步骤逐步建立。

13.2 Subdev Entity 的初始化

vimc_ent_sd_register() 的主要顺序是:

  1. 将 ved->ent 指向 sd->entity;
  2. 调用 v4l2_subdev_init();
  3. 设置 Entity function、Entity ops、Subdev owner/name 和私有数据;
  4. 设置 V4L2_SUBDEV_FL_HAS_DEVNODE;
  5. 调用 media_entity_pads_init();
  6. 调用 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. 常见理解错误

容易误解的说法
正确理解
Entity 就是 Subdev
Subdev 可以携带 Entity,但 Video 节点等也可以有 Entity。
Pad 就是硬件引脚
Pad 是媒体图中的逻辑数据端口,不等于芯片封装引脚或 MIPI lane。
Link 创建后图像就能传输
Link 只描述拓扑关系;还需要格式协商、硬件配置、流启动和缓冲区准备。
Link 一定处于 ENABLED
Link 可以存在但初始禁用。
Backlink 是另一条数据通路
Backlink 是内核图遍历辅助关系,不向应用重复报告。
Interface Link 是图像数据连接
Interface Link 关联 Entity 与访问接口。
Ancillary Link 承载图像
Ancillary Link 表示辅助实体关系,不是 Pad 数据路径。
media_entity_pads_init()
 会创建 Link
它初始化 Pad 关联,不创建 Entity 之间的数据 Link。
Media Controller 负责 DMA
DMA 和像素内存由采集/处理驱动及缓冲区框架负责。

16. 调试时如何验证媒体图

可以使用以下命令观察系统导出的媒体拓扑:

# 查看系统中的媒体设备
ls -l /dev/media*

# 打印指定媒体设备的拓扑
media-ctl -p -d /dev/media0

# 查询媒体设备信息
media-ctl -d /dev/media0 --print-dot

重点检查:

  1. Entity 是否存在,名称和 function 是否符合预期;
  2. 每个 Entity 的 Pad 数量、编号和 SOURCE/SINK 方向是否正确;
  3. Link 的 source/sink 端点是否正确;
  4. Link 是否启用,是否不可变;
  5. Video Interface 是否关联到预期 Capture Entity;
  6. 是否存在缺失 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 可查询的拓扑结构。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料