modetest 命令详解：用 libdrm 模式测试工具验证 DRM/KMS 显示驱动（linux-command 速查手册）

• 文档
• 教程

modetest 是 libdrm 自带的 DRM/KMS（Direct Rendering Manager / Kernel Mode Setting）模式测试工具，用于枚举显示设备拓扑、设置显示模式、测试页面翻转与光标等驱动能力。本篇以 linux-command 仓库收录的 modetest 文档 为主体，结合仓库索引与构建方式，带你掌握 modetest 的编译安装、全部选项语义，以及如何在 MIPI-DSI 等显示设备上针对 Rockchip 等显卡驱动做实际测试。

一、modetest 是什么：DRM/KMS 与 libdrm

modetest是 libdrm 项目中的一个命令行工具，用于测试和验证 DRM 驱动程序的模式设置功能。它直接与内核 DRM 子系统的设备节点（如/dev/dri/card0）交互，通过 ioctl 完成对显示硬件的查询与配置，因此在嵌入式显示驱动开发、Bring-up 调试和显示适配验证场景中使用非常频繁。

DRM/KMS 体系把显示链路抽象为几个核心对象，modetest 的查询输出正是围绕它们展开：

• Connector（连接器）：物理显示接口，如 HDMI、DP、DSI、eDP，对应屏幕的接入状态；
• Encoder（编码器）：把像素数据编码为特定接口信号的单元，如 TMDS、DSI、Virtual；
• CRTC（显示器控制器）：负责把帧缓冲内容扫描输出到指定连接器，决定分辨率和刷新率；
• Plane（平面）：可独立叠加的显示层，用于主图层、光标层、视频层等；
• FB / Framebuffer（帧缓冲）：显存中保存一帧图像数据的内存对象。

在 linux-command 仓库中，modetest 被收录于 command/modetest.md，同时登记在命令索引 dist/data.json 中，索引描述为「DRM/KMS驱动程序libdrm中的模式测试工具」。仓库整体收录了 600 余条 Linux 命令（索引文件实际包含 617 条），modetest 属于其中面向显示与图形子系统调试的专项工具。

二、编译安装 libdrm 与 modetest

modetest 随 libdrm 一同构建，源码属于 Mesa 项目维护的 drm 仓库（官方发布物托管于 dri.freedesktop.org）。获得源码后即可按标准 autotools 流程编译。

以下为典型的交叉编译流程（示例目标平台为 aarch64，安装前缀为/opt）：

./configure --prefix=/opt/ --host=aarch64-linux-gnu make && make install ## 编译删除 make distclean

要点说明：

• --prefix=/opt/：指定安装目录，交叉编译产物默认不放入系统路径，便于后续打包进目标根文件系统；
• --host=aarch64-linux-gnu：声明目标主机三元组，配合交叉工具链使用，常见场景是 ARM 开发板上的显示驱动调试；
• make distclean：清除编译过程产生的全部临时文件与配置缓存，在需要重新配置构建参数时使用。

需要注意：modetest 需要访问 DRM 设备节点并取得 DRM Master 权限，实际运行时通常需要 root 权限或具有相应权限组的用户，下文示例的提示符~#也印证了这一点。

三、语法与选项全解

3.1 语法

modetest [选项]

不带任何选项运行时，modetest 会输出当前 DRM 设备上可枚举到的全部对象信息（编码器、连接器、CRTC、平面等），默认使用第一个 DRM 设备。

3.2 查询选项

这些选项用于只读地获取设备拓扑信息，是确认驱动枚举是否正常的第一步。

3.3 测试选项

其中两个核心参数串的字段含义如下：

• -s中<connector_id>是连接器 ID（可在-c输出中查到），@<crtc_id>指定使用哪个 CRTC，<mode>为分辨率（如1200x1920），-<vrefresh>可显式指定刷新率（如-60），@<format>指定像素格式（如XR24，即 XRGB8888）；
• -P中<plane_id>@<crtc_id>:<w>x<h>定义平面尺寸与位置，+<x>+<y>为屏幕坐标偏移，*<scale>为缩放比例，@<format>指定平面像素格式。

3.4 通用选项

-D在存在多个 DRM 设备（例如同时存在独立显卡与核显）时尤为有用；-a则用于验证原子提交路径下的模式切换行为。

四、-M <module>可指定的驱动模块

modetest的-M参数用于选择目标显卡驱动模块，常见取值及其对应的硬件平台如下：

嵌入式场景中，-M常与 SoC 厂商驱动配套使用，例如下文实战中的 Rockchip DSI 屏调试。

五、实战一：枚举显示设备拓扑

直接运行modetest，即可看到当前 DRM 设备完整对象列表（以下为典型输出节选，原文档中省略了大量模式行）：

~# modetest Encoders: # 省略了好多好多 id crtc type possible crtcs possible clones 194 0 Virtual 0x0000000f 0x00000001 196 88 TMDS 0x00000002 0x00000002 210 0 DSI 0x00000004 0x00000004 213 0 TMDS 0x00000001 0x00000008 Connectors: # 省略了好多好多 id encoder status name size (mm) modes encoders 197 196 connected HDMI-A-1 530x300 10 196 mode # 巴拉巴拉非常多的一大串 211 210 connected DSI-1 184x114 1 210 214 0 disconnected DP-1 0x0 0 213 CRTCs: # 省略了好多好多**** id fb pos size 68 0 (0,0) (0x0) 0 0 0 0 0 0 0 0 0 0 flags: ; type: 88 0 (0,0) (0x0) 0 0 0 0 0 0 0 0 0 0 flags: ; type: 108 219 (0,0) (1200x1920) 1200x1920 60 1200 1280 1284 1344 1920 1955 1956 1981 159400 flags: ; type: 128 0 (0,0) (0x0) 0 0 0 0 0 0 0 0 0 0 flags: ; type: Planes: # 省略了好多好多 id crtc fb CRTC x,y x,y gamma size possible crtcs 54 0 0 0,0 0,0 0 0x0000000f formats: XR24 AR24 XB24 AB24 RG24 BG24 RG16 BG16 NV12 NV21 NV16 NV61 NV24 NV42 NV15 NV20 NV30 YVYU VYUY YUYV UYVY 74 0 0 0,0 0,0 0 0x0000000f formats: XR24 AR24 XB24 AB24 RG24 BG24 RG16 BG16 NV12 NV21 NV16 NV61 NV24 NV42 NV15 NV20 NV30 YVYU VYUY YUYV UYVY 94 108 219 0,0 0,0 0 0x0000000f formats: XR24 AR24 XB24 AB24 RG24 BG24 RG16 BG16 NV12 NV21 NV16 NV61 NV24 NV42 NV15 NV20 NV30 YVYU VYUY YUYV UYVY

逐段解读：

• Encoders：crtc列表示该编码器当前绑定的 CRTC（0 表示未绑定），type是接口类型（Virtual/TMDS/DSI），possible crtcs与possible clones为位掩码，指示可与哪些 CRTC 配合、可与其他编码器克隆；
• Connectors：status区分connected/disconnected，size (mm)为物理尺寸，modes为支持的模式数量。本例中DSI-1（id 211）与HDMI-A-1（id 197）已连接，DP-1（id 214）未连接；
• CRTCs：fb为当前绑定的帧缓冲 ID，pos/size为位置与尺寸。CRTC 108 正在输出1200x1920@60Hz，其模型行（1200 1280 1284 1344 ... 159400）即为完整的 timing 参数（前/后沿、同步脉冲、像素时钟等）；
• Planes：possible crtcs位掩码标明平面可绑定的 CRTC，formats列出该平面支持的 DRM 像素格式 fourcc，如XR24（XRGB8888）、AR24（ARGB8888）、NV12/NV21（YUV420 半平面）等，可用于判断驱动是否支持目标格式。

六、实战二：在 MIPI-DSI 屏上测试 Rockchip 驱动

结合第五节枚举结果：连接器DSI-1（id 211）已连接、CRTC 108 支持1200x1920@60Hz，接下来就在这块 MIPI-DSI 屏幕上对 Rockchip 显卡驱动做模式测试。

6.1 垂直同步页面翻转测试（-v）

~# modetest -M rockchip -s 211@108:1200x1920 -v freq: 59.90Hz freq: 59.87Hz freq: 59.87Hz freq: 59.87Hz freq: 59.87Hz freq: 59.87Hz freq: 59.87Hz freq: 59.87Hz

命令拆解：-M rockchip指定 Rockchip 驱动；-s 211@108:1200x1920把连接器 211 绑定到 CRTC 108 并设置1200x1920模式；-v开启垂直同步页面翻转测试。输出的freq: 59.9xHz是每一轮 vblank 翻转的实际刷新频率，接近 60Hz 的标称值，说明翻转链路工作正常。

观察结果：在 MIPI 屏幕上会看到闪烁的彩色块——这是 modetest 在每次 vblank 时提交不同内容的帧缓冲形成的视觉效果，可用于直观确认驱动是否持续正常出图。

6.2 硬件光标测试（-C）

~# modetest -M rockchip -s 211@108:1200x1920 -C setting mode 1200x1920-60Hz@XR24 on connectors 211, crtc 108 starting cursor

命令拆解：-s完成模式设置（日志明确打印了1200x1920-60Hz@XR24的配置结果），-C随后启动硬件光标测试。starting cursor表示光标平面已启用，像素格式XR24即前面 Planeformats列表中的 XRGB8888。

观察结果：与-v不同，此时 MIPI 屏幕上会看到静止的彩色块，光标测试专注于验证硬件光标（cursor plane）的加载与显示，而非连续翻转。

七、在 linux-command 仓库中检索与复用本文档

modetest 是 linux-command 仓库 600 余条命令中的一员，除了通过 README.md 描述的 Web 站搜索使用外，还可以通过 npm 包以编程方式直接引用本文档内容：

npm install linux-command

var modetest = require("linux-command/command/modetest.md"); console.log(modetest); // 返回 modetest 命令的 Markdown 原文

同时，dist/data.json 提供全部命令的索引数据，其中modetest条目的描述为「DRM/KMS驱动程序libdrm中的模式测试工具」，路径为/modetest，可用于构建命令检索、速查表或自动化文档生成等场景。仓库中与显示相关的命令文档还包括 xrandr（X11 分辨率调整）、lspci（枚举显卡设备）等，可作为显示调试的配套参考。

八、使用注意事项

• 权限要求：modetest 需要打开 DRM 设备节点并成为 DRM Master，一般以 root 运行（示例提示符~#），或确保用户属于 video 等具备设备访问权限的用户组；
• 驱动匹配：-M指定的模块必须与内核实际加载的 DRM 驱动一致，否则枚举或模式设置会失败；多设备场景用-D明确指定/dev/dri/cardN；
• 原子模式：-a依赖驱动对 atomic KMS 的支持，老驱动或非原子路径下需去掉该选项改用传统 modeset 路径；
• 测试对象：-v与-C分别验证页面翻转和光标能力，是判断驱动中断（vblank）与 overlay 平面是否正常工作的快速手段，输出中的freq数值可直接用于核对刷新率是否达标。

综上，modetest 以极简的参数形态覆盖了 DRM/KMS 调试的查询、模式设置、翻转、光标与属性测试等核心场景，配合-M/-D/-a等通用选项，足以支撑嵌入式与桌面环境下显示驱动的快速验证，是图形栈工程师的高频工具之一。

• 文档
• 教程