构建配置

所有构建均使用同一套完整开发板配置，包含 Wi-Fi、蓝牙、USB、I2C、SPI、I2S、以太网、SD/MMC 等原生控制器驱动。无需选择构建变体。可选硬件通过运行时覆盖层启用。

make build
make image

构建输出、暂存文件和报告位于 out/，最终镜像位于 out/images/。同一个输出目录的写入由构建锁串行化。共享下载及工具链保留在 cache/。发布的匹配镜像集位于 dist/<build-id>/；验证成功后才会更新 dist/current。

完整配置包含 S31 控制器及必要的 Linux 框架，但不会自动包含每一种外接 SPI 屏幕、USB HID 设备或 USB 声卡的驱动。

源码配置

文件

设置

linux-esp32-s31/arch/riscv/configs/esp32s31_defconfig

原生开发板默认选项

configs/kernel/common.config、configs/kernel/board.config

完整内核配置

configs/kernel/debug.config

DEBUG=1 时增加的诊断选项

mk/config.mk

构建路径、工具链、内核命令行和配置片段选择

buildroot-external/configs/esp32s31_rootfs_defconfig

根文件系统软件包和系统选项

buildroot-external/board/esp32-s31/busybox.fragment

BusyBox 工具，包括网络校时

configs/esp32-config-timezones.list

镜像中保留的时区

buildroot-external/board/esp32-s31/post-build.sh

最终根文件系统的安装与精简策略

需要长期保留的更改应写入源码配置。内核配置输入变化时，会重新生成 out/linux/.config；输入标识未变化时，保留原生增量构建行为。已有 Buildroot 输出中的软件包或工具链配置输入变化时，构建会要求运行 make buildroot-reconfigure 后重建，下载缓存仍保留。

先用 make fetch 准备 Buildroot 输出，再打开配置菜单并导出供审查的配置副本：

make buildroot-menuconfig
make -C buildroot O="$PWD/out/buildroot" \
  BR2_EXTERNAL="$PWD/buildroot-external" \
  savedefconfig DEFCONFIG="$PWD/out/generated/buildroot-menu.defconfig"

将需要的软件包和系统选项从该文件合入 buildroot-external/configs/esp32s31_rootfs_defconfig。不要把已解析的主机专用 BR2_TOOLCHAIN_EXTERNAL_PATH 或暂存目录的 BR2_ROOTFS_OVERLAY 路径写回源码；主构建会在配置时注入这些值。审查源码差异后，分别运行 make buildroot-reconfigure、make fetch-rootfs 和 make image。这也会清理手工改过的输出配置；主构建会拒绝直接复用该配置。额外应用仍需在 Buildroot 中单独选择，参见添加用户空间工具。最终内核选项的核对方法见内核配置。

体积优化

目标代码使用原生构建接口进行体积优化，不修改上游构建算法：

  • Linux 使用 CONFIG_CC_OPTIMIZE_FOR_SIZE=y，并通过逐目标 CFLAGS 将开发板的速度优化例外及 LZ4 调整为 -Os。jitterentropy 熵源保留其强制要求的 -O0。

  • U-Boot/SPL 使用原生体积优化配置，包括库优化。

  • OpenSBI 在原生 Makefile 之后加载补充 Makefile，在保留 ISA/ABI 选项的同时追加 -Os。

  • Buildroot 使用 BR2_OPTIMIZE_S=y；项目应用继承 TARGET_CFLAGS。CoreMark 通过原生 PORT_CFLAGS/XCFLAGS 接口构建，并保留两个 pthread。

  • ESP-IDF 无线和 LP 固件使用原生 SIZE 配置；LP 和项目无线 C 源码使用 -Os。

主机工具保留各自的优化设置。供应商二进制库、工具链运行库和继承的根文件系统二进制不会因此重新编译。重打包基线 rootfs 时，必须将继承代码的优化状态标记为未验证。汇编指令序列不变；CoreMark 性能需要重新建立基准，代码更小并不保证更快。

完整 XIP 内核使用 6 MiB（6,291,456 字节）分区；ext4 和 JBD2 保持内置。镜像必须通过体积检查；超出预算会直接失败，不会自动禁用驱动或发布超大镜像。影响内核体积的更改需要明确修改源码配置并重新验证。

make image 成功后，检查本次发布产物的实际大小，不要依赖其他构建记录中的数值：

stat -c %s dist/current/xipImage

实际大小及清单对应具体的源码和配置；主机体积检查通过不代表硬件启动成功。

内核导出符号裁剪

默认启用 CONFIG_TRIM_UNUSED_KSYMS=y。内核保留同次构建中的模块所引用的导出符号，并通过 CONFIG_UNUSED_KSYMS_WHITELIST 保留外部 XIP 无线载荷所需的导入。构建从载荷生成 out/generated/radio-kernel-symbols.txt，其内容随载荷输入重新生成；原生内核配置使用该文件的绝对路径。用以下命令查看自己构建生成的列表行数：

wc -l out/generated/radio-kernel-symbols.txt

不能清空白名单，否则可能裁掉运行时所需的导出。

此设置不承诺未来模块或树外模块的 ABI。新增模块应与内核一起构建，或明确将必要导出加入原生白名单，然后重新检查分区预算及模块加载。

镜像中的配置工具

镜像包含 esp32-config、GPIO 服务和配置备份。网络校时客户端由 BusyBox 提供。启动时存在已保存的 GPIO 配置才启动 GPIO 服务；自动校时和开机程序初始为关闭。

post-build 根据最终内核配置生成 /usr/share/esp32-config/kernel-features，菜单据此提供接口和 USB 功能。存储功能也会检查运行系统中的文件系统驱动。内核与 rootfs 必须来自同一个匹配镜像集。

添加时区时，修改 configs/esp32-config-timezones.list；若来源区域尚未包含，还需在 Buildroot defconfig 的 BR2_TARGET_TZ_ZONELIST 中加入该区域，然后重新构建 rootfs。

无线模式

集成构建始终生成 Wi-Fi/蓝牙组合载荷。板端通过 esp32-config wifi enable|disable 和 esp32-config bluetooth enable|disable 保存策略并重新加载无线服务；重新加载可能断开活动连接。

已启用的服务

运行时模式

覆盖层

仅 Wi-Fi

wifi

radio-wifi

仅蓝牙

bt

radio-bluetooth

两者均启用

combo

radio-combo

两者均未启用

停止无线模块

移除无线覆盖层配置

当前 mac80211 前端只提供一个 STA 接口；完整开发板配置不会增加 AP 支持。参见无线接口和开发板配置。