IMX-Forge 系统架构文档¶
文档版本: v1.0 最后更新: 2026-03-15 维护者: IMX-Forge 项目组
文档概述¶
本文档详细描述 IMX-Forge 项目的整体系统架构，包括模块组成、依赖关系、数据流向以及核心设计决策。通过本文档，开发者可以快速理解项目的组织结构，并有效地参与开发工作。
目录¶
1. 整体架构概览¶
1.1 架构图¶
┌─────────────────────────────────────────────────────────────────────┐
│ IMX-Forge 项目架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ 开发环境 │───▶│ 构建系统 │───▶│ 输出产物 │ │
│ │ Development │ │ Scripts │ │ Output Artifacts │ │
│ └─────────────┘ └──────────────┘ └─────────────────────┘ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ 第三方源码 │ │ 补丁管理 │ │ 可烧录镜像文件 │ │
│ │Third-Party │◀───│ Patches │ │ - zImage │ │
│ │ Sources │ │ │ │ - u-boot.bin │ │
│ │ │ │ ┌────────┐ │ │ - rootfs │ │
│ │ ┌─────────┐ │ │ │linux- │ │ │ - DTB │ │
│ │ │linux- │ │ │ │imx/ │ │ │ │ │
│ │ │imx │ │ │ │mainline│ │ │ │ │
│ │ └─────────┘ │ │ │/uboot/ │ │ │ │ │
│ │ ┌─────────┐ │ │ └────────┘ │ │ │ │
│ │ │uboot- │ │ └──────────────┘ │ │ │
│ │ │imx │ │ │ │ │ │
│ │ └─────────┘ │ │ │ │ │
│ │ ┌─────────┐ │ │ │ │ │
│ │ │busybox │ │ │ │ │ │
│ │ └─────────┘ │ │ │ │ │
│ └─────────────┘ │ │ │ │
│ │ │ │ │
│ ┌─────────────┐ │ │ │ │
│ │ 板卡支持 │ │ │ │ │
│ │ Boards │───────────┘ │ │ │
│ │ │ │ │ │
│ │ - alpha │ │ │ │
│ │ - custom-v1 │ │ │ │
│ └─────────────┘ │ │ │
│ │ │ │
│ ┌─────────────┐ │ │ │
│ │ 文档教程 │ ▼ │ │
│ │ Documents │◀─────────────────────────┘ │ │
│ │ │ │ │
│ │ - tutorial │ │ │
│ │ - roadmap │ │ │
│ │ - architecture│ │ │
│ └─────────────┘ │ │
│ │ │
└──────────────────────────────────────────────────────────────────┘
1.2 核心模块说明¶
| 模块名称 | 路径 | 功能描述 |
|---|---|---|
| 构建系统 | scripts/ |
提供统一的构建入口，管理编译流程 |
| 第三方源码 | third_party/ |
Git Submodule 管理的第三方源码 |
| 补丁管理 | patches/ |
基于格式化补丁的修改管理 |
| 板卡支持 | boards/ |
板级配置和设备树文件 |
| 文档教程 | document/ |
项目文档和教程 |
| 驱动模块 | driver/ |
自研驱动和设备树overlay |
| 根文件系统 | rootfs/ |
多种根文件系统实现 |
| 输出目录 | out/ |
构建产物输出位置 |
2. 启动流程架构¶
2.1 完整启动流程¶
┌──────────────────────────────────────────────────────────────────────┐
│ i.MX6ULL 系统启动流程 │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ 上电复位 │ │
│ │ Power On/Reset│ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ ROM Code │ ───▶ 内部 BootROM，不可修改 │
│ │ (芯片内部) │ - 从 eMMC/SD 加载 SPL │
│ └──────┬───────┘ - 初始化基础硬件 │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ SPL │ ───▶ Secondary Program Loader │
│ │ (MLO/u-boot │ - 初始化 DDR │
│ │ .spl) │ - 加载完整 U-Boot │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ U-Boot │ ───▶ Universal Bootloader │
│ │ (引导加载器) │ - 硬件初始化 │
│ │ │ - 加载设备树 (DTB) │
│ │ │ - 加载内核镜像 │
│ │ │ - 设置 bootargs │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Linux Kernel│ ───▶ 操作系统内核 │
│ │ (zImage) │ - 内核初始化 │
│ │ │ - 驱动加载 │
│ │ │ - 挂载根文件系统 │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Rootfs │ ───▶ 根文件系统 │
│ │ (根文件系统) │ - busybox / Buildroot / Debian │
│ │ │ - 启动 init 进程 │
│ │ │ - 运行用户应用 │
│ └──────────────┘ │
│ │
│ 支持的启动介质: eMMC / SD 卡 / NFS 网络根文件系统 │
│ │
└──────────────────────────────────────────────────────────────────────┘
2.2 组件来源与版本¶
| 组件 | 来源分支 | 版本策略 | 状态 |
|---|---|---|---|
| U-Boot | uboot-imx (NXP fork) |
跟随 NXP 官方 BSP | 当前 |
| Linux Kernel | linux-imx (NXP fork) |
跟随 NXP 官方 BSP | 当前 |
| Linux Kernel | mainline (Torvalds) |
实验性支持 | 规划中 |
| BusyBox | mirror/busybox |
官方稳定版 | 当前 |
2.3 存储介质布局¶
┌─────────────────────────────────────────────────────────────┐
│ eMMC/SD 卡分区布局 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 分区 0: Boot Partition (可启动硬件分区) │
│ ┌──────────────────────────────────────────┐ │
│ │ SPL / MLO │ │
│ │ (必需位于固定位置，ROM Code 可寻址) │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 分区 1: U-Boot 分区 │
│ ┌──────────────────────────────────────────┐ │
│ │ u-boot.img / u-boot.bin │ │
│ │ (完整 U-Boot 镜像) │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 分区 2: 内核与设备树 │
│ ┌──────────────────────────────────────────┐ │
│ │ zImage (压缩内核镜像) │ │
│ │ *.dtb (设备树二进制文件) │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 分区 3: 根文件系统 │
│ ┌──────────────────────────────────────────┐ │
│ │ Rootfs (ext4/squashfs/ubifs) │ │
│ │ - busybox │ │
│ │ - Buildroot │ │
│ │ - 或 Debian/Ubuntu │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 可选: 数据分区 │
│ ┌──────────────────────────────────────────┐ │
│ │ 用户数据 / 应用数据 │ │
│ └──────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
3. 双轨策略架构¶
3.1 策略总览¶
IMX-Forge 采用双轨并行策略，平衡稳定性与前沿性：
┌───────────────────────────────────────────────────────────────────┐
│ 双轨策略时间轴 │
├───────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ v0.x [当前阶段] │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ linux-imx 轨道 │ │ │
│ │ │ - NXP BSP 6.12.3 基线 │ │ │
│ │ │ - 完整驱动支持 │ │ │
│ │ │ - 稳定性优先 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ mainline 轨道 │ │ │
│ │ │ - 实验性探索 │ │ │
│ │ │ - 差异分析记录 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ │ 补丁向上游提交 / 移植 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ v1.x [中期目标] │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ linux-imx 轨道 │ │ │
│ │ │ - 继续维护 │ │ │
│ │ │ - 生产环境推荐 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ mainline 轨道 │ │ │
│ │ │ + 基础功能验证 │ │ │
│ │ │ + 关键驱动移植 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ │ mainline 趋于稳定 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ v2.x [长期目标] │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ linux-imx 轨道 │ │ │
│ │ │ - 兼容性备选 │ │ │
│ │ │ - 向后兼容支持 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ mainline 轨道 │ │ │
│ │ │ + 成为推荐轨道 │ │ │
│ │ │ + 全功能验证通过 │ │ │
│ │ │ + 补丁向上游合并 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────┘
3.2 轨道对比¶
| 特性 | linux-imx 轨道 | mainline 轨道 |
|---|---|---|
| 基线来源 | NXP 官方 BSP | Torvalds 主线 |
| 驱动完整性 | 完整支持 i.MX 系列 | 需要适配验证 |
| 更新频率 | 跟随 NXP 发布 | 跟随内核主线 |
| 稳定性 | 生产可用 | 实验性 |
| 补丁标签 | [linux-imx] |
[mainline] |
| 存储位置 | patches/linux-imx/ |
patches/linux-mainline/ |
| 上游策略 | NXP 特有补丁本地化 | 积极向上游合并 |
3.3 补丁目录结构¶
patches/
├── linux-imx/ # NXP BSP 轨道补丁
│ ├── series # 补丁应用序列文件
│ ├── 0001-xxx.patch # [linux-imx] 标签补丁
│ └── ...
├── linux-mainline/ # 主线内核轨道补丁
│ ├── series # 补丁应用序列文件 (未来)
│ └── ...
├── uboot-imx/ # U-Boot NXP fork 补丁
│ └── charlies_board.patch
├── uboot/ # U-Boot mainline 补丁 (未来)
└── busybox/ # BusyBox 补丁
4. 模块依赖关系¶
4.1 依赖关系图¶
┌─────────────────────────────────────────────────────────────────────┐
│ 模块依赖关系图 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ scripts/ (构建系统) │
│ │ │
│ ├── lib/ │
│ │ └── logging.sh ◀─────── 被所有构建脚本引用 │
│ │ │
│ ├── build_helper/ │
│ │ ├── build-linux.sh ────▶ third_party/linux-imx/ │
│ │ ├── build-uboot.sh ────▶ third_party/uboot-imx/ │
│ │ └── build-busybox.sh ────▶ third_party/busybox/ │
│ │ │
│ ├── patch_maker.sh ────▶ 生成 patches/*.patch │
│ │ │
│ ├── release_builder/ ────▶ 打包输出产物 │
│ │ │
│ ├── third_party_install/ │
│ │ └── install_libc.sh ────▶ rootfs/nfs/ │
│ │ │
│ └── varified_rootfs_ok.sh ────▶ rootfs/nfs/ │
│ │ │
│ ▼ │
│ driver/device_tree/alpha-board/ │
│ │ ├── linux/ ────▶ third_party/linux-imx/arch/arm/boot/dts/ │
│ │ └── uboot/ ────▶ third_party/uboot-imx/arch/arm/dts/ │
│ │
│ patches/ │
│ │ ├── linux-imx/ ────▶ third_party/linux-imx/ │
│ │ ├── uboot-imx/ ────▶ third_party/uboot-imx/ │
│ │ └── busybox/ ────▶ third_party/busybox/ │
│ │
│ out/ ◀─── 所有构建脚本的输出目录 │
│ │
└─────────────────────────────────────────────────────────────────────┘
4.2 脚本调用链¶
┌─────────────────────────────────────────────────────────────────────┐
│ 构建流程调用链 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 用户命令 │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ 构建入口脚本 │ (未来实现) │
│ │ scripts/ │ │
│ │ build.sh │ │
│ └──────┬──────┘ │
│ │ │
│ ├──▶ scripts/build_helper/build-linux.sh │
│ │ │ │
│ │ ├── 1. source scripts/lib/logging.sh │
│ │ ├── 2. check_host_dependencies() │
│ │ ├── 3. check_toolchain() │
│ │ ├── 4. apply patches/linux-imx/*.patch │
│ │ ├── 5. do_configure() │
│ │ └── 6. do_build() │
│ │ │
│ ├──▶ scripts/build_helper/build-uboot.sh │
│ │ │ │
│ │ └── (类似流程) │
│ │ │
│ └──▶ scripts/build_helper/build-busybox.sh │
│ │ │
│ └── (类似流程) │
│ │
│ Rootfs 构建 │
│ │ │
│ ▼ │
│ scripts/varified_rootfs_ok.sh │
│ │ │
│ ├── check_directory_safe() │
│ ├── check_required_dirs() │
│ ├── create_rootfs_structure() │
│ ├── create_fstab() │
│ ├── create_rcs() │
│ ├── create_inittab() │
│ └── run_third_party_installs() │
│ │ │
│ └── scripts/third_party_install/*.sh │
│ │
└─────────────────────────────────────────────────────────────────────┘
4.3 Git Submodule 管理¶
.gitmodules 配置:
┌─────────────────────────────────────────────────────────────────────┐
│ [submodule "third_party/uboot-imx"] │
│ path = third_party/uboot-imx │
│ url = https://github.com/nxp-imx/uboot-imx.git │
│ ignore = dirty │
│ │
│ [submodule "third_party/linux-imx"] │
│ path = third_party/linux-imx │
│ url = https://github.com/nxp-imx/linux-imx.git │
│ ignore = dirty │
│ │
│ [submodule "third_party/busybox"] │
│ path = third_party/busybox │
│ url = https://github.com/mirror/busybox.git │
│ │
└─────────────────────────────────────────────────────────────────────┘
5. 数据流向说明¶
5.1 源码到补丁的流向¶
┌─────────────────────────────────────────────────────────────────────┐
│ 源码修改 → 补丁 → 构建流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. 源码修改阶段 │
│ ┌────────────────────────────────────┐ │
│ │ third_party/linux-imx/ │ │
│ │ └── drivers/xxx/modified_file.c │ ← 直接修改 │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ Git 工作区 │ │
│ │ - Modified files │ │
│ │ - New commits │ │
│ └────────────────────────────────────┘ │
│ │
│ 2. 补丁生成阶段 │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ scripts/patch_maker.sh │ │
│ │ --submodule_path=linux-imx │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ patches/linux-imx/ │ │
│ │ └── new-changes.patch │ ← 生成补丁 │
│ └────────────────────────────────────┘ │
│ │
│ 3. 补丁应用阶段 │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ scripts/build_helper/build-linux.sh │ │
│ │ quilt import / patch -p1 │ ← 应用补丁 │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────�┐ │
│ │ out/linux/ │ │
│ │ ├── zImage │ ← 编译输出 │
│ │ ├── vmlinux │ │
│ │ └── *.dtb │ │
│ └────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
5.2 配置文件影响构建的流向¶
┌─────────────────────────────────────────────────────────────────────┐
│ 配置文件 → 构建参数流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 板级配置 (未来) │
│ ┌────────────────────────────────────┐ │
│ │ boards/alpha/BOARD.yaml │ │
│ │ name: "Alpha Board" │ │
│ │ defconfig: "imx_aes_defconfig" │ ──────┐ │
│ │ dtb: "imx6ull-alpha.dtb" │ │ │
│ └────────────────────────────────────┘ │ │
│ 解析 │
│ Defconfig │ │
│ ┌────────────────────────────────────┐ │ │
│ │ third_party/linux-imx/ │ │ │
│ │ arch/arm/configs/ │ │ │
│ │ imx_aes_defconfig │ ←───┘ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ make imx_aes_defconfig │ │
│ │ └──▶ .config │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ make -jN │ │
│ │ └──▶ 构建输出 │ │
│ └────────────────────────────────────┘ │
│ │
│ 设备树配置 │
│ ┌────────────────────────────────────┐ │
│ │ driver/device_tree/alpha-board/ │ │
│ │ linux/imx6ull-alpha.dts │ ──────┐ │
│ └────────────────────────────────────┘ │ │
│ 复制/编译 │
│ ┌────────────────────────────────────┐ │ │
│ │ third_party/linux-imx/ │ │ │
│ │ arch/arm/boot/dts/ │ ←───┘ │
│ │ imx6ull-alpha.dts │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ dtc -I dts -O dtb │ │
│ │ └──▶ imx6ull-alpha.dtb │ │
│ └────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
5.3 Rootfs 构建流向¶
┌─────────────────────────────────────────────────────────────────────┐
│ Rootfs 构建数据流 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ BusyBox 编译 │
│ ┌────────────────────────────────────┐ │
│ │ third_party/busybox/ │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ scripts/build_helper/ │ │
│ │ build-busybox.sh │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ out/busybox/busybox │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ rootfs/nfs/bin/busybox │ ← 复制到 rootfs │
│ └────────────────────────────────────┘ │
│ │
│ Rootfs 初始化 │
│ ┌────────────────────────────────────┐ │
│ │ scripts/varified_rootfs_ok.sh │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ├──▶ 创建目录结构 │
│ ├──▶ 生成配置文件 │
│ │ - etc/fstab │
│ │ - etc/inittab │
│ │ - etc/init.d/rcS │
│ │ │
│ └──▶ 运行第三方安装脚本 │
│ scripts/third_party_install/*.sh │
│ │
│ 最终 Rootfs 结构 │
│ rootfs/nfs/ │
│ ├── bin/busybox │
│ ├── lib/ │
│ ├── etc/fstab │
│ ├── etc/inittab │
│ ├── etc/init.d/rcS │
│ └── linuxrc -> bin/busybox │
│ │
└─────────────────────────────────────────────────────────────────────┘
6. 目录结构说明¶
6.1 完整目录树¶
imx-forge/
├── .devcontainer/ # VS Code Dev Container 配置
├── .git/ # Git 仓库
│ └── modules/ # Submodule 检出位置
├── .gitmodules # Submodule 配置文件
├── document/ # 项目文档
│ ├── architecture/ # 架构文档 (本目录)
│ │ └── SYSTEM_ARCHITECTURE.md
│ ├── logo/ # 项目 Logo 资源
│ ├── todo/ # 待办事项文档
│ └── tutorial/ # 教程文档
│ ├── kernel/ # 内核相关教程
│ ├── practical/ # 实践教程
│ ├── rootfs/ # Rootfs 教程
│ ├── start/ # 入门教程
│ └── uboot/ # U-Boot 教程
├── driver/ # 驱动模块
│ └── device_tree/ # 设备树文件
│ └── alpha-board/ # 阿尔法板设备树
│ ├── linux/ # 内核设备树
│ └── uboot/ # U-Boot 设备树
├── out/ # 构建输出目录
│ ├── busybox/ # BusyBox 构建产物
│ ├── linux/ # Linux 内核构建产物
│ └── uboot/ # U-Boot 构建产物
├── patches/ # 补丁管理
│ ├── busybox/ # BusyBox 补丁
│ ├── linux-imx/ # linux-imx 轨道补丁
│ │ └── linux-imx-patch_test-20260314.patch
│ ├── linux-mainline/ # mainline 轨道补丁 (未来)
│ ├── uboot/ # U-Boot mainline 补丁 (未来)
│ └── uboot-imx/ # U-Boot NXP fork 补丁
│ └── charlies_board.patch
├── rootfs/ # 根文件系统
│ ├── nfs/ # NFS Rootfs
│ │ ├── bin/ # 可执行文件
│ │ ├── dev/ # 设备文件
│ │ ├── etc/ # 配置文件
│ │ │ ├── fstab # 文件系统挂载表
│ │ │ ├── init.d/ # 初始化脚本
│ │ │ │ └── rcS # 系统初始化脚本
│ │ │ └── inittab # init 配置
│ │ ├── home/ # 用户目录
│ │ ├── lib/ # 库文件
│ │ ├── mnt/ # 挂载点
│ │ ├── proc/ # proc 文件系统
│ │ ├── root/ # root 用户目录
│ │ ├── sbin/ # 系统可执行文件
│ │ ├── sys/ # sys 文件系统
│ │ ├── tmp/ # 临时文件
│ │ └── usr/ # 用户程序
│ └── src/ # Rootfs 源文件
├── scripts/ # 构建和工具脚本
│ ├── build_helper/ # 构建辅助脚本
│ │ ├── build-busybox.sh # BusyBox 构建脚本
│ │ ├── build-linux.sh # Linux 内核构建脚本
│ │ └── build-uboot.sh # U-Boot 构建脚本
│ ├── lib/ # 公共库
│ │ └── logging.sh # 日志工具库
│ ├── logo_helper/ # Logo 生成工具
│ ├── patch_maker.sh # 补丁生成脚本
│ ├── release_builder/ # 发布构建脚本
│ ├── server_helper/ # 服务器辅助脚本
│ ├── third_party_install/ # 第三方依赖安装
│ │ ├── README.md # 安装脚本说明
│ │ └── install_libc.sh # libc 安装脚本
│ └── varified_rootfs_ok.sh # Rootfs 验证脚本
├── third_party/ # 第三方源码 (Submodule)
│ ├── busybox/ # BusyBox 源码
│ ├── linux-imx/ # NXP Linux 内核 fork
│ └── uboot-imx/ # NXP U-Boot fork
├── tools/ # 工具集合
│ └── third_party/ # 第三方工具
├── LICENSE # 开源协议
├── README.md # 项目说明
└── roadmap.md # 项目路线图
6.2 目录功能说明表¶
| 目录路径 | 用途 | 维护策略 |
|---|---|---|
scripts/ |
构建系统核心 | 项目维护，版本控制 |
patches/ |
补丁管理 | 项目维护，版本控制 |
third_party/ |
第三方源码 | Submodule，独立更新 |
out/ |
构建输出 | .gitignore，本地生成 |
rootfs/ |
根文件系统 | 框架版本控制，内容由脚本生成 |
driver/ |
自研驱动 | 项目维护，版本控制 |
document/ |
项目文档 | 项目维护，版本控制 |
tools/ |
工具集合 | 项目维护，版本控制 |
7. 设计决策记录¶
7.1 为什么选择 format-patch + series¶
背景
嵌入式开发中，对厂商 BSP 的修改管理是一个挑战。直接修改源码无法追踪、无法复用、难以贡献回上游。
决策
采用 Git format-patch 生成的标准补丁格式，配合 series 文件管理应用顺序。
理由
| 优势 | 说明 |
|---|---|
| 标准化 | Git 原生支持，无需额外工具 |
| 可追溯 | 每个补丁包含完整的提交信息和作者信息 |
| 可贡献 | 补丁格式与上游内核贡献格式一致 |
| 可复用 | 补丁可以在不同版本间尝试应用 |
| 可审查 | 纯文本格式，便于代码审查 |
| 灵活性 | 通过 series 文件控制应用顺序和条件 |
实现
# 生成补丁
git format-patch -o patches/linux-imx/ base_commit..HEAD
# 应用补丁
quilt import patches/linux-imx/*.patch
quilt push -a
# 或使用 patch 命令
cat patches/linux-imx/series | while read patch; do
patch -p1 < "patches/linux-imx/$patch"
done
7.2 为什么采用双轨策略¶
背景
- NXP 提供的 linux-imx 分支包含大量针对 i.MX 系列的优化和驱动
- 主线内核 (mainline) 代表 Linux 的发展方向，长期维护更佳
- 直接切换到 mainline 需要大量适配工作，存在风险
决策
采用双轨并行策略：以 linux-imx 为当前稳定轨道，同时探索 mainline 轨道。
理由
| 稳定性 (linux-imx) | 前瞻性 (mainline) |
|---|---|
| NXP 官方支持 | 代表 Linux 未来 |
| 驱动完整 | 代码质量更高 |
| 立即可用 | 长期维护更佳 |
| 适合生产环境 | 适合学习和贡献 |
长期目标
- v0.x: 完善 linux-imx 轨道，确保基础功能稳定
- v1.x: 开始 mainline 探索，记录差异和移植经验
- v2.x: mainline 功能完整，成为推荐轨道
- 未来: 积极向上游贡献补丁，减少本地修改
7.3 为什么使用 Git Submodule¶
背景
项目需要集成多个第三方大型代码库： - linux-imx (~1GB+) - uboot-imx (~500MB+) - busybox (~50MB+)
决策选项对比
| 方案 | 优点 | 缺点 |
|---|---|---|
| 直接复制 | 简单 | 体积大，无法更新 |
| Git Submodule | 独立更新，精确版本 | 学习曲线 |
| 下载脚本 | 灵活 | 无版本锁定 |
| Vendor 分支 | 完全控制 | 合并复杂 |
选择 Git Submodule 的理由
- 精确版本控制: 通过 commit hash 锁定第三方库版本
- 独立更新: 第三方库的更新与主项目分离
- 节省空间: Submodule 使用对象共享，节省存储
- 社区标准: 广泛使用的依赖管理方式
- 灵活性: 可以随时切换到任意 commit 或分支
配置策略
[submodule "third_party/linux-imx"]
path = third_party/linux-imx
url = https://github.com/nxp-imx/linux-imx.git
ignore = dirty # 忽略工作区修改，仅追踪提交
7.4 为什么输出目录独立¶
背景
构建产物体积大，且大部分是二进制文件，不应纳入版本控制。
决策
使用独立的 out/ 目录存放所有构建输出，并在 .gitignore 中排除。
理由
- 清洁仓库: 源码与产物分离
- 可重建: 任何时候都可以从源码重建
- 灵活性: 可以随时删除 out/ 释放空间
- 并行构建: 不同组件输出到不同子目录，互不干扰
目录结构
7.5 为什么 Rootfs 采用脚本生成¶
背景
Rootfs 需要包含库文件、配置文件、初始化脚本等，手动维护容易出错。
决策
通过 scripts/varified_rootfs_ok.sh 脚本自动生成 Rootfs 结构和配置。
理由
- 可重现: 脚本确保每次生成的 Rootfs 一致
- 可验证: 脚本内置验证逻辑
- 可扩展: 通过第三方安装脚本机制扩展功能
- 安全性: 内置目录安全检查，防止误操作系统根目录
扩展机制
# scripts/third_party_install/ 目录下的所有 .sh 脚本
# 会在 Rootfs 构建时自动执行，支持:
# - 安装额外的库文件
# - 添加自定义配置
# - 执行特定的初始化操作
8. 构建系统架构¶
8.1 构建系统组件图¶
┌─────────────────────────────────────────────────────────────────────┐
│ 构建系统架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 用户接口层 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ scripts/build.sh (未来实现) │ │
│ │ --board=alpha --rootfs=busybox --clean │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 构建辅助层 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ scripts/build_helper/ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│ │ │build-linux │ │build-uboot │ │ build-busybox │ │ │
│ │ │ .sh │ │ .sh │ │ .sh │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 公共服务层 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ scripts/lib/ │ │
│ │ ┌────────────────────────────────────────────────────────┐ │ │
│ │ │ logging.sh - 统一日志接口 │ │ │
│ │ │ - log_info(), log_error(), log_warn(), log_debug() │ │ │
│ │ └────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 工具支持层 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ scripts/patch_maker.sh - 补丁生成工具 │ │
│ │ scripts/release_builder/ - 发布打包工具 │ │
│ │ scripts/third_party_install/ - 依赖安装脚本 │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
8.2 构建脚本依赖图¶
┌─────────────────────────────────────────────────────────────────────┐
│ 脚本依赖关系图 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ build-linux.sh │
│ │ │
│ ├──▶ source scripts/lib/logging.sh │
│ │ │
│ ├──▶ check_host_dependencies() │
│ │ │ │
│ │ ├── check_cmd (gcc, make, bc, bison, flex...) │
│ │ ├── check_dpkg (libssl-dev, libncurses-dev...) │
│ │ └── check_python_module │
│ │ │
│ ├──▶ check_toolchain() │
│ │ │ │
│ │ └── ${CROSS_COMPILE}gcc, objcopy, objdump... │
│ │ │
│ ├──▶ apply patches/linux-imx/*.patch │
│ │ │
│ ├──▶ do_configure() │
│ │ │ │
│ │ └── make ${DEFCONFIG} │
│ │ │
│ └──▶ do_build() │
│ │ │
│ └── make -j${NPROC} │
│ │
└─────────────────────────────────────────────────────────────────────┘
8.3 环境变量与配置¶
┌─────────────────────────────────────────────────────────────────────┐
│ 配置变量说明 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 全局配置 (可在脚本中覆盖) │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ ARCH=arm │ │
│ │ CROSS_COMPILE=arm-none-linux-gnueabihf- │ │
│ │ NPROC=$(nproc) │ │
│ │ PROJECT_ROOT=$(自动检测) │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ Linux 构建配置 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ LINUX_SRC_DIR=${PROJECT_ROOT}/third_party/linux-imx │ │
│ │ OUTPUT_DIR=${PROJECT_ROOT}/out/linux │ │
│ │ DEFCONFIG=imx_aes_defconfig │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ U-Boot 构建配置 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ UBOOT_SRC_DIR=${PROJECT_ROOT}/third_party/uboot-imx │ │
│ │ OUTPUT_DIR=${PROJECT_ROOT}/out/uboot │ │
│ │ DEFCONFIG=... │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ Rootfs 配置 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ ROOTFS_DIR=${PROJECT_ROOT}/rootfs/nfs │ │
│ │ CROSS_COMPILE=arm-none-linux-gnueabihf- │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
9. 扩展机制¶
9.1 板卡接入扩展¶
┌─────────────────────────────────────────────────────────────────────┐
│ 新板卡接入流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. 创建板卡目录 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ boards/custom-v1/ │ │
│ │ ├── BOARD.yaml # 板卡元数据 │ │
│ │ ├── configs/ # 板级配置 │ │
│ │ │ └── kernel_defconfig │ │
│ │ └── dts/ # 设备树源文件 │ │
│ │ └── imx6ull-custom.dts │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ 2. 配置板卡信息 (未来实现) │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ BOARD.yaml 内容: │ │
│ │ name: "Custom Board v1" │ │
│ │ chip: "i.MX6ULL" │ │
│ │ storage: ["eMMC", "SD"] │ │
│ │ defconfig: "custom_defconfig" │ │
│ │ dtb: "imx6ull-custom.dtb" │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ 3. 构建命令 (未来实现) │
│ scripts/build.sh --board=custom-v1 │
│ │
└─────────────────────────────────────────────────────────────────────┘
9.2 Rootfs 扩展机制¶
┌─────────────────────────────────────────────────────────────────────┐
│ Rootfs 第三方安装脚本 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ scripts/third_party_install/ │
│ │ │
│ ├── 10-install-libc.sh # 安装 libc 库 │
│ ├── 20-install-ssl.sh # 安装 OpenSSL 库 │
│ ├── 30-install-custom.sh # 安装自定义库 │
│ └── README.md # 说明文档 │
│ │ │
│ ▼ │
│ 执行流程: │
│ 1. 按文件名字母顺序执行 │
│ 2. 导出环境变量: ROOTFS_DIR, PROJECT_ROOT │
│ 3. 每个脚本独立运行，失败不影响其他脚本 (可选策略) │
│ │
│ 脚本模板: │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ #!/bin/bash │ │
│ │ : "${ROOTFS_DIR:=../../rootfs/nfs}" │ │
│ │ set -e │ │
│ │ # 安装逻辑... │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
9.3 驱动模块扩展¶
┌─────────────────────────────────────────────────────────────────────┐
│ 驱动模块组织 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ driver/ │
│ │ │
│ ├── device_tree/ # 设备树 overlay │
│ │ └── alpha-board/ │
│ │ ├── linux/ │
│ │ │ └── imx6ull-alpha.dts │
│ │ └── uboot/ │
│ │ └── imx6ull-alpha-u-boot.dts │
│ │ │
│ └── modules/ # 内核模块 (未来) │
│ ├── rs485-control/ │
│ │ ├── rs485_control.c │
│ │ ├── Kconfig │
│ │ └── Makefile │
│ └── README.md │
│ │
└─────────────────────────────────────────────────────────────────────┘
附录¶
A. 快速参考¶
A.1 常用目录路径¶
| 路径 | 说明 |
|---|---|
third_party/linux-imx |
Linux 内核源码 |
third_party/uboot-imx |
U-Boot 源码 |
third_party/busybox |
BusyBox 源码 |
patches/linux-imx |
Linux 补丁 |
patches/uboot-imx |
U-Boot 补丁 |
out/linux |
Linux 构建输出 |
out/uboot |
U-Boot 构建输出 |
out/busybox |
BusyBox 构建输出 |
rootfs/nfs |
NFS Rootfs |
driver/device_tree |
设备树文件 |
A.2 常用脚本命令¶
# 构建 Linux 内核
scripts/build_helper/build-linux.sh
# 构建 U-Boot
scripts/build_helper/build-uboot.sh
# 构建 BusyBox
scripts/build_helper/build-busybox.sh
# 验证和完成 Rootfs
scripts/varified_rootfs_ok.sh
# 生成补丁
scripts/patch_maker.sh --submodule_path=linux-imx
# 快速构建 (跳过 distclean)
scripts/build_helper/build-linux.sh --fast-build
B. 版本控制规范¶
B.1 补丁命名规范¶
格式: [轨道类型] 简短描述
轨道类型:
- [linux-imx] NXP BSP 轨道补丁
- [mainline] 主线内核轨道补丁
- [uboot-imx] U-Boot NXP fork 补丁
- [uboot-main] U-Boot 主线补丁
示例:
[linux-imx] drivers: add alpha board support
[mainline] net: fec: add imx6ull support
[uboot-imx] board: enable alpha board
B.2 Commit 规范¶
格式: <类型>: <简短描述>
类型:
- feat: 新功能
- fix: Bug 修复
- docs: 文档更新
- style: 代码格式
- refactor: 代码重构
- test: 测试相关
- chore: 构建/工具相关
示例:
feat(build): add linux build script
fix(patches): correct series file order
docs(readme): update board support table
C. 故障排查¶
C.1 常见问题¶
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 编译失败 | 缺少依赖 | 运行 sudo apt install ... |
| 补丁应用失败 | 版本不匹配 | 检查 submodule 版本 |
| 交叉编译错误 | 工具链未找到 | 检查 PATH 环境变量 |
| Rootfs 启动失败 | 配置文件缺失 | 运行 varified_rootfs_ok.sh |
C.2 日志级别¶
# 启用调试输出
DEBUG=1 scripts/build_helper/build-linux.sh
# 查看构建日志
cat out/linux/build.log
# 查看补丁应用日志
quilt push -v
文档修订历史¶
| 版本 | 日期 | 作者 | 变更说明 |
|---|---|---|---|
| v1.0 | 2026-03-15 | IMX-Forge | 初始版本 |
联系方式¶
**IMX-Forge - 让 i.MX6ULL 开发更简单**