RaspberryPi KMS HDMI 输出图形驱动程序

版权页

2020-2023 Raspberry Pi Ltd（前身为 Raspberry Pi (Trading) Ltd.） 本文档根据知识共享署名-NoDerivatives 4.0 International (CC BY-ND 4.0) 许可获得许可。 构建日期：2023-02-10 构建版本：githash：c65fe9c-clean

法律免责声明

不时修改的 RASPBERRY PI 产品（包括数据表）的技术和可靠性数据（“资源”）由 RASPBERRY PI LTD（“RPL”）“按原样”提供，以及任何明示或暗示的保证，包括但不限于TO，不提供针对特定用途的适销性和适用性的默示保证。 在适用法律允许的最大范围内，在任何情况下，RPL 均不对任何直接、间接、偶然、特殊、惩戒性或后果性损害（包括但不限于替代商品或服务的采购；使用损失、数据, 或利润; 或业务中断），无论是基于合同、严格责任或侵权行为（包括疏忽或其他）以任何方式因使用资源而引起的任何责任理论，即使已被告知这种可能性此类损坏。 RPL 保留随时对资源或其中描述的任何产品进行任何增强、改进、更正或任何其他修改的权利，恕不另行通知。 这些资源适用于具有适当设计知识水平的熟练用户。 用户对其选择和使用资源以及其中描述的产品的任何应用承担全部责任。 用户同意赔偿 RPL 并使其免受因使用资源而产生的所有责任、成本、损害或其他损失。RPL 授予用户仅将资源与 Raspberry Pi 产品结合使用的权限。 禁止对资源的所有其他使用。 未向任何其他 RPL 或其他第三方知识产权授予许可。 高风险活动。 Raspberry Pi 产品并非设计、制造或旨在用于需要故障安全性能的危险环境，例如核设施、飞机导航或通信系统、空中交通管制、武器系统或安全关键应用（包括生命支持）的运行系统和其他医疗设备），其中产品故障可能直接导致死亡、人身伤害或严重的物理或环境破坏（“高风险活动”）。 RPL 明确否认对高风险活动适用性的任何明示或暗示保证，并且不对在高风险活动中使用或包含 Raspberry Pi 产品承担任何责任。 Raspberry Pi 产品根据 RPL 的标准条款提供。 RPL 提供的资源不会扩展或以其他方式修改 RPL 的标准条款，包括但不限于其中表达的免责声明和保证。

文档版本历史

文件范围

本文档适用于以下树莓派产品

介绍

随着 KMS（内核模式设置）图形驱动程序的推出，Raspberry Pi Ltd 正在摆脱对视频输出系统的传统固件控制，转向更加开源的图形系统。 然而，这也带来了一系列挑战。 本文档旨在帮助解决在迁移到新系统时可能出现的任何问题。 本白皮书假定 Raspberry Pi 正在运行 Raspberry Pi OS，并且已完全更新最新的固件和内核。

术语

数字版权管理： Direct Rendering Manager，Linux 内核的一个子系统，用于与图形处理单元 (GPU) 通信。 与 FKMS 和 KMS 配合使用。
DVI： HDMI 的前身，但没有音频功能。 HDMI 到 DVI 电缆和适配器可用于将 Raspberry Pi 设备连接到配备 DVI 的显示器。
编辑： 扩展显示标识数据。 显示设备的一种元数据格式，用于描述其对视频源的功能。 EDID 数据结构包括制造商名称和序列号、产品类型、物理显示器尺寸和显示器支持的时序，以及一些不太有用的数据。 一些显示器可能有有缺陷的 EDID 块，如果显示系统不处理这些缺陷，就会导致问题。
FKMS（vc4-fkms-v3d）： 假内核模式设置。 虽然固件仍然控制着低级硬件（例如amp例如，高清晰度多媒体接口 (HDMI) 端口、显示串行接口 (DSI) 等），标准 Linux 库在内核本身中使用。 Buster 中默认使用 FKMS，但现在已弃用，取而代之的是 Bullseye 中的 KMS。
HDMI： 高清晰度多媒体接口是专有的音频/视频接口，用于传输未压缩的视频数据以及压缩或未压缩的数字音频数据。
HPD： 热插拔检测。 由连接的显示设备断言以表明其存在的物理线路。
公里数： 内核模式设置； 看 https://www.kernel.org/doc/html/latest/gpu/drm-kms.html 更多细节。 在树莓派上，vc4-kms-v3d是实现KMS的驱动，常被称为“KMS驱动”。 遗留图形堆栈：完全在由 Linux 帧缓冲区驱动程序公开的 VideoCore 固件 blob 中实现的图形堆栈。 直到最近，大多数 Raspberry Pi Ltd 设备都在使用传统图形堆栈； 现在逐渐被 (F)KMS/DRM 取代。

HDMI 系统和图形驱动程序

Raspberry Pi 设备使用 HDMI 标准进行视频输出，这在现代 LCD 显示器和电视上很常见。 Raspberry Pi 3（包括 Raspberry Pi 3B+）和更早的设备有一个 HDMI 端口，能够使用全尺寸 HDMI 连接器输出 1920 × 1200 @60Hz。 Raspberry Pi 4 有两个 micro HDMI 端口，并且可以在两个端口上进行 4K 输出。 根据设置，Raspberry Pi 0 上的 HDMI 4 端口最高可达 4kp60，但是当使用两个 4K 输出设备时，您在两个设备上都被限制为 p30。 图形软件堆栈，无论版本如何，都负责询问连接的 HDMI 设备的属性，并适当地设置 HDMI 系统。 Legacy 和 FKMS 堆栈都使用 VideoCore 图形处理器中的固件来检查 HDMI 存在和属性。 相比之下，KMS 使用完全开源的 ARM 端实现。 这意味着两个系统的代码库完全不同，在某些情况下，这可能导致两种方法之间的行为不同。 HDMI 和 DVI 设备使用称为 EDID 块的元数据向源设备标识自己。 这是由源设备通过 I2C 连接从显示设备读取的，这对最终用户来说是完全透明的，因为它是由图形堆栈完成的。 EDID 块包含大量信息，但主要用于指定显示器支持哪些分辨率，因此可以设置 Raspberry Pi 以输出合适的分辨率。

开机时如何处理HDMI

第一次上电时，树莓派会经历一系列 stages，称为 boot stages：

1. 第一个-stage，基于 ROM 的引导加载程序启动 VideoCore GPU。
2. 秒秒tage bootloader（在 Raspberry Pi 4 之前的设备上是 SD 卡上的 bootcode.bin，在 Raspberry Pi 4 上是 SPI EEPROM 中）：
   1. 在 Raspberry Pi 4 上，second-stag引导加载程序将启动 HDMI 系统，询问显示器的可能模式，然后适当地设置显示器。 此时显示器用于提供基本的诊断数据。
   2. 引导加载程序诊断显示（07 年 2022 月 XNUMX 日起）将显示任何连接的显示器的状态（是否存在热插拔检测 (HPD)，以及是否从显示器恢复了 EDID 块）。
3. VideoCore 固件 (start.elf) 已加载并运行。 这将接管 HDMI 系统的控制，从任何连接的显示器读取 EDID 块，并在这些显示器上显示彩虹屏幕。
4. Linux 内核启动
   1. 在内核启动期间，KMS 将从固件接管 HDMI 系统的控制权。 EDID 块再次从任何连接的显示器读取，此信息用于设置 Linux 控制台和桌面。

可能出现的问题和症状

迁移到 KMS 时遇到的最常见的故障症状是最初启动良好，先是引导加载程序屏幕，然后出现彩虹屏幕，几秒钟后显示屏变黑并且不再亮起。 显示器变黑的时间点实际上是内核启动过程中 KMS 驱动程序从固件接管运行显示器的时间点。 Raspberry Pi 当前在除 HDMI 输出之外的所有方面都在运行，因此如果启用了 SSH，那么您应该能够通过该路由登录到设备。 绿色的 SD 卡访问 LED 通常会偶尔闪烁。 也有可能您根本看不到 HDMI 输出； 没有引导加载程序显示，也没有彩虹屏幕。 这通常可以归因于硬件故障。

诊断故障

根本没有HDMI输出
设备可能根本没有启动，但这不在本白皮书的讨论范围之内。 假设观察到的行为是显示问题，则在启动过程的任何部分缺少 HDMI 输出通常是由于硬件故障。 有许多可能的选择：

• HDMI 电缆不良
• 尝试使用新电缆。 有些电缆，尤其是非常便宜的电缆，可能不包含 Raspberry Pi 成功检测显示器所需的所有通信线路（例如热插拔）。
• Raspberry Pi 上的 HDMI 端口有缺陷
• 如果您使用的是 Raspberry Pi 4，请尝试使用其他 HDMI 端口。
• 显示器上的 HDMI 端口有缺陷
• 有时显示器或电视上的 HDMI 端口可能会磨损。 如果设备有一个端口，请尝试不同的端口。
• 在极少数情况下，显示设备可能仅在打开时或选择了正确的端口时才提供 EDID 数据。 要进行检查，请确保设备已打开并且选择了正确的输入端口。
• 显示设备未断言热插拔检测线

初始输出，然后屏幕变黑
如果在 Linux 内核启动期间显示屏出现但随后熄灭，则有多种可能的原因，这些通常与从显示设备读取 EDID 的问题有关。 从上面处理启动顺序的部分可以看出，EDID 在启动过程中的多个不同点被读取，并且这些读取中的每一个都由不同的软件完成。 当 KMS 接管时，最终读取由未更改的上游 Linux 内核代码执行，这不会处理有缺陷的 EDID 格式以及早期的固件软件。 这就是 KMS 接管后显示器无法正常工作的原因。 有多种方法可以确认 KMS 是否未能读取 EDID，其中两种方法如下。
检查引导加载程序诊断屏幕（仅限 Raspberry Pi 4）

笔记
引导加载程序诊断需要最新的引导加载程序。 您可以使用以下说明升级到最新版本： https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#updating-the-bootloader 取出 SD 卡并重启树莓派。 在 Install OS 屏幕上按 ESC，诊断屏幕应出现在显示设备上。 显示屏上应该有一行以 display: — for ex 开头amp乐：

• 展示： DISP0：HDMI HPD=1 EDID=ok #2 DISP1：HPD=0 EDID=none #0

Raspberry Pi 4 的输出显示系统在 HDMI 端口 0 上检测到 HDMI 显示器，热插拔检测有效，EDID 读取正常。 在 HDMI 端口 1 上找不到任何内容。

检查KMS系统是否检测到EDID
要检查这一点，您需要从另一台计算机通过 SSH 登录到 Raspberry Pi 设备。 使用 Raspberry Pi Imager 创建 SD 卡映像时，可以使用高级设置选项启用 SSH。 在已经镜像的 SD 卡上启用 SSH 有点复杂：您需要使用另一台计算机添加一个 file 将 ssh 命名为引导分区。 更换原装树莓派中的SD卡并上电。 这应该启用 SSH，并使用 DHCP 分配的 IP 地址。 登录后，在终端提示符下键入以下内容以显示检测到的任何 EDID 的内容（您可能需要将 HDMI-A-1 更改为 HDMI-A-2，具体取决于显示设备所连接的 Raspberry Pi 上的 HDMI 端口to): cat /sys/class/drm/card?-HDMI-A-1/edid 如果没有名为 card?-HDMI-A-1 或类似的文件夹，则可能无法从显示器读取 EDID设备。

笔记
在成功读取EDID的情况下，有一个有用的虚 file 在同一文件夹中，称为模式，显示时显示 EDID 声称设备支持的所有可能模式。

缓解措施

热插拔检测失败 如果固件和 KMS 均未能找到连接的显示器，则可能是热插拔检测失败——即 Raspberry Pi 不知道已插入设备，因此它不会检查 EDID。 这可能是由于电缆损坏或显示设备未正确断言热插拔引起的。 您可以通过更改内核命令行来强制热插拔检测 file (cmdline.txt) 存储在 Raspberry Pi OS SD 卡的引导分区中。 你可以编辑这个 file 在另一个系统上，使用您喜欢的任何编辑器。 将以下内容添加到 cmdline.txt 的末尾 file: video=HDMI-A-1:1280×720@60D 如果您使用的是第二个 HDMI 端口，请将 HDMI-A-1 替换为 HDMI-A-2。 您还可以指定不同的分辨率和帧速率，但请确保选择显示设备支持的分辨率和帧速率。

笔记
可以在此处找到有关视频的内核命令行设置的文档： https://www.kernel.org/doc/Documentation/fb/modedb.txt

警告
较旧的图形堆栈支持使用 config.txt 条目来设置热插拔检测，但在撰写本文时，这不适用于 KMS。 未来的固件版本可能会支持它。 config.txt 条目是 hdmi_force_hotplug，您可以使用 hdmi_force_hotplug:0=1 或 hdmi_force_hotplug:1=1 指定热插拔适用的特定 HDMI 端口。 请注意，KMS 的命名法将 HDMI 端口称为 1 和 2，而 Raspberry Pi 使用 0 和 1。

EDID问题
少数显示设备在关闭或选择了错误的 AV 输入时无法返回 EDID。 当 Raspberry Pi 和显示设备位于同一电源板上时，这可能会成为一个问题，并且 Raspberry Pi 设备的启动速度比显示器快。 对于此类设备，您可能需要手动提供 EDID。 更不寻常的是，某些显示设备的 EDID 块格式错误，KMS EDID 系统无法解析。 在这些情况下，可以从具有相似分辨率的设备读取 EDID 并使用它。 在任何一种情况下，以下说明都说明了如何从显示设备读取 EDID 并配置 KMS 以使用它，而不是 KMS 尝试直接询问设备。

将 EDID 复制到 file
创建一个 file 从头开始包含 EDID 元数据通常是不可行的，使用现有的元数据要容易得多。 一般可以从显示设备获取EDID，存储在树莓派的SD卡上，这样就可以被KMS使用，而不是从显示设备获取EDID。 此处最简单的选择是确保显示设备已启动并运行并使用正确的 AV 输入，并且 Raspberry Pi 已正确启动 HDMI 系统。 从终端，您现在可以将 EDID 复制到 file 使用以下命令：sudo cp /sys/class/drm/card?-HDMI-A-1/edid /lib/firmware/myedid.dat 如果由于某种原因 EDID 不存在，您可以在非- 成功启动到桌面或控制台的 KMS 模式，然后将固件将（希望）成功读取的 EDID 复制到 file.

1. 启动到传统图形模式。
   1. 编辑启动分区中的 config.txt，确保使用 sudo 运行编辑器，并将 dtoverlay=vc4-kms-v3d 行更改为#dtoverlay=vc4-kms-v3d。
   2. 重新启动。
2. 现在应该出现桌面或登录控制台。
   1. 使用终端，将 EDID 从连接的显示设备复制到 file 使用以下命令：

• tvservice -d myedid.dat 须藤 mv myedid.dat /lib/firmware/

使用 file基于 EDID 而不是询问显示设备 编辑 /boot/cmdline.txt，确保使用 sudo 运行编辑器，并将以下内容添加到内核命令行：具体的 HDMI 端口如下： drm.edid_firmware=HDMI-A-1:myedid.dat 如有必要，通过执行以下操作重新启动到 KMS 模式：

1. 在引导分区中编辑 config.txt，确保使用 sudo 运行编辑器，并将 #dtoverlay=vc4-kms-v3d 行更改为 dtoverlay=vc4-kms-v3d。
2. 重新启动。

笔记
如果你使用 file基于 EDID，但热插拔仍然存在问题，您可以通过在内核命令行中添加以下内容来强制热插拔检测：video=HDMI-A-1:D。

文件/资源

RaspberryPi KMS HDMI 输出图形驱动程序 [pdf] 用户手册 KMS, HDMI 输出显卡驱动, KMS HDMI 输出, 显卡驱动, KMS HDMI 输出显卡驱动, 驱动

参考

• 用户手册