这份文档解决的是「一个 BSP 团队如何把内核从源码变成可量产固件」的问题： 它不教你怎么写某一个驱动（那是第 6 章下挂的专项子文档），而是把 环境 → 配置 → 设备树 → 驱动 → 文件系统 → 调试 → 调优 → 测试 → 发布串成一条可复用的流水线， 并把每一步的基线（源码基线 / 配置基线 / 交付基线）固化下来。 新人按 1→15 章通读一遍即可上手；老手直接翻第 15 章速查与附录 F 检查清单。 第 17–23 章是从「能跑」到「能量产、能长期维护」的七块拼图： 硬件 Bring-up、存储子系统深度、安全启动、量产支持、CI/CD、可观测性、内核生命周期—— 按项目阶段取用，不必通读。

这份文档的三条硬约束

与其它文档的分工

第 1 章 文档总览

这一章先把边界划清楚：这份文档给谁用、基于什么平台与版本、用到哪些术语、内核源码从哪来。边界不清是 BSP 项目后期返工的头号原因。

1.1 编写目的、适用范围与读者

本指南用于规范嵌入式 Linux 产品内核层（BSP）开发的全流程动作与交付标准， 目标是让不同背景的工程师在同一套基线上协作，并把「个人经验」沉淀成「团队可复用的流程」。

适用范围：基于 Linux 内核的嵌入式产品（ARM32 / ARM64 / RISC-V 均可参照）， 存储介质覆盖 SPI NOR、SPI NAND、eMMC、SD / SD NAND 等。 不适用范围：裸机 / RTOS 开发、纯用户态应用开发、芯片 RTL 设计。

1.2 平台与版本基线

版本基线必须写进文档的「第一页」，后续所有命令、补丁、配置都以此为准。 下表为示例基线，项目立项时按实际情况替换并冻结。

1.3 术语、缩写与参考文档

参考文档（详见附录 E）：内核源码树内 Documentation/、 README、各子系统 *-api.rst；芯片厂商 SDK Release Note 与 TRM； 器件 datasheet（以正式版本为准）。

1.4 内核源码来源与分支策略

内核源码只有两种来源，必须先定性再开发——它决定了后续所有补丁与升级方式。

分支管理策略（建议）

main            # 基线分支，只接受经过评审的合入，每个发布版本打 tag
release/vX.Y    # 发布分支，从 main 切出，只接受 bugfix，不再合入新特性
dev/<feature>   # 特性分支，开发者个人分支，完成后提 MR/PR 合入 main
hotfix/<issue>  # 紧急修复分支，修完同时回流 main 与对应 release 分支

第 2 章 开发环境搭建

环境是后面所有工作的地基。这一章的目标是：任何一个新人在一台干净的机器上，照着命令跑完就能编出可启动的内核。

2.1 宿主机系统与依赖包

推荐 Ubuntu 20.04 / 22.04 LTS（64 位），磁盘预留 100 GB 以上（内核源码 + 构建产物体积可观）。 以下为最小依赖集，已覆盖内核编译、menuconfig、设备树编译、模块签名等常见需求。

sudo apt update
sudo apt install -y build-essential libncurses-dev flex bison libssl-dev libelf-dev \
    bc cpio kmod rsync wget git python3 python3-pip device-tree-compiler \
    u-boot-tools zlib1g-dev liblz4-tool zstd file cscope exuberant-ctags \
    picocom minicom tftpd-hpa nfs-kernel-server openssh-server

# 调试与性能工具（第 8、9 章会用到）
sudo apt install -y trace-cmd kernelshark linux-tools-common linux-tools-generic \
    gdb-multiarch stress stress-ng iperf3 sysstat

2.2 交叉编译工具链选型

工具链必须与内核版本和目标架构同时匹配，尤其注意浮点 ABI （ARM32 的 gnueabihf 与 gnueabi 不兼容）。

# 方式一：发行版仓库安装（够用，版本较固定）
sudo apt install -y gcc-arm-linux-gnueabihf gcc-aarch64-linux-gnu

# 方式二：官方工具链（推荐，版本可控）
wget https://developer.arm.com/-/media/Files/downloads/gnu/.../arm-gnu-toolchain-*.tar.xz
sudo tar -xf arm-gnu-toolchain-*.tar.xz -C /opt
export PATH=/opt/arm-gnu-toolchain-*/bin:$PATH

# 验证（必须看到版本号与正确的 target）
arm-linux-gnueabihf-gcc --version
aarch64-linux-gnu-gcc --version

# 写入环境脚本，避免每次手敲（放在 build/env.sh，团队共用）
cat > build/env.sh <<'EOF'
export ARCH=arm
export CROSS_COMPILE=arm-linux-gnueabihf-
export PATH=/opt/arm-gnu-toolchain-13.2/bin:$PATH
export KBUILD_OUTPUT=${PWD}/build/out      # 可选：把编译产物放到独立目录
EOF
source build/env.sh

2.3 内核源码获取与补丁管理

# 主线内核（浅克隆加速，够编译即可）
git clone --depth 1 --branch v6.1 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
cd linux && git log --oneline -1

# 厂商 SDK：以原厂文档为准，一般提供完整 git 仓库或 tarball + 补丁集
# 补丁管理：所有本地修改一律做成 patch 入仓，禁止直接改源码不留痕
git format-patch -1 <commit> -o patches/       # 生成补丁
git am patches/0001-*.patch                    # 应用补丁
quilt series                                   # 若 SDK 使用 quilt 管理补丁，按其规范操作

2.4 构建系统：Buildroot / Yocto / 厂商 SDK

三者不是互斥关系，而是不同规模产品的不同选择。

2.5 内核、设备树与模块的独立编译

日常开发中，全量重编太慢，掌握「单独编」能省大量时间。

source build/env.sh

# 1) 配置（首次）
make <soc>_defconfig            # 载入芯片默认配置，例如 imx_v6_v7_defconfig
make menuconfig                 # 交互调整
make savedefconfig              # 生成精简 defconfig（提交这一个，不要提交 .config）
cp defconfig arch/arm/configs/myboard_defconfig

# 2) 编译内核与模块（-j 按 CPU 核数调整）
make -j$(nproc) zImage          # ARM32；ARM64 通常是 Image
make -j$(nproc) modules
make -j$(nproc) dtbs            # 编译全部设备树
make mysoc-myboard.dtb          # 只编指定的一个 dtb（快）

# 3) 单独编译某个外部模块
make -C /path/to/kernel M=$(pwd) modules
make -C /path/to/kernel M=$(pwd) modules_install INSTALL_MOD_PATH=/path/to/rootfs

# 4) 清理（注意别误删 .config）
make clean                      # 清目标文件
make mrproper                   # 连 .config 一起清，慎用

2.6 调试通道：串口 / TFTP / NFS / SSH

开发期强烈建议内核走 TFTP、rootfs 走 NFS，把「改一行代码」到「看到结果」压缩到一分钟内， 同时避免反复擦写 Flash 导致器件损耗。

# U-Boot 侧：网络启动内核 + NFS 根文件系统（开发期最常用）
setenv ipaddr 192.168.1.100; setenv serverip 192.168.1.10
setenv bootargs 'console=ttymxc0,115200 root=/dev/nfs nfsroot=192.168.1.10:/srv/nfs/rootfs,v3,tcp rw ip=dhcp'
tftpboot 0x80800000 zImage
tftpboot 0x83000000 myboard.dtb
bootz 0x80800000 - 0x83000000        # ARM64 用 booti

# 宿主机：把编译产物同步到 TFTP 目录
cp arch/arm/boot/zImage /srv/tftp/ && cp arch/arm/boot/dts/myboard.dtb /srv/tftp/

2.7 推荐工具集

第 3 章 内核基础原理

这一章是给新人的理论底座：搞清楚内核怎么启动、设备树起什么作用、子系统怎么分层、模块怎么加载。理解了这些，后面调驱动才知道自己在改哪一层。

3.1 内核空间与用户空间、系统调用

CPU 以特权级区分两种运行态：用户空间跑应用程序，各自拥有独立虚拟地址空间， 一旦越界访问或执行特权指令会被 MMU / CPU 拦截；内核空间所有进程共享同一份地址空间， 驱动代码就运行在这里，一处出错会影响整机。

用户态进入内核态的合法途径只有三类：系统调用（open/read/write/ioctl 等）、 异常（缺页、未定义指令）、中断（外设触发）。 驱动开发者打交道最多的是 ioctl 与 read/write 在内核侧的 file_operations 实现。

3.2 内核启动全流程

启动链路是排障的总地图。拿到一块不启动的板子，第一件事永远是看串口停在哪一步， 而不是猜。下图给出七阶段与每一步的日志特征。

3.3 设备树 DTS 原理

设备树解决的是「同一份内核如何描述不同硬件」的问题： 硬件描述（DTS）从内核代码中剥离出来，编译成 DTB 后由 Bootloader 传给内核， 内核展开成 device_node，再按 compatible 与驱动的 of_match_table 做匹配，匹配成功才调用 probe()。

3.4 内核子系统地图

下表是子系统清单与本文定位——每个子系统单独写专项文档，这里只给出职责边界与常用接口入口。

3.5 内核模块：内置 vs 动态加载

# 模块常用操作
insmod  demo.ko                 # 加载（不处理依赖）
modprobe demo                   # 加载（自动处理依赖，需先 depmod）
lsmod                           # 查看已加载模块
modinfo demo.ko                 # 查看模块信息（依赖、参数、版本）
rmmod demo                      # 卸载
cat /proc/modules               # 内核视角的模块列表

# 模块参数（驱动内 module_param 声明）
insmod demo.ko debug=1

第 4 章 内核配置与裁剪

配置裁剪是 BSP 工程师的核心工作：把几千个 CONFIG 收敛成一份可维护、可追溯、体积与启动时间都达标的基线。

4.1 .config 与 Kconfig 原理

内核配置由 Kconfig（各级目录下的配置描述）生成菜单，选择结果落在源码树根目录的 .config（CONFIG_XXX=y/m/n）。常见命令：

make <soc>_defconfig        # 载入芯片/板级默认配置（起点）
make menuconfig             # 图形化调整（需要 ncurses）
make oldconfig              # 沿用旧 .config，只提示新增项（升级内核时用）
make olddefconfig           # 同上，新增项取默认值，不交互（CI 里用这个）
make savedefconfig          # 生成精简 defconfig（只保留非默认项）→ 入仓
make nconfig / xconfig      # 其它交互前端

4.2 配置基线管理规范

1. 选起点：以最接近目标硬件的 *_defconfig 为起点，不要从零开始。
2. 调配置：用 menuconfig 调整，每改一批就记录「改了什么、为什么」。
3. 存基线：make savedefconfig 产出 defconfig，与源码同仓提交。
4. 编译验证：make -j$(nproc) 全量编译，确认无警告转错误。
5. 度量收益：记录镜像体积、启动时间、内核内存占用三项指标。
6. 写 changelog：配置变更与代码变更一样要有评审与记录（见 14.2）。

# 推荐：把 defconfig 与构建脚本一起放进项目的 build/ 目录
build/
├── env.sh                  # ARCH / CROSS_COMPILE / PATH
├── myboard_defconfig       # 配置基线（唯一来源）
├── build_kernel.sh         # 一键编译：载入 defconfig → 编译 → 拷贝产物
└── patches/                # 内核补丁集

# build_kernel.sh 关键片段
#!/bin/sh
set -e
source "$(dirname "$0")/env.sh"
cp "$1" .config || cp build/myboard_defconfig .config
make olddefconfig
make -j"$(nproc)" zImage dtbs modules
make modules_install INSTALL_MOD_PATH=../rootfs

4.3 裁剪原则与收益

裁剪的三条原则：没有对应硬件的驱动全删；量产版本关闭调试组件； 按需保留文件系统与协议栈。收益体现在体积、启动时间、内存占用与攻击面四个方面。

4.4 内核编译产出

4.5 镜像烧录与启动介质

烧录方式取决于介质与阶段：开发期用 TFTP/NFS 避免擦写； 小批量用 U-Boot 命令或 USB 烧写工具；量产用编程器或产线烧录工装。

# U-Boot 下烧录到 SPI NOR（示例，偏移按分区表调整）
sf probe 0
sf erase 0x100000 0x400000
tftpboot 0x80800000 zImage
sf write 0x80800000 0x100000 ${filesize}

# U-Boot 下烧录到 SPI NAND（需先确认坏块与 ECC 布局）
mtd list
nand erase.spread 0x200000 0x600000
nand write 0x80800000 0x200000 ${filesize}

# eMMC：通常在能启动的系统中用 dd 或专用升级工具写入分区
dd if=rootfs.ext4 of=/dev/mmcblk0p3 bs=4M conv=fsync

附录 B .config 参考配置片段

以下为常见场景的配置片段示例。写入 defconfig 时注意：defconfig 只保留非默认项，片段中的每一条都要确认与当前内核版本的选项名一致。

B.1 存储相关（裸闪存场景）

CONFIG_MTD=y
CONFIG_MTD_SPI_NOR=y
CONFIG_MTD_RAW_NAND=y            # 并行 NAND，SPI NAND 不需要这一项
CONFIG_MTD_SPI_NAND=y            # SPI NAND（走 spi-nand 框架）
CONFIG_MTD_UBI=y                 # UBI 卷管理
CONFIG_UBIFS_FS=y                # UBIFS（根文件系统必须内置）
CONFIG_MTD_BLOCK=y               # 需要 mtdblock 设备时

B.2 存储相关（块设备场景）

CONFIG_MMC=y
CONFIG_MMC_BLOCK=y
CONFIG_MMC_SDHCI=y
CONFIG_MMC_SDHCI_OF_ARASAN=y     # 按实际控制器选择
CONFIG_EXT4_FS=y                 # 或 CONFIG_F2FS_FS=y
CONFIG_SQUASHFS=y
CONFIG_OVERLAY_FS=y              # 只读底 + 可写上层的组合需要

B.3 调试相关（开发版开启，量产关闭）

CONFIG_DEBUG_KERNEL=y
CONFIG_DEBUG_INFO=y              # addr2line 需要
CONFIG_FRAME_POINTER=y           # 栈回溯更准确
CONFIG_DEBUG_FS=y                # debugfs（动态调试依赖）
CONFIG_DYNAMIC_DEBUG=y
CONFIG_FTRACE=y
CONFIG_FUNCTION_TRACER=y
CONFIG_PERF_EVENTS=y
CONFIG_KGDB=y                    # 视调试需求
CONFIG_LOCKDEP=y                 # 锁问题排查
CONFIG_DEBUG_KMEMLEAK=y          # 内存泄漏排查
CONFIG_MAGIC_SYSRQ=y             # 卡死时打印栈，强烈建议保留

B.4 量产版建议关闭 / 收紧

# CONFIG_DEBUG_KERNEL is not set
# CONFIG_KGDB is not set
# CONFIG_DEBUG_FS is not set        # 减小攻击面
# CONFIG_MODULES is not set         # 若无需现场加载模块
CONFIG_DEBUG_RODATA=y               # 只读数据不可写（按架构名可能不同）
CONFIG_STACKPROTECTOR=y
CONFIG_RANDOMIZE_BASE=y

附录 C DTS 代码样例

三份可直接改用的最小样例：SPI 存储器件、固定分区、GPIO 与中断。

C.1 SPI 存储器件 + 固定分区

&spi0 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&spi0_pins>;
    #address-cells = <1>;
    #size-cells = <0>;

    flash@0 {
        compatible = "vendor,part", "jedec,spi-nor";
        reg = <0>;
        spi-max-frequency = <50000000>;
        spi-rx-bus-width = <4>;
        #address-cells = <1>;
        #size-cells = <1>;

        partitions {
            compatible = "fixed-partitions";
            #address-cells = <1>;
            #size-cells = <1>;
            partition@0      { label = "uboot";  reg = <0x000000 0x100000>; read-only; };
            partition@100000 { label = "env";    reg = <0x100000 0x020000>; };
            partition@120000 { label = "kernel"; reg = <0x120000 0x500000>; };
            partition@620000 { label = "rootfs"; reg = <0x620000 0x900000>; };
        };
    };
};

C.2 保留内存（pstore / ramoops）

/ {
    reserved-memory {
        #address-cells = <1>;
        #size-cells = <1>;
        ranges;
        ramoops@80000000 {
            compatible = "ramoops";
            reg = <0x80000000 0x100000>;
            record-size  = <0x20000>;
            console-size = <0x20000>;
            ftrace-size  = <0x20000>;
        };
    };
};

C.3 带中断的 I2C 外设

&i2c1 {
    status = "okay";
    clock-frequency = <400000>;

    sensor@48 {
        compatible = "vendor,part";
        reg = <0x48>;
        interrupt-parent = <&gpio1>;
        interrupts = <5 IRQ_TYPE_EDGE_FALLING>;
        vdd-supply = <&reg_3v3>;          /* 电源域/供电引用 */
        wakeup-source;                    /* 允许作为唤醒源 */
    };
};

附录 D 常用调试命令脚本

四个可直接改用的脚本骨架：一键编译、启动耗时量测、存储压力与掉电测试、回归用例。

D.1 一键编译脚本

#!/bin/sh
# build/build_kernel.sh —— 用法：./build_kernel.sh [defconfig]
set -e
cd "$(dirname "$0")/.."
source build/env.sh

CFG=${1:-build/myboard_defconfig}
cp "$CFG" .config
make olddefconfig
make -j"$(nproc)" zImage dtbs modules
make modules_install INSTALL_MOD_PATH=../rootfs

mkdir -p out
cp arch/"$ARCH"/boot/zImage out/
cp arch/"$ARCH"/boot/dts/*.dtb out/
cp .config System.map vmlinux out/          # 定位 Oops 必需
sha256sum out/* > out/manifest.sha256
echo "build ok: $(git rev-parse --short HEAD)"

D.2 启动耗时量测

#!/bin/sh
# 串口时间戳量测（需 grabserial）
grabserial -d /dev/ttyUSB0 -b 115200 -e 60 -m 'login:' -t | tee boot_$(date +%s).log

# 内核侧 initcall 耗时（bootargs 追加 initcall_debug printk.time=1）
dmesg > boot_dmesg.log
scripts/bootgraph.pl boot_dmesg.log > boot.svg

D.3 存储压力与掉电测试

#!/bin/sh
# stress_storage.sh <挂载点> <轮次>
MNT=$1; N=${2:-100}
i=0
while [ $i -lt $N ]; do
    f="$MNT/dd_$i.bin"
    dd if=/dev/urandom of="$f" bs=1M count=8 conv=fsync 2>/dev/null
    sync
    a=$(sha256sum "$f" | cut -d' ' -f1)
    sync
    b=$(sha256sum "$f" | cut -d' ' -f1)
    [ "$a" = "$b" ] || echo "MISMATCH at round $i" | tee -a err.log
    rm -f "$f"
    i=$((i+1))
done
echo "done $N rounds, errors: $(wc -l < err.log 2>/dev/null || echo 0)"
# 掉电测试：配合继电器工装，在随机时刻断电后重新上电，校验 err.log 与文件系统可挂载

D.4 回归用例骨架

#!/bin/sh
# tests/run_all.sh —— 输出 PASS/FAIL 汇总，供 CI 使用
pass=0; fail=0
run() {  # run <用例名> <命令>
    if eval "$2" >/dev/null 2>&1; then echo "PASS  $1"; pass=$((pass+1));
    else echo "FAIL  $1"; fail=$((fail+1)); fi
}

run "boot_ok"        "dmesg | grep -q 'VFS: Mounted root'"
run "storage_mtd"    "cat /proc/mtd | grep -q rootfs"
run "net_ping"       "ping -c1 -W2 192.168.1.1"
run "fs_rw"          "touch /data/.t && rm /data/.t"
run "no_oom"         "! dmesg | grep -q 'Out of memory'"

echo "---- summary: PASS=$pass FAIL=$fail ----"
[ "$fail" -eq 0 ]

附录 E 参考资料与内核文档

附录 F 内核发布前检查清单

发布评审逐条过，任一条不满足都要有书面说明才能放行。建议把这份清单接入评审流程并存档。

F.1 配置与编译

• defconfig 已入仓，源码树内不提交 .config。
• 全量编译无 error；关键 warning 已确认或修复。
• 内核版本、工具链版本、U-Boot 版本与 1.2 基线表一致。
• 裁剪后镜像体积、启动时间、内存占用三项指标已记录并与基线对比。
• 根文件系统所依赖的存储与文件系统驱动为内置（非模块）。

F.2 设备树与启动

• DTS 编译无 warning；dtc -I dts -O dtb 单独验证通过。
• 板级 /proc/device-tree 节点与预期一致。
• 所有外设的 compatible 与驱动 of_match_table 已逐项核对。
• 时钟、电源域、GPIO 复用已确认（尤其新改动的节点）。
• bootargs 的 root / rootfstype / rootwait 已在实际介质上验证。

F.3 驱动与文件系统

• 所有改动过 checkpatch.pl，ERROR 清零。
• 驱动 probe / remove 配对，资源用 devm_* 或手工释放完整。
• suspend / resume（含 Runtime PM）已验证，唤醒后外设功能正常。
• 文件系统参数（UBIFS / ubinize）与 mtdinfo 实测值一致。
• 存储读写循环测试通过，无数据不一致。

F.4 调试配置与量产配置

• 量产版本已关闭 kgdb / ftrace / debugfs 等调试组件（若策略如此）。
• 保留 CONFIG_MAGIC_SYSRQ 等现场救命项。
• 看门狗已启用，喂狗周期覆盖最长阻塞操作。
• pstore / 日志持久化已验证：死机后重启能取到现场。
• panic 自动重启策略（kernel.panic）已设置。

F.5 OTA 与可靠性

• A/B 分区（或等效回滚机制）已验证：升级中断电可自愈。
• 升级包 sha256 与签名校验已验证；写入后回读比对通过。
• 掉电测试已跑够轮次（数百次），数据完整性通过。
• 回滚后启动标记清理正确，不会出现双槽反复横跳。
• 回滚动作不擦除共享 data 区。

F.6 交付与文档

• 源码 tag / commit id 已记录，构建可复现。
• vmlinux、System.map、.config 已归档。
• manifest（版本号 + sha256）随镜像一起交付。
• changelog 与 Known Issues 已更新，每条 Known Issue 有规避方案或修复计划。
• 第 13 章测试报告（含性能基准对比）已产出并归档。
• 烧录与升级说明文档已交付给产线与售后。