4. dumpsys SurfaceFlinger 采集帧率信息
在 Android 图形系统中，dumpsys SurfaceFlinger 是诊断帧率抖动、卡顿、丢帧的核心工具。它直接读取 SurfaceFlinger 内部维护的帧完成时间戳队列与合成统计数据，无需 root 即可在 userdebug/eng 版本上获取精确的逐帧延迟与丢帧计数。本章将深入讲解命令使用、关键字段含义、帧耗时分布分析方法以及丢帧计数解读，帮助开发者从原始数据中快速定位帧率不稳定的根因。
4.1 命令使用与基本参数
基础命令（无需参数）：
adb shell dumpsys SurfaceFlinger输出量巨大，通常需要追加过滤参数只保留帧率相关数据。最常用的选项：
| 参数 | 作用 | 示例 |
|---|---|---|
| --latency <layer> | 输出指定图层的帧时间戳序列（128个历史帧） | --latency SurfaceView |
| --list | 列出所有可见图层 | --list |
| --displays | 显示显示设备属性及刷新率 | --displays |
| --frame-stats | 输出全局帧统计信息（Android 11+） | --frame-stats |
实用技巧：重复执行
dumpsys SurfaceFlinger --latency "StatusBar" 并观察时间戳趋势，可以实时检测一帧从 Choreographer 回调到 SurfaceFlinger 合成完成的端到端延迟。建议配合 | grep -E "Refresh|Frame|jank|missed" 快速过滤关键行。
4.2 关键字段解析
以 --latency 输出为例，原始数据格式如下：
RefreshPeriod: 16666666
NumFrames: 128
FrameTimestamps:
0: 13104419441979 13104419441979 13104437990893
1: 13104419458646 13104419458646 13104439657480
...
124: 13104445732114 13104445732114 13104464281349
125: 13104445431981 13104445431981 13104463981249每一行包含三个 64 位时间戳（单位：纳秒）：
| 列序 | 字段名 | 含义 |
|---|---|---|
| 1 | DesiredPresentTime | 应用期望该帧被呈现的时间（通常由 Choreographer 的 vsync 对齐决定） |
| 2 | ActualPresentTime | 该帧实际被 SurfaceFlinger 合成并提交到 HWComposer 的时间 |
| 3 | FrameReadyTime | 该帧所有缓冲区内容准备就绪（GPU 渲染完成）的时间 |
注意：当 ActualPresentTime = 0 时，表示该帧已经被丢弃（早期弃帧），是判断丢帧最直接的依据。数值类型的 0 不代表时间起点，而是无效标志。
RefreshPeriod 表示屏幕两次硬件 vsync 之间的间隔，单位纳秒。例如 16666666 ns ≈ 16.67 ms，对应 60 fps 刷新率；8333333 ns 对应 120 fps。
4.3 帧耗时分布计算
通过三个时间戳可以推导出三个关键耗时：
- 渲染耗时（Render Duration）：
FrameReadyTime - DesiredPresentTime。代表 CPU/GPU 从收到 Choreographer 回调到渲染完毕的耗时。如果远大于 vsync 周期，会引发丢帧。 - 合成耗时（Composition Duration）：
ActualPresentTime - FrameReadyTime。表示 SurfaceFlinger 合成以及等待 HWC 返回的耗时。正常值应在 2~5 ms 以内。 - 总延迟（Total Latency）：
ActualPresentTime - DesiredPresentTime。端到端帧呈现延迟。
批量计算时，通常关注相邻帧的 ActualPresentTime 差值是否稳定。如果某帧间隔超过 RefreshPeriod + 1ms，则认为是丢帧。
4.4 丢帧计数（Jank & Missed Deadline）
SurfaceFlinger 除了提供时间戳外，还会在全局帧统计中记录丢帧次数。使用 --frame-stats 可以获取：
adb shell dumpsys SurfaceFlinger --frame-stats
Total frames rendered since boot: 48291
Janky frames: 237
Jank ratio: 0.49%
Missed deadlines: 89
Missed deadline ratio: 0.18%字段解析：
| 字段 | 说明 |
|---|---|
| Total frames rendered | 自启动以来 SurfaceFlinger 处理的总帧数 |
| Janky frames | 被判定为卡顿的帧数（帧间隔 > 2 个 vsync） |
| Jank ratio | 卡顿帧占比 |
| Missed deadlines | 未能在期望 vsync 窗口内完成的帧数 |
| Missed deadline ratio | 丢截止帧占比 |
常见误解：Janky frames 与 Missed deadlines 并不完全等价。前者侧重帧时长突增（长于 2 个 vsync），后者侧重 vsync 对齐失败。在 game 场景下两者往往同时增加，但在 UI 动画场景中可能只有 Missed deadlines 上升。
4.5 实战：从命令输出到丢帧提取
以下是一个完整的采集与分析流程脚本（sh 片段）：
#!/system/bin/sh
# 采集 5 秒帧时间戳
dumpsys SurfaceFlinger --latency "SurfaceView" > /data/local/tmp/latency_5s.txt
# 提取 ActualPresentTime 列，计算帧间隔
awk 'NR>1 && NF==3 {print $2}' /data/local/tmp/latency_5s.txt \
| while read t
do
if [ -n "$prev" ]; then
delta=$(( t - prev ))
# 16.67ms vsync 周期，允许 1ms 误差
if [ $delta -gt 17666666 ]; then
echo "Jank detected: delta=$delta ns"
fi
fi
prev=$t
done运行输出示例：
Jank detected: delta=33333333 ns
Jank detected: delta=25000000 ns
Total frames sampled: 299
Janky frames: 24.6 调试与部署建议
- 持续采集：在自动化测试中，使用
dumpsys SurfaceFlinger --frame-stats每 10 秒写入日志，配合logcat -b events | grep "jank"交叉验证。 - 非 root 设备：部分厂商限制
--latency权限，可尝试dumpsys SurfaceFlinger --displays获取 RefreshPeriod 后，仅统计帧完成数来估算帧率。 - 批处理工具：推荐使用 Python 解析时间戳文件，计算 DFPS（delivered frames per second）和 Jank rate。
4.7 常见错误与排查
| 错误现象 | 原因 | 解决方法 |
|---|---|---|
--latency 输出全零 |
图层名称拼写错误或该图层未加入 SurfaceFlinger 的可见列表 | 先用 --list 确认正确的图层名，支持通配符 |
| RefreshPeriod 为 0 | 设备显示服务异常或未初始化，多见于模拟器 | 重启 SurfaceFlinger 或切换为真实设备 |
| 每秒采集帧数远低于预期 | adb shell 到设备的 USB 延迟导致采样窗口不准 | 使用 adb shell 本地执行脚本并重定向输出到文件 |
4.8 性能优化导向：利用丢帧数据定位瓶颈
通过分析 --latency 时间戳分布，可以快速区分三种丢帧类型：
- CPU/GPU 渲染过重：绝大多数丢帧的
FrameReadyTime远大于DesiredPresentTime，且ActualPresentTime跟随推后。 - SurfaceFlinger 合成过载：
FrameReadyTime正常，但ActualPresentTime延迟，说明合成线程或 HWC 队列拥堵。 - 外因抢占（例如温控降频）：丢帧模式呈集群出现，且伴随 CPU 频率下降日志。
将丢帧计数与帧耗时结合，可以给系统优化提供明确指标：若 Jank ratio > 1%，优先优化渲染耗时；若 Missed deadline ratio > 0.5%，则需检查 vsync 调度和 HWC 配置。