简介

Linux DRM 层包含旨在支持复杂图形设备需求的代码，通常包含非常适合 3D 图形加速的可编程流水线。内核中的图形驱动程序可以使用 DRM 函数来简化诸如内存管理、中断处理和 DMA 之类的任务，并为应用程序提供统一的接口。

关于版本说明：本指南涵盖 DRM 树中发现的功能，包括 TTM 内存管理器、输出配置和模式设置，以及新的 vblank 内部结构，以及当前内核中的所有常规功能。

[在此处插入典型 DRM 堆栈的图表]

样式指南

为了保持一致性，本文档使用美式英语。缩写形式全部使用大写字母，例如：DRM、KMS、IOCTL、CRTC 等。为了便于阅读，文档充分利用了 kerneldoc 提供的标记字符：函数参数使用 @parameter，结构体成员（在同一结构体中）使用 @member，引用结构体使用 &struct structure，引用函数使用 function()。如果被引用的对象的 kerneldoc 存在，则所有这些都会被自动超链接。引用函数 vtable 中的条目（以及一般的结构体成员）时，请使用 &vtable_name.vfunc。遗憾的是，这目前还不能直接链接到成员，只能链接到结构体。

除非在特殊情况下（将锁定变体与未锁定变体分开），否则函数的锁定要求不会在 kerneldoc 中记录。相反，应该在运行时使用例如 WARN_ON(!mutex_is_locked(...)); 来检查锁定。由于忽略文档比忽略运行时噪音要容易得多，因此这提供了更大的价值。最重要的是，当锁定规则发生变化时，运行时检查确实需要更新，从而增加了它们正确的可能性。在文档中，应该在相关结构中解释锁定规则：要么在解释其保护内容的锁的注释中，要么数据字段需要一个关于哪个锁保护它们的注释，或者两者都需要。

具有非 void 返回值的函数应包含一个名为 “Returns” 的部分，解释不同情况下预期的返回值及其含义。目前，对于该部分名称是否应全部大写，以及是否应以冒号结尾，尚无共识。请使用文件本地样式。其他常见的部分名称是“Notes”，其中包含关于危险或棘手边缘情况的信息，以及“FIXME”，其中接口可以进行清理。

另请阅读 内核文档的总体指南。

kAPI 的文档要求

所有导出到其他模块的内核 API 都必须进行文档化，包括它们的数据结构，以及至少一个解释整体概念的简短介绍部分。文档应尽可能多地以 kerneldoc 注释的形式放入代码本身。

不要盲目地记录所有内容，而只记录对驱动程序作者相关的内容：drm.ko 的内部函数，以及绝对的静态函数不应具有正式的 kerneldoc 注释。如果您觉得需要注释，请使用普通的 C 注释。您可以在注释中使用 kerneldoc 语法，但它不应以 /** kerneldoc 标记开头。数据结构也是如此，根据文档指南，使用 /* private: */ 注释来注释任何完全私有的内容。

入门

欢迎有兴趣帮助 DRM 子系统的开发人员。通常，人们会为了解决 checkpatch 或 sparse 报告的各种问题而提交补丁。我们欢迎这样的贡献。

任何希望更进一步的人都可以在 TODO 列表 上找到一份杂务列表。

贡献流程

大多数情况下，DRM 子系统的工作方式与其他任何内核子系统一样，请参阅 主流程指南和文档 以了解其工作原理。在这里，我们只记录 GPU 子系统的一些特殊之处。

功能合并截止日期

所有功能工作都必须在当前发布周期的 -rc6 版本之前进入 linux-next 树，否则必须推迟，并且无法进入下一个合并窗口。所有补丁必须最迟在 -rc7 之前进入 drm-next 树，但如果您的分支不在 linux-next 中，则必须在 -rc6 之前完成。

在此之后，只允许进行错误修复（例如在上游合并窗口以 -rc1 版本关闭之后）。不允许启用新平台或新的驱动程序。

这意味着大约有一个月的时间，功能工作无法合并。建议的处理方法是拥有一个始终开放的 -next 树，但要确保在停滞期期间不将其馈送到 linux-next 中。例如，drm-misc 就是这样工作的。

行为准则

作为 freedesktop.org 项目，dri-devel 和 DRM 社区遵循贡献者公约，该公约位于：https://www.freedesktop.org/wiki/CodeOfConduct

在邮件列表、IRC 或错误跟踪器上与社区成员互动时，请以尊重和文明的方式行事。社区代表整个项目，项目不容忍辱骂或欺凌行为。

用作示例的简单 DRM 驱动程序

DRM 子系统包含许多辅助函数，以简化简单图形设备的驱动程序编写。例如，drivers/gpu/drm/tiny/ 目录有一组驱动程序，这些驱动程序足够简单，可以在单个源文件中实现。

这些驱动程序使用了 struct drm_simple_display_pipe_funcs，它隐藏了 DRM 子系统的任何复杂性，只需要驱动程序实现操作设备所需的一些函数。这可以用于只需要一个显示流水线和一个全屏扫描输出缓冲区馈送一个输出的设备。

微型 DRM 驱动程序是了解 DRM 驱动程序应该是什么样子很好的示例。由于只有几百行代码，它们很容易阅读。

外部参考

第一次深入研究 Linux 内核子系统可能是一次令人不知所措的体验，人们需要熟悉所有概念并了解子系统的内部结构以及其他细节。

为了缩短学习曲线，本节包含一份演示文稿和文档列表，可用于学习 DRM/KMS 和一般图形知识。

人们可能想要进入 DRM 的原因有很多：移植现有的 fbdev 驱动程序、为新硬件编写 DRM 驱动程序、修复在处理图形用户空间堆栈时可能遇到的错误等。因此，学习材料涵盖了 Linux 图形堆栈的许多方面。从内核和用户空间堆栈的概述到非常具体的主题。

该列表按时间倒序排列，以将最新的材料放在最前面。但所有这些都包含有用的信息，并且通过阅读较旧的材料来了解 DRM 子系统所做的更改的原理和背景可能是有价值的。

会议演讲

幻灯片和文章