📚 课程目录第4章开发环境搭建

4、开发环境搭建：AOSP源码下载、编译环境配置、模拟器与真机调试工具的使用

Android Display HAL 与图形显示系统的开发，本质上是在 AOSP（Android Open Source Project）框架下进行系统级模块的修改、编译与验证。与普通应用开发不同，Display HAL 的改动直接影响 SurfaceFlinger、HWC（Hardware Composer）以及底层 DRM/KMS 驱动，任何错误都可能导致开机黑屏、画面撕裂或系统重启。因此，一套稳定、可复现的开发环境是开展工作的前提。本章将围绕 AOSP 源码获取、编译环境搭建、模拟器与真机调试三个核心环节展开，重点讲解 dumpsys SurfaceFlinger 与 systrace 在图形栈问题定位中的实战用法。

4.1 AOSP 源码下载：版本选择与仓库同步策略

核心原理：AOSP 采用 Git 多仓库管理，通过 repo 工具统一协调数百个独立 Git 仓库。Display HAL 相关代码主要位于 hardware/interfaces、hardware/libhardware、frameworks/native 以及设备厂商目录（如 device/google）。选择正确的分支至关重要——不同 Android 版本的 HAL 接口定义（如 IComposer 2.x/3.x/4.x）差异显著，错误的分支会导致编译失败或运行时接口不匹配。

操作流程：

安装 repo 工具：mkdir ~/bin && curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo && chmod a+x ~/bin/repo
初始化工作目录：mkdir aosp && cd aosp && repo init -u https://android.googlesource.com/platform/manifest -b android-13.0.0_r3
同步源码：repo sync -c -j8（-c 表示只同步当前分支，-j8 为并行任务数）

案例拆解：某团队需要开发基于 RK3588 平台的 Display HAL，选择了 android-12.0.0_r1 分支。同步过程中发现 device/rockchip 仓库缺失，原因是该仓库不在 AOSP 主线中，需单独添加 repo init -g all,-x86 或手动 git clone 厂商仓库。最终通过修改 .repo/local_manifests 添加私有仓库解决了问题。

风险提示：repo sync 耗时与网络环境强相关，国内开发者建议使用清华或中科大镜像源。磁盘空间不足是常见问题，AOSP 13 完整源码约 120GB，编译产物另需 150GB 以上。务必使用大小写敏感的文件系统（如 ext4），否则编译会报错。

4.2 编译环境配置：从 OpenJDK 到 lunch 选择

核心原理：AOSP 编译依赖特定版本的 JDK、Python 和系统库。Android 13 要求 OpenJDK 11，且必须使用 64 位 Linux 系统。编译系统通过 envsetup.sh 初始化环境变量，lunch 命令选择目标设备配置。对于 Display HAL 开发，通常选择 userdebug 版本，因为它允许 root 权限并保留调试工具。

关键配置清单：

配置项	推荐值	说明
操作系统	Ubuntu 20.04 LTS	官方支持，内核 ≥ 5.4
内存	≥ 32GB	16GB 可编译但容易 OOM
磁盘	≥ 500GB SSD	NVMe 速度提升明显
OpenJDK	11.0.x	sudo apt install openjdk-11-jdk
Python	3.8+	用于构建脚本
lunch 目标	aosp_arm64-userdebug	模拟器通用目标

操作流程：

# 安装依赖
sudo apt-get install git-core gnupg flex bison build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 libncurses5 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z1-dev libgl1-mesa-dev libxml2-utils xsltproc unzip fontconfig

# 初始化编译环境
source build/envsetup.sh
lunch aosp_arm64-userdebug

# 开始编译（首次建议 make -j4 避免内存溢出）
make -j$(nproc --ignore=2)

常见误区：很多初学者直接使用 make -j64 导致内存耗尽。编译 Display HAL 相关模块时，可以只编译指定模块以节省时间：make libhardware hwcomposer.ranchu。另外，修改 HAL 代码后无需全量编译，使用 mmm hardware/interfaces/display 即可增量编译。

4.3 模拟器与真机调试：adb 与 dumpsys SurfaceFlinger 实战

核心原理：模拟器（Emulator）使用 ranchu 作为虚拟硬件平台，其 Display HAL 实现为 hwcomposer.ranchu，基于 Goldfish 管道模拟。真机调试则依赖 adb（Android Debug Bridge）与设备通信。dumpsys SurfaceFlinger 是图形系统调试的核心工具，它输出所有 Layer 的状态、合成方式、帧率统计以及 HWC 配置信息。

调试工具对比：

工具	用途	关键命令
adb	设备连接、文件传输、shell	adb devices / adb shell / adb push
dumpsys SurfaceFlinger	查看 Layer 层级、合成状态、帧统计	dumpsys SurfaceFlinger --list
systrace	分析渲染管线耗时、vsync 对齐	systrace.py --trace gfx,view
dumpsys gfxinfo	应用帧渲染统计	dumpsys gfxinfo com.example.app

案例拆解：模拟器黑屏问题定位

某开发者在修改 Display HAL 后启动模拟器，出现黑屏但 adb 可连接。通过 adb shell dumpsys SurfaceFlinger 发现 Layer 列表为空，进一步检查 adb shell dumpsys display 显示 DisplayDevice 状态为 OFF。分析日志发现 hwcomposer.ranchu 的 presentDisplay 调用失败，原因是修改了 vsync 周期导致时序不匹配。回滚改动后恢复正常。

实战技巧：使用 adb shell dumpsys SurfaceFlinger --latency 可以查看每个 Layer 的帧时间戳，判断是否出现掉帧。若发现 janky 帧数增加，优先检查 HWC 合成路径是否被意外绕过（如强制 GPU 合成）。

4.4 systrace 与性能分析：捕捉渲染管线的瓶颈

核心原理：systrace 基于 Linux ftrace 和 Android atrace，能够记录内核与用户空间的耗时事件。在图形栈中，它主要追踪 Choreographer、SurfaceFlinger 的合成线程、HWC 的 present 调用以及 GPU 渲染任务。通过分析 systrace 可以定位是 CPU 渲染慢、GPU 等待还是 vsync 偏移导致卡顿。

操作流程：

# 抓取 10 秒 trace
python3 systrace.py --time=10 --trace=gfx,view,sched,idle -o trace.html

# 在浏览器中打开 trace.html，按 W 键放大，查看 SurfaceFlinger 线程
# 关注：VSYNC 信号、onFrameAvailable、queueBuffer、presentDisplay 等关键节点

案例拆解：帧率减半问题

某设备在开启 90Hz 刷新率后实际帧率只有 45Hz。通过 systrace 发现 SurfaceFlinger 的 onMessageReceived 每次间隔约 22ms，而 vsync 周期为 11ms。进一步分析发现 HWC 的 setPowerMode 调用耗时 8ms，阻塞了合成线程。优化方案是将 HWC 的电源管理操作异步化，最终帧率恢复至 90Hz。

经验总结：Display HAL 开发中，systrace 是验证 vsync 对齐和合成效率的黄金标准。建议在修改 HAL 前后各抓取一次 trace 进行对比，重点关注 SF 线程的 onMessageReceived 耗时和 HWC 的 present 调用间隔。

4.5 环境验证与常见问题复盘

核心原理：环境搭建完成后，必须通过一个最小验证流程确认工具链可用。推荐使用 adb shell dumpsys SurfaceFlinger 检查输出是否包含 HWC 2.0 或 Composer 相关字段，同时用 systrace 抓取一段 5 秒的 trace 确认无异常错误。

验证清单：

模拟器启动后 adb shell getprop ro.hardware 返回 ranchu
adb shell dumpsys SurfaceFlinger | grep -i "composer" 显示 HWC 版本
adb shell service list | grep display 确认 DisplayService 正常
编译产物 out/target/product/generic_arm64/ 包含 system.img 和 vendor.img

常见问题与解决方案：

现象	可能原因	解决方案
repo sync 中断	网络不稳定	使用 `repo sync -c --force-sync` 重试
编译报错 `No rule to make target`	缺少依赖模块	检查 `Android.bp` 中的 `deps` 字段
模拟器黑屏	HWC 初始化失败	查看 `logcat -s HWComposer` 日志
真机无法连接	USB 调试未开启	设置 → 开发者选项 → USB 调试

复盘总结：开发环境搭建的核心目标是建立“修改-编译-验证”的快速迭代闭环。建议将源码目录放在 SSD 上，并定期执行 make clean 避免增量编译的隐性错误。对于 Display HAL 开发，务必保留一份未修改的基线编译产物，以便在出现问题时快速对比。