《DRM 专栏》｜彻底入门 DRM 驱动

本篇我们一起来学习如何在 kernel 空间编写 DRM 驱动程序。

DRM 驱动相关的概念

Objects

在开始编写 DRM 驱动程序之前，我有必要对 DRM 内部的 Objects 进行一番介绍。因为这些 Objects 是 DRM 框架的核心，它们缺一不可。

上图蓝色部分则是对物理硬件的抽象，黄色部分则是对软件的抽象。虚线以上的为 drm_mode_object，虚线以下为 drm_gem_object。

之前曾对这些 objects 做过简要介绍，这里有必要再强调一下这些 objects 的概念：

这些 objects 之间的关系：

通过上图可以看到，plane 是连接 framebuffer 和 crtc 的纽带，而 encoder 则是连接 crtc 和 connector 的纽带。与物理 buffer 直接打交道的是 gem 而不是 framebuffer。

需要注意的是，上图蓝色部分即使没有实际的硬件与之对应，在软件驱动中也需要实现这些 objects，否则 DRM 子系统无法正常运行。

drm_panel

drm_panel 不属于 objects 的范畴，它只是一堆回调函数的集合。但它的存在降低了 LCD 驱动与 encoder 驱动之间的耦合度。

耦合的产生：

connector 的主要作用就是获取显示参数，所以会在 LCD 驱动中去构造 connector object。但是 connector 初始化时需要 attach 上一个 encoder object，而这个 encoder object 往往是在另一个硬件驱动中生成的，为了访问该 encoder object，势必会产生一部分耦合的代码。

encoder 除了扮演信号转换的角色，还担任着通知显示设备休眠唤醒的角色。因此，当 encoder 通知 LCD 驱动执行相应的 enable/disable 操作时，就一定会调用 LCD 驱动导出的全局函数，这也必然会产生一部分的耦合代码。

为了解决该耦合的问题，DRM 子系统为开发人员提供了 drm_panel 结构体，该结构体封装了 connector & encoder 对 LCD 访问的常用接口。

于是，原来的 Encoder 驱动和 LCD 驱动之间的耦合，就转变成了上图中 Encoder 驱动与 drm_panel、drm_panel 与 LCD 驱动之间的“耦合”，从而实现了 Encoder 驱动与 LCD 驱动之间的解耦合。

为了方便驱动程序设计，通常都将 encoder 与 connector 放在同一个驱动中初始化，即 encoder 在哪，connector 就在哪。

如何抽象硬件

对于初学者来说，往往让他们迷惑的不是 DRM 中 objects 的概念，而是如何去建立这些 objects 与实际硬件的对应关系。因为并不是所有的 Display 硬件都能很好的对应上 plane/crtc/encoder/connector 这些 objects。下面我们就来一起学习，如何去抽象显示硬件到具体的 DRM object。

MIPI DSI 接口

下图为一个典型的 MIPI DSI 接口屏的硬件连接框图：

它在软件架构上与 DRM object 的对应关系如下图：

多余的细节不做介绍，这里只说明为何如此分配 drm object：

MIPI DPI 接口

DPI 接口也就是我们常说的 RGB 并行接口，Video 数据通过 RGB 并行总线传输，控制命令（如初始化、休眠、唤醒等）则通过 SPI/I2C 总线传输，比如早期的 S3C2440 SoC 平台。下图为一个典型的 MIPI DPI 接口屏的硬件连接框图：

该硬件连接在软件架构上与 DRM object 的对应关系如下图：

多余的细节不做介绍，这里只说明为何如此分配 drm object：

VKMS 学习

VKMS 是 “Virtual Kernel Mode Setting” 的缩写，它于2018年7月5日被合入到 linux-4.19 主线版本中，并存放在 drivers/gpu/drm/vkms 目录下。之所以称它为 Virtual KMS，是因为该驱动不需要真实的硬件，它完全是一个软件虚拟的“显示”设备，甚至连显示都算不上，因为当它运行时，你看不到任何显示内容。它唯一能提供的，就是一个由高精度 timer 模拟的 VSYNC 中断信号！该驱动存在的目的，主要是为了 DRM 框架自测试，以及方便那些无头显示器设备的调试应用。虽然我们看不到 VKMS 的显示效果，但是在驱动流程上，它实现了 modesetting 该有的基本操作。因其逻辑简单，代码量少，拿来做学习案例讲解再好不过。

随着内核版本的不断升级，添加到 VKMS 的功能也越来越多，截止到内核版本 kernel 5.7-rc2，该 VKMS 驱动已经集成了如下功能：

Atomic Modeset

VBlank

Dumb Buffer

Cursor & Primary Plane

Framebuffer CRC 校验

Plane Composition

GEM Prime Import

下面就跟着我一起来学习，如何从0到1实现一个 VKMS 驱动吧！

示例 1

这是一个最简单的 DRM 驱动代码：

DRM 框架还为我们做了下面这些事情：

创建设备节点：/dev/dri/card0

创建 sysfs 节点：/sys/class/drm/card0

创建 debugfs 节点：/sys/kernel/debug/dri/0

不过该驱动目前什么事情也做不了，你唯一能做的就是查看该驱动的名字：

你甚至都无法对 /dev/dri/card0 进行 open 操作，因为该驱动还没有实现 fops 接口。

示例 2

接下来我们给 vkms 添加上 fops 操作接口。

有了 fops，我们就可以对 card0 进行 open，read，ioctl 操作了。让我们看看现在可以执行哪些 IOCTL：

但是到目前为止，凡是和 modesetting 相关的操作，还是操作不了。

示例 3

添加 drm mode objects：

重点：

给 driver_features 添加上 DRIVER_MODESET 标志位，告诉 DRM Core 当前驱动支持 modesetting 操作；

drm_mode_config_init() 初始化一些全局的数据结构。注意，那些 Standard Properties 就是在这里创建的。

drm_xxx_init() 则分别用于创建 plane、crtc、encoder、connector 这4个 drm_mode_object。

由于上面4个 objects 在创建时，它们的 callback funcs 没有赋初值，所以真正的 modeset 操作目前还无法正常执行，不过我们至少可以使用下面这些只读的 modeset IOCTL 了：

示例 4

添加 FB 和 GEM 支持：

重点：

给 driver_features 添加上 DRIVER_GEM 标志位，告诉 DRM Core 该驱动支持 GEM 操作；

dumb_create 回调接口用于创建 gem object，并分配物理 buffer。这里直接使用 CMA helper 函数来实现；

fb_create 回调接口用于创建 framebuffer object，并绑定 gem objects。这里直接使用 CMA helper 函数实现。

fops 中的 mmap 接口，用于将 dumb buffer 映射到 userspace，它依赖 drm driver 中的 gem_vm_ops 实现。这里也直接使用 CMA helper 函数来实现。

现在，我们可以使用如下 IOCTL 来进行一些标准的 GEM 和 FB 操作了！

示例 5

实现 callback funcs，添加 Legacy Modeset 支持:

重点：

xxx_funcs 必须有，xxx_helper_funcs 可以没有。

drm_xxx_init() 必须有，drm_xxx_helper_add() 可以没有。

只有当 xxx_funcs 采用 DRM 标准的 helper 函数实现时，才有可能 需要定义 xxx_helper_funcs 接口。

drmModeSetCrtc() ===> crtc_funcs.set_config()；drmModePageFlip() ===> crtc_funcs.page_flip()；drmModeSetPlane() ===> plane_funcs.update_plane()；drmModeGetConnector() ===> connector_funcs.fill_modes()

xxx_funcs.destroy() 接口必须实现。

提示：本示例中的 funcs 和 helper funcs 接口无法再精简，否则运行时将出现 kernel crash！

helper 函数的作用：drm_xxx_funcs 是 drm ioctl 操作的最终入口，但是对于大多数 SoC 厂商来说，它们的 drm_xxx_funcs 操作流程基本相同，只是在寄存器配置上存在差异，因此开发者们将那些 common 的操作流程做成了 helper 函数，而将那些厂商差异化的代码放到了 drm_xxx_helper_funcs 中去，由 SoC 厂商自己实现。

有了各种 funcs 和 helper funcs，我们现在终于可以执行真正的 modeset 操作了。当前支持的 modeset IOCTL:

示例 6

将上面的 Legacy code 转换为 Atomic 版本：

重点：

给 driver_features 添加上 DRIVER_ATOMIC 标志位，告诉 DRM Core 该驱动支持 Atomic 操作。

drm_mode_config_funcs.atomic_commit() 接口是 atomic 操作的主要入口函数，必须实现。这里直接使用 drm_atomic_helper_commit() 函数实现。

Atomic 操作依赖 VSYNC 中断（即 VBLANK 事件），因此需要使用 hrtimer 来提供软件中断信号。在驱动初始化时调用 drm_vblank_init()，在 VSYNC 中断处理函数中调用 drm_handle_vblank()。

在 plane/crtc/encoder/connector objects 初始化完成之后，一定要调用 drm_mode_config_reset() 来动态创建各个 pipeline 的软件状态（即 drm_xxx_state）。

与 Legacy 相比，Atomic 的 xxx_funcs 必须 实现如下接口：reset()，atomic_duplicate_state()，atomic_destroy_state()，它们主要用于维护 drm_xxx_state 数据结构，不能省略！

drm_plane_helper_funcs.atomic_update() 必须实现！

终于，我们可以使用 drmModeAtomicCommit() 了。

总结

要实现一个 DRM KMS 驱动，通常需要实现如下代码：

fops、drm_driver

dumb_create、fb_create、atomic_commit

drm_xxx_funcs、drm_xxx_helper_funcs

drm_xxx_init()、drm_xxx_helper_add()

drm_dev_init()、drm_dev_register()

但这都只是表象，核心仍然是上面介绍的7个 objects，一切都围绕着这几个 objects 展开：

为了创建 crtc/plane/encoder/connector objects，需要调用 drm_xxx_init()。

为了创建 framebuffer object，需要实现 fb_create() callback。

为了创建 gem object，需要实现 dumb_create() callback。

为了创建 property objects，需要调用 drm_mode_config_init()。

为了让这些 objects 动起来，需要实现各种 funcs 和 helper funcs。

为了支持 atomic 操作，需要实现 atomic_commit() callback。

希望我的文章，能为那些还在 DRM 学习路上的小伙伴们提供帮助。下一篇，我将介绍 DRM GEM 相关的知识，敬请期待！