第2章 搭建调试环境与工具准备
异常现象描述
在合成帧率异常排查中，若调试环境不完整，会出现以下症状：
- adb 连接失败：设备未识别、未授权或提示
device unauthorized。 - dumpsys SurfaceFlinger 吞日志：命令执行后卡住无输出，或返回
Can't find service: SurfaceFlinger。 - systrace 抓不到 SF 线程：Trace 中缺少
SurfaceFlinger或HWUI标签。 - Perfetto 配置文件加载失败：解析错误或缺少
ftrace权限。 - logcat 日志被截断：关键缓存溢出、进程重启导致日志丢失。
- dmesg 权限不足：非 root 设备无法直接读取内核环形缓冲区。
⚠️ 典型误区：误以为工具安装后即直接可用，忽略 Android 版本差异、CPU 架构和 SELinux 策略，导致数据采集失真。
排查思路
按照 工具链 → 权限 → 版本 → 输出验证 的递进顺序，逐层检查每个采集通道是否就绪。下图展示了调试各环节的依赖关系：
关键判断规则
| 工具/环节 | 可用判断条件 | 不可用根因 |
|---|---|---|
| adb devices | 输出存在 device 状态，非 unauthorized | 驱动缺失 / 授权弹窗未确认 / USB 调试未开 |
| adb shell dumpsys SurfaceFlinger | 命令 2s 内返回 Build fingerprint: ... 且含 HWC 信息 | SF 进程未运行 / selinux 阻止 dump / 权限不足 |
| systrace --list-categories | 输出包含 SurfaceFlinger 和 gfx | atrace 版本过旧 / kernel 不支持 ftrace |
| Perfetto 抓取 profile | 命令 perfetto --txt -c ... -o ... 正常结束且生成非空文件 | 未设置 persist.traced.enable=1 / data 分区空间不足 |
| logcat 缓冲区 | logcat -b events -d | grep SurfaceFlinger 有输出 | 日志轮转过快 / main 缓冲区太小 |
| dmesg 读取 | adb shell dmesg | grep "sf" 非空 | 非 root 且 sepolicy 限制 / 内核配置禁止访问 |
采集方法
- adb 环境搭建：从 SDK Platform Tools 下载最新 adb (≥ 30.0.5)，配置
~/.bashrc或系统 PATH。 - 确认设备模式：连接设备后执行
adb root，再adb remount（仅 userdebug 可用）。 - dumpsys SurfaceFlinger 最小数据采集：
adb shell dumpsys SurfaceFlinger --display-stat adb shell dumpsys SurfaceFlinger --latency - systrace 抓取（Python 工具，已弃用但兼容）：
python3 $ANDROID_HOME/platform-tools/systrace/systrace.py \ gfx input view SurfaceFlinger sched -t 10 -o trace.html - Perfetto 抓取（推荐）：
adb shell perfetto --txt -c /dev/stdin -o /data/misc/perfetto-traces/trace.perfetto-trace < - logcat 过滤规则：
adb logcat -v threadtime | grep -E "(SurfaceFlinger|HWC|HWUI|BufferQueue)" > log_sf.txt - dmesg 安全读取（非 root 可使用
adb shell dmesg仅缓存部分，推荐 root 后）：
💡 建议：将上述命令封装为 shell 脚本
collect_sf_data.sh，一次执行即可完成多路数据采集。
修复步骤
| 故障现象 | 修复动作 |
|---|---|
adb 设备显示 unauthorized |
在设备屏幕上确认 RSA 指纹；或执行 adb kill-server; adb start-server 后重新连接。 |
| dumpsys SurfaceFlinger 卡死 | 通过 adb shell setprop ctl.restart surfaceflinger 重启 SF；若仍有问题，检查 GPU 驱动是否异常。 |
| systrace 缺少 SF 标签 | 检查 kernel 版本：adb shell uname -r；需要 Linux ≥ 3.18 并开启 CONFIG_FTRACE；对于旧内核改用 Perfetto 的 trace:ftrace 数据源。 |
Perfetto 报错 Permission denied |
adb root；若失败则需刷入 eng 系统；或通过 adb shell setenforce 0 临时降低 SELinux。 |
| logcat 截断 | 增大缓冲区：adb logcat -G 32M；或使用 -b all -r 10240 -n 20 轮转输出。 |
| dmesg 无输出 | 确认 root 权限；若仍无则执行 echo 0 > /proc/sys/kernel/dmesg_restrict。 |
复测要点
- 连通性复测：执行
adb shell echo OK应返回OK，且无error: device offline。 - 工具输出完整性：每个工具产生文件大小至少大于 1KB，且内容包含预期关键字段（如
SF、HWC、frame-rate）。 - 性能影响：抓取期间使用
top观察traced进程 CPU 占用不超过 15%，否则调整缓冲区大小或降低采样频率。 - 跨版本兼容：在 Android 10/11/12/13 上分别运行全量命令，确保无版本差异导致的失败。
预防建议
- 版本锁定：将 adb、systrace、perfetto 的可执行文件放入项目专用的
tools/目录，避免系统路径变更。 - 环境检查脚本：编写
check_debug_env.sh，自动验证上述全部规则，并在 CI 前运行。 - 权限保留：在设备生命周期内保持
persist.sys.usb.config=adb和persist.traced.enable=1。 - 冗余采集：同时启用 systrace 和 Perfetto 互为备份；logcat 使用环形缓冲区 32MB，dmesg 结合
logd转发至 logcat。 - 文档化：为项目内每位调试人员提供 调试环境安装清单（附表格和命令），避免重复踩坑。