正常
IMX-Forge 系统架构文档
文档版本: v1.0 最后更新: 2026-03-15 维护者: IMX-Forge 项目组
文档概述
本文档详细描述 IMX-Forge 项目的整体系统架构，包括模块组成、依赖关系、数据流向以及核心设计决策。通过本文档，开发者可以快速理解项目的组织结构，并有效地参与开发工作。
目录
1. 整体架构概览
1.1 架构图
展开代码收起代码共 47 行
┌─────────────────────────────────────────────────────────────────────┐
│ IMX-Forge 项目架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ 开发环境 │───▶│ 构建系统 │───▶│ 输出产物 │ │
│ │ Development │ │ Scripts │ │ Output Artifacts │ │
│ └─────────────┘ └──────────────┘ └─────────────────────┘ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ 第三方源码 │ │ 补丁管理 │ │ 可烧录镜像文件 │ │
│ │Third-Party │◀───│ Patches │ │ - zImage │ │
│ │ Sources │ │ │ │ - u-boot.bin │ │
│ │ │ │ ┌────────┐ │ │ - rootfs │ │
│ │ ┌─────────┐ │ │ │linux_ │ │ │ - DTB │ │
│ │ │linux_ │ │ │ │mainline│ │ │ │ │
│ │ │mainline │ │ │ │uboot- │ │ │ │ │
│ │ └─────────┘ │ │ │imx/ │ │ │ │ │
│ │ ┌─────────┐ │ │ └────────┘ │ │ │ │
│ │ │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 完整启动流程
展开代码收起代码共 50 行
┌──────────────────────────────────────────────────────────────────────┐
│ 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_mainline (Torvalds 上游) | pin v7.1 tag | 唯一内核轨 |
| BusyBox | mirror/busybox | 官方稳定版 | 当前 |
2.3 存储介质布局
展开代码收起代码共 36 行
┌─────────────────────────────────────────────────────────────┐
│ 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 单轨现状
内核轨只有一条：上游主线 mainline Linux。NXP linux-imx vendor 轨已于 2026-09 退役，对应的子模块、patches/linux-imx/ 目录和 vendor defconfig 模板都已删除，CI 也没有对应 job，历史可以查 git 记录。
┌───────────────────────────────────────────────────────────────────┐
│ 内核轨道现状 │
├───────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ mainline 轨道（唯一内核轨） │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ - 子模块 third_party/linux_mainline │ │ │
│ │ │ (Torvalds 上游，shallow，pin 在 tag v7.1) │ │ │
│ │ │ - 补丁目录 patches/linux_mainline/ ([mainline]) │ │ │
│ │ │ - v7.1 已在真板实测启动，CI 持续构建验证 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 升级方式：更新 pin 的 tag → 重做总补丁 → 全量验证 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────┘3.2 为什么只保留 mainline 单轨
| 考虑 | 说明 |
|---|---|
| 真板已验证 | v7.1 在 i.MX6ULL 真板实测启动，CI 持续构建验证 |
| 长期维护 | 跟随 Torvalds 主线，版本演进节奏稳定 |
| 维护成本 | 不用再维护第二份内核子模块、补丁集和 CI job |
| 补丁去向 | 项目改动集中在 patches/linux_mainline/ 的总补丁，方向是尽量合入上游 |
3.3 补丁目录结构
patches/
├── linux_mainline/ # mainline 内核补丁（唯一内核轨）
│ └── linux_mainline-feat-imx6ull_patches-20260828.patch
├── qemu/ # QEMU 板级模拟补丁
├── uboot/ # U-Boot mainline 补丁（预留）
└── uboot-imx/ # U-Boot NXP fork 补丁
└── charlies_board.patch说明：当前没有 series 机制——每个组件一个总补丁，构建时按文件名取最新一个应用（详见 7.1 节）。
4. 模块依赖关系
4.1 依赖关系图
展开代码收起代码共 36 行
┌─────────────────────────────────────────────────────────────────────┐
│ 模块依赖关系图 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ scripts/ (构建系统) │
│ │ │
│ ├── lib/ │
│ │ └── logging.sh ◀─────── 被所有构建脚本引用 │
│ │ │
│ ├── build_helper/ │
│ │ ├── build-linux.sh ────▶ third_party/linux_mainline/ │
│ │ ├── build-uboot.sh ────▶ third_party/uboot-imx/ │
│ │ └── build-busybox.sh ────▶ third_party/busybox/ │
│ │ │
│ ├── patch_maker.sh ────▶ 生成 patches/*.patch │
│ │ │
│ ├── lib/release.sh ────▶ release 编排(build-* --release 调用) │
│ │ │
│ ├── third_party_install/ │
│ │ └── install_libc.sh ────▶ rootfs/nfs/ │
│ │ │
│ └── varified_rootfs_ok.sh ────▶ rootfs/nfs/ │
│ │ │
│ ▼ │
│ driver/device_tree/alpha-board/ │
│ │ ├── linux/ ────▶ third_party/linux_mainline/arch/arm/boot/ │
│ │ └── uboot/ ────▶ third_party/uboot-imx/arch/arm/dts/ │
│ │
│ patches/ │
│ │ ├── linux_mainline/ ────▶ third_party/linux_mainline/ │
│ │ ├── uboot-imx/ ────▶ third_party/uboot-imx/ │
│ │ └── busybox/ ────▶ third_party/busybox/ │
│ │
│ out/ ◀─── 所有构建脚本的输出目录 │
│ │
└─────────────────────────────────────────────────────────────────────┘4.2 脚本调用链
展开代码收起代码共 46 行
┌─────────────────────────────────────────────────────────────────────┐
│ 构建流程调用链 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 用户命令 │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ 构建入口脚本 │ (未来实现) │
│ │ 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_mainline/*.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_mainline"] │
│ path = third_party/linux_mainline │
│ url = https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git │
│ shallow = true │
│ ignore = dirty │
│ │
│ [submodule "third_party/busybox"] │
│ path = third_party/busybox │
│ url = https://github.com/mirror/busybox.git │
│ │
└─────────────────────────────────────────────────────────────────────┘5. 数据流向说明
5.1 源码到补丁的流向
展开代码收起代码共 48 行
┌─────────────────────────────────────────────────────────────────────┐
│ 源码修改 → 补丁 → 构建流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. 源码修改阶段 │
│ ┌────────────────────────────────────┐ │
│ │ third_party/linux_mainline/ │ │
│ │ └── drivers/xxx/modified_file.c │ ← 直接修改 │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ Git 工作区 │ │
│ │ - Modified files │ │
│ │ - New commits │ │
│ └────────────────────────────────────┘ │
│ │
│ 2. 补丁生成阶段 │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ scripts/patch_maker.sh │ │
│ │ --submodule_path=linux_mainline │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ patches/linux_mainline/ │ │
│ │ └── new-changes.patch │ ← 生成补丁 │
│ └────────────────────────────────────┘ │
│ │
│ 3. 补丁应用阶段 │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ scripts/build_helper/build-linux.sh │ │
│ │ git apply (apply_patches.sh) │ ← 应用补丁 │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────�┐ │
│ │ out/linux/ │ │
│ │ ├── zImage │ ← 编译输出 │
│ │ ├── vmlinux │ │
│ │ └── *.dtb │ │
│ └────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘5.2 配置文件影响构建的流向
展开代码收起代码共 51 行
┌─────────────────────────────────────────────────────────────────────┐
│ 配置文件 → 构建参数流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 板级配置 (未来) │
│ ┌────────────────────────────────────┐ │
│ │ boards/alpha/BOARD.yaml │ │
│ │ name: "Alpha Board" │ │
│ │ defconfig: │ │
│ │ "imx_aes_mainline_defconfig" │ ──────┐ │
│ │ dtb: "imx6ull-alpha.dtb" │ │ │
│ └────────────────────────────────────┘ │ │
│ 解析 │
│ Defconfig │ │
│ ┌────────────────────────────────────┐ │ │
│ │ third_party/linux_mainline/ │ │ │
│ │ arch/arm/configs/ │ │ │
│ │ imx_aes_mainline_defconfig │ ←───┘ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ make imx_aes_mainline_defconfig │ │
│ │ └──▶ .config │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ make -jN │ │
│ │ └──▶ 构建输出 │ │
│ └────────────────────────────────────┘ │
│ │
│ 设备树配置 │
│ ┌────────────────────────────────────┐ │
│ │ driver/device_tree/alpha-board/ │ │
│ │ linux/imx6ull-alpha.dts │ ──────┐ │
│ └────────────────────────────────────┘ │ │
│ 复制/编译 │
│ ┌────────────────────────────────────┐ │ │
│ │ third_party/linux_mainline/ │ │ │
│ │ arch/arm/boot/dts/ │ ←───┘ │
│ │ imx6ull-alpha.dts │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ dtc -I dts -O dtb │ │
│ │ └──▶ imx6ull-alpha.dtb │ │
│ └────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘5.3 Rootfs 构建流向
展开代码收起代码共 49 行
┌─────────────────────────────────────────────────────────────────────┐
│ 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 完整目录树
展开代码收起代码共 78 行
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/ # 补丁管理
│ ├── linux_mainline/ # mainline 内核轨道补丁（唯一内核轨）
│ │ └── linux_mainline-feat-imx6ull_patches-20260828.patch
│ ├── qemu/ # QEMU 板级模拟补丁
│ ├── 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/progress/release)
│ │ ├── logging.sh # 日志工具库
│ │ └── release.sh # release 编排(build-* --release 调用)
│ ├── logo_helper/ # Logo 生成工具
│ ├── patch_maker.sh # 补丁生成脚本
│ ├── server_helper/ # 服务器辅助脚本
│ ├── third_party_install/ # 第三方依赖安装
│ │ ├── README.md # 安装脚本说明
│ │ └── install_libc.sh # libc 安装脚本
│ └── varified_rootfs_ok.sh # Rootfs 验证脚本
├── third_party/ # 第三方源码 (Submodule)
│ ├── busybox/ # BusyBox 源码
│ ├── buildroot/ # Buildroot 源码
│ ├── buildmeter/ # 构建进度条工具
│ ├── linux_mainline/ # 上游主线 Linux 内核 (pin v7.1)
│ ├── qemu/ # QEMU 模拟器源码
│ └── 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 规划
当前实现说明：项目现有自动补丁脚本仍采用“按文件名排序，仅应用最新 patch”的简化策略。
series是推荐架构和后续增强方向，用于未来管理多补丁顺序。
背景
嵌入式开发中，对厂商 BSP 的修改管理是一个挑战。直接修改源码无法追踪、无法复用、难以贡献回上游。
决策
采用 Git format-patch 生成的标准补丁格式；后续可配合 series 文件管理应用顺序。
理由
| 优势 | 说明 |
|---|---|
| 标准化 | Git 原生支持，无需额外工具 |
| 可追溯 | 每个补丁包含完整的提交信息和作者信息 |
| 可贡献 | 补丁格式与上游内核贡献格式一致 |
| 可复用 | 补丁可以在不同版本间尝试应用 |
| 可审查 | 纯文本格式，便于代码审查 |
| 灵活性 | 通过 series 文件控制应用顺序和条件 |
实现
bash
# 生成补丁（推荐用项目脚本，自动对比分支并命名）
./scripts/patch_maker.sh --submodule_path=linux_mainline
# 应用补丁（构建脚本内部就是这么调的）
./scripts/apply_patches.sh linux_mainline
# 或使用 patch 命令手工应用总补丁
cd third_party/linux_mainline
cat ../../patches/linux_mainline/*.patch | patch -p17.2 为什么内核只保留 mainline 单轨
背景
- 项目早期同时维护 NXP linux-imx (6.12.x BSP) 和主线 mainline 两条内核轨
- mainline v7.1 在 i.MX6ULL 真板上实测启动、外设逐步验证通过，双轨里"vendor 轨兜底"的意义消失了
- 双份内核子模块、双份补丁集、双份 CI job 的维护成本却一直存在
决策
2026-09 起只保留 mainline 一条内核轨：linux-imx 子模块、patches/linux-imx/ 目录、vendor defconfig 模板全部删除，历史可查 git 记录。
理由
| 考虑 | 说明 |
|---|---|
| 真板已验证 | v7.1 在真板实测启动，CI 持续构建验证 |
| 长期维护 | 跟随 Torvalds 主线，版本演进节奏稳定 |
| 维护成本 | 少维护一份内核子模块、补丁集和 CI job |
| 上游方向 | 改动收在一个总补丁里，目标是尽量合入上游 |
后续方向
- 内核版本随上游演进：升级时更新 pin 的 tag，重做总补丁并全量验证
- 积极向上游贡献补丁，减少本地修改
7.3 为什么使用 Git Submodule
背景
项目需要集成多个第三方大型代码库：
- linux_mainline (~1GB+)
- uboot-imx (~500MB+)
- busybox (~50MB+)
决策选项对比
| 方案 | 优点 | 缺点 |
|---|---|---|
| 直接复制 | 简单 | 体积大，无法更新 |
| Git Submodule | 独立更新，精确版本 | 学习曲线 |
| 下载脚本 | 灵活 | 无版本锁定 |
| Vendor 分支 | 完全控制 | 合并复杂 |
选择 Git Submodule 的理由
- 精确版本控制: 通过 commit hash 锁定第三方库版本
- 独立更新: 第三方库的更新与主项目分离
- 节省空间: Submodule 使用对象共享，节省存储
- 社区标准: 广泛使用的依赖管理方式
- 灵活性: 可以随时切换到任意 commit 或分支
配置策略
ini
[submodule "third_party/linux_mainline"]
path = third_party/linux_mainline
url = https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
ignore = dirty # 忽略工作区修改，仅追踪提交7.4 为什么输出目录独立
背景
构建产物体积大，且大部分是二进制文件，不应纳入版本控制。
决策
使用独立的 out/ 目录存放所有构建输出，并在 .gitignore 中排除。
理由
- 清洁仓库: 源码与产物分离
- 可重建: 任何时候都可以从源码重建
- 灵活性: 可以随时删除 out/ 释放空间
- 并行构建: 不同组件输出到不同子目录，互不干扰
目录结构
out/
├── busybox/ # BusyBox 构建输出
├── linux/ # Linux 内核构建输出
└── uboot/ # U-Boot 构建输出7.5 为什么 Rootfs 采用脚本生成
背景
Rootfs 需要包含库文件、配置文件、初始化脚本等，手动维护容易出错。
决策
通过 scripts/varified_rootfs_ok.sh 脚本自动生成 Rootfs 结构和配置。
理由
- 可重现: 脚本确保每次生成的 Rootfs 一致
- 可验证: 脚本内置验证逻辑
- 可扩展: 通过第三方安装脚本机制扩展功能
- 安全性: 内置目录安全检查，防止误操作系统根目录
扩展机制
bash
# scripts/third_party_install/ 目录下的所有 .sh 脚本
# 会在 Rootfs 构建时自动执行，支持:
# - 安装额外的库文件
# - 添加自定义配置
# - 执行特定的初始化操作8. 构建系统架构
8.1 构建系统组件图
展开代码收起代码共 39 行
┌─────────────────────────────────────────────────────────────────────┐
│ 构建系统架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 用户接口层 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 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/lib/release.sh - release 编排(--release 模式) │ │
│ │ scripts/third_party_install/ - 依赖安装脚本 │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘8.2 构建脚本依赖图
展开代码收起代码共 29 行
┌─────────────────────────────────────────────────────────────────────┐
│ 脚本依赖关系图 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 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_mainline/*.patch │
│ │ │
│ ├──▶ do_configure() │
│ │ │ │
│ │ └── make ${DEFCONFIG} │
│ │ │
│ └──▶ do_build() │
│ │ │
│ └── make -j${NPROC} │
│ │
└─────────────────────────────────────────────────────────────────────┘8.3 环境变量与配置
展开代码收起代码共 33 行
┌─────────────────────────────────────────────────────────────────────┐
│ 配置变量说明 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 全局配置 (可在脚本中覆盖) │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ ARCH=arm │ │
│ │ CROSS_COMPILE=arm-none-linux-gnueabihf- │ │
│ │ NPROC=$(nproc) │ │
│ │ PROJECT_ROOT=$(自动检测) │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ Linux 构建配置 │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ LINUX_SRC_DIR=${PROJECT_ROOT}/third_party/linux_mainline │ │
│ │ OUTPUT_DIR=${PROJECT_ROOT}/out/linux │ │
│ │ DEFCONFIG=imx_aes_mainline_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 板卡接入扩展
展开代码收起代码共 28 行
┌─────────────────────────────────────────────────────────────────────┐
│ 新板卡接入流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 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 扩展机制
展开代码收起代码共 26 行
┌─────────────────────────────────────────────────────────────────────┐
│ 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 驱动模块扩展
展开代码收起代码共 21 行
┌─────────────────────────────────────────────────────────────────────┐
│ 驱动模块组织 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 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_mainline | Linux 内核源码 (pin v7.1) |
third_party/uboot-imx | U-Boot 源码 |
third_party/busybox | BusyBox 源码 |
patches/linux_mainline | 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 常用脚本命令
bash
# 构建 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_mainline
# 快速构建 (跳过 distclean)
scripts/build_helper/build-linux.sh --fast-buildB. 版本控制规范
B.1 补丁命名规范
格式: [轨道类型] 简短描述
轨道类型:
- [mainline] 主线内核轨道补丁（唯一内核轨）
- [uboot-imx] U-Boot NXP fork 补丁
- [uboot-main] U-Boot 主线补丁
示例:
[mainline] arm: dts: add imx6ull aes board support
[uboot-imx] board: enable alpha boardB.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 tableC. 故障排查
C.1 常见问题
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 编译失败 | 缺少依赖 | 运行 sudo apt install ... |
| 补丁应用失败 | 版本不匹配 | 检查 submodule 版本 |
| 交叉编译错误 | 工具链未找到 | 检查 PATH 环境变量 |
| Rootfs 启动失败 | 配置文件缺失 | 运行 varified_rootfs_ok.sh |
C.2 日志级别
bash
# 启用调试输出
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 开发更简单