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

4. 开发环境搭建

TF-M 的构建体系建立在 CMake 与 Kconfig 之上，并依赖 GNU Arm 工具链完成交叉编译。与普通裸机工程不同，TF-M 需要同时产出安全侧固件（Secure Processing Environment，SPE）与非安全侧应用（Non-secure Processing Environment，NSPE），二者通过 PSA 客户端接口与 IPC 或函数调用方式协作。因此，环境搭建的核心不是“装一个编译器”，而是把工具链、Python 依赖、源码仓库、构建配置四者对齐到同一版本基线。

一、核心原理：TF-M 构建系统的三层结构

TF-M 的构建可以理解为三层：最上层是 CMake 工程，负责组织目标、源文件与链接脚本；中间层是 Kconfig 配置系统，负责裁剪组件、选择平台与开关特性；最下层是工具链与 Python 脚本，负责编译、签名、镜像合并与测试生成。理解这三层，才能定位“编译失败”到底出在哪一层。

TF-M 源码通常由多个仓库组成：trusted-firmware-m 主仓库、tf-m-tests 测试仓库，以及平台相关的 HAL 仓库。主仓库通过 config 目录下的 Kconfig 文件描述所有可配置项，构建时由 CMake 调用 kconfiglib 生成 .config，再据此生成 config_defs.h 等头文件。因此，任何配置改动都应通过 Kconfig 或 CMake 变量完成，而不是直接改生成文件。

二、工具链与依赖准备

推荐使用 GNU Arm Embedded Toolchain 10.3 及以上版本，并确保 arm-none-eabi-gcc 在 PATH 中。Python 依赖由 TF-M 的 requirements.txt 管理，主要包括 cmake、kconfiglib、pycryptodome、cbor 等。建议使用虚拟环境隔离，避免污染系统 Python。

# 1. 创建并激活虚拟环境
python3 -m venv tfm-venv
source tfm-venv/bin/activate

# 2. 安装 TF-M 构建依赖
pip install -r trusted-firmware-m/tools/requirements.txt

# 3. 验证工具链
arm-none-eabi-gcc --version
cmake --version
ninja --version

若使用 Windows，建议在 WSL2 或 MSYS2 下构建；原生 Windows 对符号链接与路径长度较敏感，容易在 install 阶段报错。

三、源码获取与版本对齐

TF-M 主仓库与测试仓库需要版本匹配。推荐使用 git clone 后切换到同一 release 标签，例如 TF-Mv2.1.0。若平台 HAL 由芯片厂商提供，还需将其放入 platform/ext/target 对应目录，并确认 target_cfg.cmake 中的路径正确。

git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git
git clone https://git.trustedfirmware.org/TF-M/tf-m-tests.git
cd trusted-firmware-m
git checkout TF-Mv2.1.0
cd ../tf-m-tests
git checkout TF-Mv2.1.0

四、编译流程与关键参数

TF-M 的编译入口是 tools/cmake 下的 CMake 脚本。常用参数包括：TFM_PLATFORM 指定平台，TFM_TOOLCHAIN_FILE 指定工具链文件，TFM_BUILD_TESTS 控制是否编译测试，TFM_ISOLATION_LEVEL 选择隔离级别。首次构建建议先跑通默认配置，再逐步开启特性。

参数	含义	常用取值
TFM_PLATFORM	目标平台	arm/mps2/an521、stm/nucleo_l552ze_q
TFM_TOOLCHAIN_FILE	工具链描述文件	tools/cmake/toolchain/GNUArm.cmake
TFM_BUILD_TESTS	是否编译测试套件	ON / OFF
TFM_ISOLATION_LEVEL	安全分区隔离级别	1 / 2 / 3
CMAKE_BUILD_TYPE	构建类型	Debug / Release / MinSizeRel

cmake -G Ninja \
  -S trusted-firmware-m \
  -B build \
  -DTFM_PLATFORM=arm/mps2/an521 \
  -DTFM_TOOLCHAIN_FILE=tools/cmake/toolchain/GNUArm.cmake \
  -DTFM_BUILD_TESTS=ON \
  -DCMAKE_BUILD_TYPE=Debug

cmake --build build -- install

五、案例场景：从零构建 AN521 并运行测试

以 AN521 为例，完整流程为：准备工具链 → 克隆源码 → 配置 CMake → 编译 → 烧录 → 查看串口日志。若日志中出现 Booting TF-M 与 PSA API test PASSED，说明安全侧与非安全侧均已正常启动。若卡在 BL2 阶段，优先检查镜像签名与烧录地址是否匹配。

常见误区：直接修改 build 目录下的生成文件。这些文件在下次 CMake 配置时会被覆盖，正确做法是修改 Kconfig 或 CMake 变量后重新配置。

六、复盘与排障清单

工具链版本不匹配：确认 arm-none-eabi-gcc 版本与 TF-M 要求一致。
Python 依赖缺失：重新执行 pip install -r requirements.txt。
平台路径错误：检查 TFM_PLATFORM 是否与 platform/ext/target 下目录一致。
镜像未合并：确认 install 目标已执行，并检查 build/bin 输出。
烧录地址错误：对照平台链接脚本与烧录工具配置，确认 BL2、SPE、NSPE 的起始地址。

完成本节环境搭建后，应能稳定复现一次完整构建，并保留构建日志与配置快照。后续开发安全分区时，只需在既有构建基线上增加分区源文件与 Kconfig 选项，即可快速迭代。