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

4. 开发环境搭建

OP-TEE 的开发环境横跨 Normal World 与 Secure World 两个世界，涉及交叉编译工具链、OP-TEE OS（Secure World 内核）、OP-TEE Client（Normal World 用户态库与守护进程）、Linux 内核 TEE 驱动以及 QEMU 或真实开发板。环境搭建的核心目标，是让这五部分能够被同一套构建系统一致地编译、链接并运行起来。本章从工具链选择开始，逐步完成源码获取、环境配置、编译与烧录的完整闭环。

一、核心原理：为什么必须使用交叉编译工具链

OP-TEE OS 运行在 ARM TrustZone 的 Secure EL1（AArch64）或 Secure Supervisor（AArch32）异常级别，其代码不能使用宿主机的 x86_64 gcc 编译。因此必须使用目标架构的交叉编译器，把 C 源码编译成 ARM 指令。同时，OP-TEE 的构建系统（build.git）会同时编译多个组件，每个组件对工具链的要求并不相同：

OP-TEE OS：需要支持 -mgeneral-regs-only、-fno-stack-protector 等安全编译选项的裸机交叉编译器，通常使用 aarch64-linux-gnu- 或 arm-linux-gnueabihf-。
OP-TEE Client：运行在 Normal World 用户态，需要带 glibc 的交叉工具链，并链接 libteec 与 tee-supplicant。
Linux 内核与 TEE 驱动：需要与内核版本匹配的交叉编译器，并保证 CONFIG_TEE、CONFIG_OPTEE 已开启。
QEMU 或开发板：QEMU 使用 qemu-system-aarch64 模拟 ARMv8，真实开发板则依赖厂商提供的 BSP 与烧录工具。

工具链版本不一致是环境搭建中最常见的失败原因。建议统一使用 Linaro 或 Arm 官方发布的 GCC 工具链，并在构建前通过 --version 确认版本。

二、源码获取与目录结构

OP-TEE 官方推荐使用 repo 管理多仓库源码。repo 清单文件 default.xml 会同时拉取 optee_os、optee_client、optee_test、linux、build、qemu 等仓库，保证各组件版本互相兼容。

# 安装 repo 工具
mkdir -p ~/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
export PATH=~/bin:$PATH

# 初始化并同步源码（以 4.0.0 版本为例）
mkdir -p ~/optee && cd ~/optee
repo init -u https://github.com/OP-TEE/manifest.git -m qemu_v8.xml -b 4.0.0
repo sync -j4

# 安装构建依赖
cd build
make -f toolchain.mk toolchains

同步完成后，顶层目录下会出现 optee_os/、optee_client/、optee_test/、linux/、build/、qemu/ 等子目录。其中 build/ 是构建入口，qemu_v8.mk 定义了 QEMU 平台的编译与运行规则。

三、QEMU 与真实开发板环境配置

QEMU 环境适合快速验证 OP-TEE 功能，无需硬件即可运行完整的安全世界与普通世界。真实开发板（如 STM32MP157、i.MX8、RK3399）则更接近量产场景，但需要额外处理 U-Boot、设备树与烧录。

对比项	QEMU 环境	真实开发板
硬件依赖	无，纯软件模拟	需要开发板、串口线、烧录器
启动方式	直接运行 `make run`	U-Boot 加载 TF-A、OP-TEE、Linux
调试手段	GDB + QEMU 单步	JTAG/SWD + 串口日志
适用阶段	功能验证、CI 自动化	性能测试、驱动适配、量产验证
典型命令	`make run-only`	`fastboot flash` / `STM32CubeProgrammer`

QEMU 环境配置的关键是确认 qemu_v8.mk 中的 QEMU_PATH 与 QEMU_BIN 指向正确，并保证 qemu-system-aarch64 已加入 PATH。真实开发板则需要把编译产物 tee-header_v2.bin、tee-pager_v2.bin、tee-pageable_v2.bin 与 bl32.bin 按厂商要求打包进 FIP 或直接烧录到指定分区。

四、编译与烧录流程

OP-TEE 的编译分为“全量编译”和“单组件编译”两种方式。全量编译由 build/ 目录统一驱动，适合首次搭建；单组件编译适合日常开发调试。

# 全量编译 QEMU 环境
cd ~/optee/build
make -j$(nproc) all

# 仅编译 OP-TEE OS
make -C optee_os \
  CROSS_COMPILE=aarch64-linux-gnu- \
  PLATFORM=vexpress-qemu_armv8a \
  O=out/arm

# 仅编译 OP-TEE Client
make -C optee_client \
  CROSS_COMPILE=aarch64-linux-gnu- \
  O=out/arm

# 启动 QEMU
make run-only

编译成功后，out/arm/ 下会生成 tee.bin、libteec.so、tee-supplicant 等产物。QEMU 启动后，串口会依次打印 TF-A、OP-TEE OS、Linux 内核日志，最后进入 Normal World 的 shell。此时可运行 xtest 验证 TEE 功能是否正常。

提示：首次编译建议使用 make -j$(nproc) 加速，但若出现内存不足，可降低并行度至 -j2。编译 OP-TEE OS 时若报 undefined reference to __stack_chk_fail，说明工具链默认开启了栈保护，需在 CFLAGS 中追加 -fno-stack-protector。

五、误区与复盘

环境搭建阶段最容易踩的坑集中在工具链、版本与权限三方面：

工具链混用：用 arm-linux-gnueabihf- 编译 AArch64 的 OP-TEE OS，会直接报架构不匹配。务必确认 CROSS_COMPILE 与 PLATFORM 对应。
repo 分支不一致：optee_os 与 optee_client 版本差异过大，会导致 TA 加载失败或 TEEC_ERROR_BAD_PARAMETERS。
QEMU 未安装：make run-only 报 qemu-system-aarch64: command not found，需先安装 QEMU 或使用 build 提供的工具链脚本。
烧录分区错误：真实开发板把 bl32.bin 烧到错误分区，会导致 Secure World 无法启动，串口无 OP-TEE 日志。

注意：真实开发板烧录前务必确认分区表与厂商文档一致，并保留原始固件备份。一旦烧录错误分区，可能导致设备无法启动，需要借助恢复模式重新刷写。

完成本章环境搭建后，你已经具备编译、运行和调试 OP-TEE 的最小闭环。后续章节将在此基础上，深入 OP-TEE Client 的 API 使用与安全通信机制。