简介

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

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

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

风格指南

为了保持一致性，本文档使用美式英语。 缩写以全部大写字母书写，例如：DRM、KMS、IOCTL、CRTC 等。 为了方便阅读，文档充分利用 kerneldoc 提供的标记字符：@parameter 用于函数参数，@member 用于结构成员（在同一结构内），&struct 结构用于引用结构，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 子系统更改的理由和背景可能很有价值。

会议演讲

幻灯片和文章