🤖 roboto_origin_03 Wiki
首页 / 固件 / 板卡配置与内核编译

本文档深入解析 Orange Pi 构建系统中板卡配置的层级化架构与内核编译的完整流水线。作为构建系统的核心子系统，板卡配置决定了目标硬件的 SoC 族系、内核分支、引导加载器策略及设备树选择；内核编译则负责源码获取、补丁应用、配置生成与 Debian 包封装的完整闭环。理解这两个子系统的工作机理，是进行深度定制、添加新板卡支持或调试构建失败的前提。

板卡配置的层级化架构

Orange Pi 构建系统采用四层配置模型，通过分层覆写机制将硬件共性抽象与板级差异分离。配置加载顺序从具体到通用依次为：用户配置 → 板卡配置 → 族系配置 → 架构配置，后加载的变量可覆盖前者。

第一层：板卡定义 (external/config/boards/*.conf) 是配置入口的最小单元，以 robopi1.conf 为例，其声明了板卡显示名称、所属 SoC 族系、U-Boot 默认配置、内核目标分支及设备树文件名等关键属性。BOARDFAMILY 变量是连接板卡与族系配置的桥梁，系统据此加载对应的族系配置脚本。

第二层：族系配置 (external/config/sources/families/*.conf) 实现了同 SoC 平台的共享定义。以 RK3588 平台为例，rockchip-rk3588.conf 通过 case $BRANCH 结构为 legacy、current、develop 三个内核分支分别定义了内核源码仓库、分支名、补丁目录 (KERNELPATCHDIR) 及内核配置文件名 (LINUXCONFIG)。族系配置还会引入 include/rockchip64_common.inc 等公共片段，进一步抽取跨族系的通用逻辑如串口控制台参数、DVFS 频率范围、引导场景 (BOOT_SCENARIO) 及 RK 二进制 blobs 路径。

第三层：架构配置 (external/config/sources/${ARCH}.conf) 设定了目标架构的默认参数，如默认交叉编译器前缀、内核镜像类型 (KERNEL_IMAGE_TYPE)、页大小及字节序等。

第四层：用户覆写 (userpatches/config-*.conf 与 userpatches/lib.config) 允许构建者在不修改上游配置的前提下，通过环境变量注入或事后 source 加载的方式覆盖任意中间变量。构建系统在执行脚本中通过 call_extension_method 插入了多个钩子点（如 post_family_config、user_config），使扩展和用户逻辑能够在配置聚合的精确时机介入。

以下 Mermaid 图展示了从 build.sh 启动到配置完全就绪的调用链与数据流：

flowchart TD
    A[build.sh] -->|source| B[scripts/main.sh]
    B -->|source| C[scripts/configuration.sh]
    C -->|source| D[boards/BOARD.conf]
    D -->|BOARDFAMILY| E[families/LINUXFAMILY.conf]
    E -->|include| F[common.inc]
    E -->|source| G[sources/ARCH.conf]
    C -->|initialize| H[Extension Manager]
    H -->|hooks| I[post_family_config<br/>user_config]
    C -->|aggregate| J[Package Lists]

Sources: build.sh, main.sh, configuration.sh, robopi1.conf, rockchip-rk3588.conf

配置解析与变量推导

在 scripts/configuration.sh 中，系统完成板卡与族系配置的加载后，进入变量推导与校验阶段。此阶段的核心任务是将高层的抽象配置（如 BOARD、BRANCH）转化为编译阶段可直接使用的技术参数（如 BOOTCONFIG、LINUXCONFIG、KERNELBRANCH）。

启动配置推导：BOOTCONFIG_VAR_NAME 采用间接变量引用模式，根据当前分支名构造变量名（如 BOOTCONFIG_LEGACY），若族系配置中定义了该变量，则将其赋值给 BOOTCONFIG。这使得同一板卡在不同分支下可使用不同的 U-Boot 默认配置。

内核配置推导：LINUXCONFIG 的默认值按 linux-${LINUXFAMILY}-${BRANCH} 规则生成，但族系配置中通过条件覆盖为具体板卡提供了独立的内核配置文件名。例如 RK3588 族系为 robopi1 板卡在 legacy 分支指定了 linux-rockchip-rk3588-legacy-robopi1.config，在 current 分支指定了 linux-rockchip-rk3588-current-robopi1.config。这种粒度确保了板卡级硬件差异（如特定外设引脚复用）不会污染同族系其他板卡的通用配置。

路径与镜像参数：BOOTSOURCEDIR 和 LINUXSOURCEDIR 通过 branch2dir 函数将 BOOTBRANCH/KERNELBRANCH 中的 branch: 或 tag: 前缀去除，映射到 external/cache/sources 下的具体子目录。CHOSEN_UBOOT、CHOSEN_KERNEL 等变量则按固定命名模板生成，用于后续编译产物查找与缓存命中判定。

Sources: configuration.sh, rockchip-rk3588.conf, main.sh

内核编译流水线

内核编译由 scripts/compilation.sh 中的 compile_kernel() 函数驱动，其流水线可分为源码准备、补丁应用、配置生成、编译与打包四个阶段。

源码准备：系统首先根据 CLEAN_LEVEL 决定是否执行 make clean。若启用 USE_OVERLAYFS，则通过 overlayfs_wrapper 将原始源码目录与可写覆盖层组合，保证原始源码的纯净并支持并行构建不同目标。随后 grab_version 从内核源码 Makefile 中提取主版本、补丁级、子级及 RC 标识，用于后续版本比较与包名生成。

补丁应用：构建系统支持两类补丁机制。其一为系列补丁，若 external/patch/kernel/${KERNELPATCHDIR}/series.conf 存在，则按该文件列出的顺序批量应用。其二为层级化目录补丁，由 advanced_patch 函数实现，其按优先级从 8 个候选目录中收集 .patch 文件：用户补丁优先级高于官方补丁，且细分了 target_、board_、branch_ 三个维度。补丁冲突时可通过 EXIT_PATCHING_ERROR 变量控制是否终止构建。

配置生成：系统按以下优先级选取内核配置：先前构建保留的配置 (DEST/config/) > 用户自定义配置 (userpatches/) > 官方默认配置 (external/config/kernel/)。若 KERNEL_CONFIGURE=yes，则依次调用 oldconfig 与 menuconfig，并将最终配置导出至 DEST/config/ 与 external/config/kernel/ 两处，兼顾了用户调试与上游同步需求。call_extension_method "custom_kernel_config" 钩子允许扩展在配置落盘后直接修改 .config。

编译与打包：内核通过 make 构建 Image、modules 与 dtbs。对于 Linux 4.3+ 使用 bindeb-pkg 目标生成 Debian 包，产出包含 linux-image、linux-headers、linux-dtb 的三个独立 deb 包。特殊平台如 sun60iw2 还会在此阶段编译外部 GPU 内核模块并安装至临时目录。构建完成后产物经 rsync 转移至 output/debs/。

flowchart LR
    subgraph 源码准备
        A1[CLEAN_LEVEL<br/>判断] --> A2[OverlayFS<br/>包装]
    end
    subgraph 补丁应用
        B1[series.conf<br/>系列补丁] --> B2[advanced_patch<br/>层级补丁]
    end
    subgraph 配置生成
        C1[配置优先级<br/>判定] --> C2[olddefconfig<br/>静默更新] --> C3[menuconfig<br/>交互式可选]
    end
    subgraph 编译打包
        D1[Image+modules+dtbs] --> D2[bindeb-pkg] --> D3[rsync至<br/>output/debs]
    end
    A2 --> B1
    B2 --> C1
    C3 --> D1

Sources: compilation.sh, general.sh

交叉编译工具链管理

构建系统对工具链的管理体现为自动发现与版本约束相结合的策略。find_toolchain 函数遍历 ${SRC}/toolchains/*/bin/ 目录，筛选出前缀匹配（如 aarch64-linux-gnu-）且 GCC 版本满足表达式约束（如 > 10.0、< 8.0）的工具链。在存在多个候选时，选取与目标版本号欧氏距离最小者，确保在系统默认编译器与项目需求之间取得平衡。

工具链的下载由 prepare_host 函数在构建初始化阶段完成。根据目标 BOARDFAMILY，系统从预定义的清单中选择需要下载的 Linaro/ARM GNU 工具链压缩包，支持通过 BitTorrent 加速获取。对于 RK3588 等 arm64 平台，U-Boot 编译器与内核编译器可能采用不同版本约束（如 U-Boot 要求 < 8.0 而内核要求 > 10.0），find_toolchain 的独立调用确保了二者各自匹配到最优工具链。

Sources: compilation.sh, general.sh

源码获取与缓存策略

fetch_from_repo 函数封装了对 Git 仓库的浅克隆与增量更新逻辑。其支持四种引用类型：branch:、tag:、head、commit:。对于分支类型，默认采用 --depth 200 的浅抓取以节省带宽与磁盘空间；若引用类型为 commit 且远程不支持直接抓取，则自动回退至全克隆。

该函数还内建了变更检测机制：通过比较本地 HEAD 哈希与远程引用哈希，仅在发生变更时执行 fetch 与 checkout，否则直接判定为 "Up to date"。当工作目录存在未跟踪文件或修改时（如先前补丁应用遗留），函数通过 git checkout -f 与 git clean -qdf 强制还原至追踪文件的干净状态。子模块则通过递归调用 fetch_from_repo 同步更新。

在 main.sh 的 do_default 流程中，fetch_from_repo 按构建目标 (BUILD_OPT) 条件触发：仅当构建 u-boot 或 image 时拉取 U-Boot 源码，仅当构建 kernel 或 image 时拉取内核源码，避免了不必要的网络操作。

Sources: general.sh, main.sh

构建入口与产物缓存

构建系统通过 main.sh 中的交互式菜单或配置文件中的预定义变量确定构建参数。当 BUILD_OPT 为 kernel 时，系统跳过根文件系统相关步骤，仅执行 compile_kernel；当为 image 时，依次编译 U-Boot、内核、BSP 包并最终组装镜像。编译产物以 Debian 包形式缓存于 output/debs/，命名遵循 ${CHOSEN_KERNEL}_${REVISION}_${ARCH}.deb 的固定模式。若缓存包已存在且未强制清理，则直接复用，显著缩短迭代构建时间。

构建完成后，main.sh 会输出一行可复现构建命令，将本次使用的所有参数（BOARD、BRANCH、BUILD_OPT、RELEASE 等）以键值对形式打印，便于 CI/CD 集成或问题复现。

Sources: main.sh, main.sh

扩展阅读

Generated from zread wikis · roboto_origin_03