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

4. 开发环境搭建

Jailhouse 是一个运行在裸机之上的静态分区 Hypervisor，它并不依赖 Linux 内核的虚拟化扩展来调度客户机，而是把物理 CPU 核、内存区域、中断控制器和外设直接“切分”给不同的 Cell。这种“静态划分”的特性决定了它对开发环境有比较特殊的要求：编译产物必须与目标硬件的架构、页表粒度、中断控制器版本严格匹配，任何一处工具链或内核源码版本不一致，都可能在启动阶段表现为难以定位的挂死或异常。因此，本章把环境搭建视为移植工作的第一道工程关口，而不是简单的“装几个包”。

4.1 环境搭建的核心原理

Jailhouse 的构建过程可以拆成三条相互独立的产物链：第一条是 交叉编译工具链，负责把 C 源码编译成目标架构的机器码；第二条是 Linux 内核源码，Jailhouse 需要从内核头文件中获取体系结构相关的定义，并在运行时以内核模块 jailhouse.ko 的形式加载；第三条是 Jailhouse 自身源码，它同时包含 Hypervisor 二进制、 inmate 示例和用户态工具 jailhouse。这三条链最终在目标板上汇合，任何一条版本错位都会导致“编译通过但运行失败”。

理解这一点后，环境搭建的目标就非常明确：让工具链、内核源码、Jailhouse 源码三者的版本与目标硬件平台形成可复现的对应关系。推荐使用与目标板 BSP 一致的内核源码树，而不是随意下载主线内核，因为 Jailhouse 的 configs/ 目录中已经为若干开发板预置了配置，这些配置往往依赖特定内核版本的结构体布局。

4.2 方法流程：从零到可运行

推荐按以下顺序推进，每一步都保留可回退的检查点。第一步安装依赖包，第二步准备交叉编译工具链，第三步获取并准备内核源码，第四步获取 Jailhouse 源码并配置，第五步选择 QEMU 或真实硬件进行验证。

# 1. 安装构建依赖（以 Ubuntu 为例）
sudo apt update
sudo apt install -y git build-essential flex bison \
    libssl-dev libncurses-dev bc rsync \
    gcc-aarch64-linux-gnu \
    qemu-system-arm qemu-system-x86

# 2. 验证交叉编译器
aarch64-linux-gnu-gcc --version

# 3. 获取 Jailhouse 源码
git clone https://github.com/siemens/jailhouse.git
cd jailhouse
git checkout v0.12   # 选择与目标板匹配的稳定分支

# 4. 准备内核源码（版本需与目标板 BSP 一致）
git clone --depth 1 -b v5.10 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git

完成源码准备后，进入 Jailhouse 目录执行配置。关键参数是 ARCH 与 CROSS_COMPILE，它们决定了后续所有编译动作的目标架构。若使用 QEMU 验证，可直接选用 configs/qemu-arm64.c 或 configs/qemu-x86.c；若使用真实硬件，则应选择与开发板对应的配置文件，例如 configs/arm64/ 下的板级配置。

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- \
     KDIR=../linux KERNEL_ARCH=arm64 \
     clean
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- \
     KDIR=../linux KERNEL_ARCH=arm64

4.3 依赖清单与版本对应

下表汇总了环境搭建中最容易出问题的依赖项及其检查方式。建议在正式编译前逐项确认，避免在运行阶段才发现版本不匹配。

依赖项	作用	检查命令	常见问题
交叉编译工具链	生成目标架构机器码	`aarch64-linux-gnu-gcc -v`	前缀与 ARCH 不匹配
Linux 内核源码	提供头文件与模块编译环境	`make -C $KDIR kernelrelease`	版本与 BSP 不一致
Jailhouse 源码	Hypervisor 与工具本体	`git describe --tags`	分支过新导致配置缺失
QEMU	无硬件时的快速验证	`qemu-system-aarch64 --version`	缺少虚拟化或 GIC 支持
设备树 / 板级配置	描述硬件资源划分	`ls configs/arm64/`	内存区域与实物不符

4.4 案例场景：QEMU 与真实硬件的取舍

在移植初期，建议优先使用 QEMU 验证构建链路是否通畅。QEMU 的优势是启动快、可反复重启、便于观察串口日志，适合验证 Hypervisor 能否正常启用、Root Cell 能否创建。但 QEMU 无法完全模拟真实硬件的中断路由、时钟和内存映射，因此最终必须回到真实开发板上验证。

一个典型的踩坑场景是：在 QEMU 上一切正常，但烧录到开发板后卡在 jailhouse enable。原因往往是板级配置中的内存区域与实物不一致，或者内核源码版本与 BSP 存在差异，导致 jailhouse.ko 加载后符号解析异常。此时应回到 4.3 的清单逐项核对，而不是盲目修改 Hypervisor 代码。

常见误区：直接使用主线最新内核源码编译 Jailhouse 模块。Jailhouse 的部分代码依赖内核内部结构体布局，主线内核的频繁变更可能导致编译失败或运行时崩溃。务必使用与目标板 BSP 一致的内核版本。

实用建议：为每个目标平台建立独立的环境目录，例如 env/qemu-arm64/ 与 env/board-a/，分别保存工具链、内核源码和 Jailhouse 配置。这样可以在多个平台之间快速切换，避免版本污染。

4.5 复盘：环境搭建的检查点

环境搭建完成后，建议按以下顺序做一次完整自检：确认交叉编译器可执行且版本正确；确认内核源码可被 KDIR 正确指向；确认 Jailhouse 编译无警告且生成了 hypervisor.bin 与 jailhouse.ko；确认目标平台可启动并加载模块；确认 jailhouse enable 后系统未挂死。只有这五个检查点全部通过，才进入后续的 Cell 配置与设备划分阶段。

把环境搭建做扎实，后续的移植与故障诊断才有稳定的基线。很多看似复杂的启动失败，根源都在这一章的几个版本参数上。