在 Linux 显示故障排查中，很多问题很难复现。

尤其是内置 eDP 屏幕偶发出现黑屏、白屏、绿屏时，如果每次都依赖“重新启动系统看看会不会发生”，不仅效率很低，而且同时改变了太多变量：

Firmware
→ Bootloader
→ Kernel
→ DRM/i915
→ Display Manager
→ Wayland/X11
→ Desktop

很难判断究竟是哪一层导致了故障。

一次实际排查中采用了一种非常有效的方法：

在已经完全正常运行的 KDE Plasma Wayland 桌面中，主动关闭内置显示器，等待指定时间，再重新打开。

通过改变这个等待时间，最终直接找到了 eDP 面板的临界恢复时间，并把问题锁定到了 Panel Power Cycle Timing。

这是一种非常值得记录的显示器测试方法。

---

一、问题为什么难以定位

故障表现为内置屏幕偶发进入：

黑屏
白屏
绿屏

奇怪的是，即使物理屏幕已经明显异常，Linux DRM/i915 日志仍可能显示：

Clock recovery OK
Channel EQ done
DP Training successful
Link Training passed
Pipe enabled
Backlight enabled

也就是说：

GPU 认为显示器正常

但：

人眼看到的面板明显不正常

这是一个非常关键的矛盾。

它说明不能简单依赖：

DP link training 成功

来判断物理面板已经真正恢复。

---

二、传统重启测试的问题

最初可以通过反复重启观察：

Firmware
→ Linux
→ 登录界面
→ Plasma

期间是否出现故障。

但这种方法有一个严重缺点：

每次重启都同时改变大量状态。

例如一次异常可能涉及：

Firmware framebuffer handoff
i915 modeset
eDP link training
Panel Power Sequencing
SDDM
Xorg
Wayland
KWin

如果只知道：

“这次启动黑屏了”

实际上几乎无法判断真正的触发条件。

因此需要设计一个实验，把其他因素全部固定，只改变一个变量。

---

三、关键思路：在正常 Plasma 中重新关开屏幕

KDE Plasma 提供了：

kscreen-doctor

可以直接控制显示输出的 DPMS 状态。

最基本的测试：

kscreen-doctor --dpms off
sleep 2
kscreen-doctor --dpms on

含义是：

关闭显示器
↓
等待 2 秒
↓
重新开启显示器

这条命令最大的价值在于：

它可以在一个已经完全正常运行的桌面中重新触发显示器电源状态转换。

因此不再需要：

重新启动 Linux
重新经过 GRUB
重新经过 SDDM
重新登录 Plasma

实验环境变成：

正常运行的 Plasma Wayland
        ↓
只改变 DPMS OFF → ON 的等待时间

变量一下子被压缩到了一个。

---

四、这只是关闭视频信号吗？

这是这个实验最有意思的地方。

表面上：

kscreen-doctor --dpms off

很容易被理解成：

暂停输出视频信号。

但结合 i915 DRM debug 日志，可以看到在目标系统中实际发生了更完整的流程。

大致过程为：

DPMS OFF
   ↓
Backlight Off
   ↓
Display Pipe / Transcoder Disable
   ↓
eDP Panel Power Off
   ↓
等待

重新开启时：

DPMS ON
   ↓
Panel Power On
   ↓
等待 Panel Power-Up
   ↓
AUX / DPCD 通信
   ↓
重新进行 DP Link Training
   ↓
Pipe Enable
   ↓
Backlight On

所以在这个实际环境中，DPMS off/on 并不只是简单地“停止和恢复视频流”。

从 Linux/i915 驱动层面看，它触发的是：

完整的 eDP Panel Power Cycle。

严格来说，如果要证明 LCD 模组内部每一条物理供电轨都真正下降到 0 V，需要示波器或硬件测量。

但对于 Linux 显示驱动故障诊断来说，日志已经明确证明 PPS 执行了：

Panel Power Off
→
Panel Power On

因此工程层面完全可以把这个实验视为一次面板断电再上电测试。

---

五、开始改变唯一变量：等待时间

既然怀疑的是：

Panel Power Off
→
Panel Power On

之间的时间过短，那么最直接的实验就是修改：

sleep N

---

0.5 秒

kscreen-doctor --dpms off
sleep 0.5
kscreen-doctor --dpms on

结果：

FAIL

可以复现黑屏。

部分异常状态还可能继续向绿色区域发展。

---

1 秒

kscreen-doctor --dpms off
sleep 1
kscreen-doctor --dpms on

结果仍然可能：

FAIL

出现黑屏。

这说明：

1 秒仍然不足以保证可靠恢复

---

2 秒

kscreen-doctor --dpms off
sleep 2
kscreen-doctor --dpms on

结果发生明显变化。

经过连续测试：

20 / 20 PASS

---

3 秒

kscreen-doctor --dpms off
sleep 3
kscreen-doctor --dpms on

同样：

20 / 20 PASS

---

5 秒

kscreen-doctor --dpms off
sleep 5
kscreen-doctor --dpms on

正常。

---

六、实验结果非常有辨识度

最终得到：

OFF → ON 等待时间	结果
0.5 s	可复现故障
1.0 s	可复现故障
2.0 s	20/20 PASS
3.0 s	20/20 PASS
5.0 s	正常

这种结果比单纯“修改某个参数后好像稳定了”强得多。

因为它存在非常明显的：

时间阈值关系

也就是说：

短
→
容易失败

足够长
→
稳定恢复

---

七、为什么这个实验具有很强的因果意义

因为测试是在：

系统已经启动
Plasma 已经正常运行
Wayland 已经建立
KWin 正常工作
显示器当前也是正常的

条件下进行的。

因此如果此时执行：

DPMS off
↓
等待 0.5 秒
↓
DPMS on

就能再次复现和启动时相同的黑屏，那么以下组件就都不再是故障发生的必要条件：

Firmware boot
GRUB
Kernel boot process
SDDM
Xorg
X11 → Wayland handoff
用户登录

因为这些步骤根本没有重新发生。

剩下的共同变量只有：

eDP Panel Power Off
↓
等待
↓
Panel Power On

这是一个非常典型的“控制变量”排错方法。

---

八、再读取 i915 实际使用的 PPS 参数

Intel i915 可以通过 debugfs 暴露当前 eDP Panel Power Sequencing 参数。

路径形式：

/sys/kernel/debug/dri/<DRM-device>/eDP-1/i915_panel_timings

例如：

sudo cat \
    /sys/kernel/debug/dri/<DRM-device>/eDP-1/i915_panel_timings

故障修复前得到：

Panel power up delay: 200
Panel power down delay: 60
Panel power cycle delay: 500
Backlight on delay: 1
Backlight off delay: 200

其中最值得注意的是：

Panel power cycle delay: 500

也就是：

500 ms

而实际实验结果恰好是：

0.5 秒 → FAIL
1 秒   → FAIL
2 秒   → PASS

这就把：

实际行为

和：

驱动配置

直接联系起来了。

---

九、什么是 Panel Power Cycle Delay

它并不是简单的：

屏幕关闭多久

而是 Panel Power Sequencing 中：

上一次面板断电后，在允许下一次重新上电之前必须满足的最小时间。

可以简单理解为：

Panel Power Off
        ↓
必须等待至少 T
        ↓
Panel Power On

原驱动实际使用：

T = 500 ms

而实际面板表现说明：

500 ms 太短
1 s 仍不够可靠
2 s 开始稳定

---

十、为什么驱动仍然会显示 Link Training Successful

这里也是整个实验中很有意思的一点。

面板发生故障时，i915 可能依然完成：

AUX communication
Clock Recovery
Channel Equalization
DP Link Training

于是软件得到：

DP Training successful

但面板内部状态机可能没有从掉电状态正确恢复。

因此存在：

GPU / eDP link
        =
正常

Panel internal state
        =
异常

也就是说：

DisplayPort 链路工作，并不等价于 LCD 面板内部所有电源和显示状态都已经正确初始化。

这解释了为什么软件日志看起来完全正常，而肉眼却看到黑屏甚至绿屏。

---

十一、连续测试脚本

确定 2 秒稳定后，可以做简单的连续循环：

for i in $(seq 1 20); do
    echo "===== TEST $i / 20 ====="

    kscreen-doctor --dpms off
    sleep 2
    kscreen-doctor --dpms on

    sleep 5
done

其中：

sleep 2

是被测试的 Panel OFF → ON 间隔。

后面的：

sleep 5

只是为了：

• 等待桌面完全恢复；
• 留出人工观察时间；
• 避免连续操作过快。

它不是 PPS 参数的一部分。

---

十二、通过 SSH 执行 Wayland DPMS 测试

如果测试不是从当前 Plasma Terminal 直接执行，而是通过 SSH 进入机器，那么通常需要显式连接到已经存在的 Wayland session。

先检查：

systemctl --user show-environment |
    grep -E '^(DISPLAY|WAYLAND_DISPLAY|XDG_CURRENT_DESKTOP|XDG_SESSION_TYPE)='

还可以查看 Wayland socket：

ls -l "$XDG_RUNTIME_DIR"/wayland-*

然后按照实际环境传递：

QT_QPA_PLATFORM
WAYLAND_DISPLAY
DISPLAY
XDG_RUNTIME_DIR
DBUS_SESSION_BUS_ADDRESS

例如通用形式：

env \
    QT_QPA_PLATFORM=wayland \
    WAYLAND_DISPLAY=<wayland-socket> \
    DISPLAY=<xwayland-display> \
    XDG_RUNTIME_DIR=<runtime-dir> \
    DBUS_SESSION_BUS_ADDRESS=<session-bus> \
    kscreen-doctor --dpms off

等待：

sleep 2

再执行：

env \
    QT_QPA_PLATFORM=wayland \
    WAYLAND_DISPLAY=<wayland-socket> \
    DISPLAY=<xwayland-display> \
    XDG_RUNTIME_DIR=<runtime-dir> \
    DBUS_SESSION_BUS_ADDRESS=<session-bus> \
    kscreen-doctor --dpms on

这些值必须从当前机器实时读取，不应把某台机器的用户 ID、socket 名称等直接写死到通用文档中。

---

十三、旧 X11 环境中的类似测试

在 X11 登录界面中，也曾使用：

xrandr --output eDP-1 --off
sleep 2
xrandr --output eDP-1 --auto

一次异常白屏状态下，这种重新 modeset 曾让登录界面暂时恢复。

但之后登录仍可能再次出现异常。

因此：

xrandr off/on

可以作为诊断工具，却不应被理解成修复方案。

它证明的是：

再次执行显示输出重置能够改变物理面板状态。

---

十四、最终把 2000 ms 写进 i915

实验结果最终促成了驱动修改。

源码：

drivers/gpu/drm/i915/display/intel_pps.c

原逻辑：

intel_dp->pps.panel_power_cycle_delay =
        pps_units_to_msecs(final->power_cycle);

增加最低限制：

intel_dp->pps.panel_power_cycle_delay =
        max(intel_dp->pps.panel_power_cycle_delay, 2000);

于是：

固件要求 500 ms
→
实际使用 2000 ms

但如果某块面板原本要求：

2500 ms

仍然保留：

2500 ms

---

十五、补丁后的验证

重新加载自定义 i915 后：

sudo cat \
    /sys/kernel/debug/dri/<DRM-device>/eDP-1/i915_panel_timings

变成：

Panel power up delay: 200
Panel power down delay: 60
Panel power cycle delay: 2000
Backlight on delay: 1
Backlight off delay: 200

此后启动过程中可以肉眼观察到：

第一次约 2 秒黑屏
第二次约 2 秒黑屏

这反而是一个很好的现象。

它表明：

Panel Power Cycle minimum = 2000 ms

确实已经参与实际启动流程。

随后显示器能够可靠恢复。

---

十六、测试中的安全原则

这种实验涉及真实的显示面板电源状态转换，不适合无限制压力测试。

尤其已经知道：

0.5 s
1 s

会触发异常后，就没有必要反复重现。

推荐原则：

绿屏
→
立即关机

持续黑屏 / 白屏
→
尽快结束测试

已经确认危险的短时间间隔
→
不再重复

验证修复时，应优先使用：

2 秒或更长

的已知安全范围。

---

十七、这套测试方法最大的价值

整个排查中，最有效的并不是某个日志参数，而是实验设计。

最初的问题是：

启动时偶发黑屏

这包含几十个变量。

后来把实验变成：

系统完全正常
↓
DPMS OFF
↓
等待 N 秒
↓
DPMS ON

于是只剩一个变量：

N

再得到：

N = 0.5 → FAIL
N = 1   → FAIL
N = 2   → PASS
N = 3   → PASS

最后又发现驱动恰好配置：

Panel power cycle delay = 500 ms

整个证据链因此闭合：

可重复的物理故障
        ↓
控制变量实验
        ↓
发现明确时间阈值
        ↓
驱动参数正好等于危险区间
        ↓
修改为安全时间
        ↓
故障消失

---

十八、结论

对于某些非常特殊的 Linux 内屏故障，下面这三条命令可能比反复重启系统更有诊断价值：

kscreen-doctor --dpms off
sleep 2
kscreen-doctor --dpms on

再结合：

sudo cat \
    /sys/kernel/debug/dri/<DRM-device>/eDP-1/i915_panel_timings

可以直接研究：

eDP Panel Power Sequencing

而不仅仅是：

分辨率
刷新率
Link Training
Wayland
Xorg

这次案例最终证明：

故障与 eDP Panel Power Cycle 间隔直接相关。默认约 500 ms 的等待时间不足，而将最低间隔提高到 2000 ms 后，面板能够稳定完成重新上电和初始化。

更重要的是，这种测试方式把一个原本只能“碰运气重启复现”的问题，转化成了一个：

可以控制
可以重复
可以量化
可以验证

的实验。

这往往才是复杂硬件故障真正开始变得可解的时刻。