添加覆盖层

设备树覆盖层用于启用外设，并选择其引脚和设置。s31-overlay 工具可以在 Linux 运行时加载这些描述，也可以保存选择，在下次启动时恢复。

1. 创建覆盖层

创建 esp32s31-overlay-NAME.dtso，放在 linux-esp32-s31/arch/riscv/boot/dts/espressif/ 下。可以从类似设备的现有覆盖层开始修改。完整的 I2C0 覆盖层包含头部、资源声明、pinctrl 节点和控制器设置。

覆盖层需要设备树插件头部和 espressif,overlay-name。新覆盖层应使用新名称。如果它使用的控制器、DMA 通道或其他资源不能与别的覆盖层共享，应添加 espressif,resource-claims。例如，I2C0 覆盖层的开头如下：

/dts-v1/;
/plugin/;

/ {
    espressif,overlay-name = "i2c0";
    espressif,resource-claims = "i2c0";
};

资源列表是可选的。需要同一独占资源的覆盖层应使用相同的资源声明名称，让管理器能够检测冲突。对于 pinmux 条目尚未描述的固定引脚，使用 espressif,gpio-claims 声明。

2. 添加设备和引脚设置

用 status = "okay" 启用控制器，并提供其 pinctrl 状态。按需添加时钟、复位、DMA 通道、稳压器、PHY 或子设备。

要允许用户选择 GPIO，在引脚节点上设置 espressif,route-name 和 espressif,route-kind。支持的类型为 matrix-input、matrix-output 和 matrix-bidirectional。如果一个节点有多条分别命名的路由，则使用对应的 espressif,route-names 和 espressif,route-kinds 列表。

例如，I2C0 覆盖层导出 i2c0.scl 和 i2c0.sda。用户可以运行 s31-overlay routes i2c0 查看它们，并在应用覆盖层时选择引脚。

要开放数值设置，需声明属性名及允许值：

&i2c0 {
    espressif,param-name = "clock-frequency";
    espressif,param-values = <100000 400000 1000000>;
    clock-frequency = <100000>;
    status = "okay";
};

这样，工具就会接受 clock-frequency=400000，并拒绝列表之外的值。完整的覆盖层还需要包含控制器的 pinctrl 配置。

3. 构建并安装

将覆盖层的 .dtbo 目标添加到内核目录下的 arch/riscv/boot/dts/espressif/Makefile，并将 NAME 替换为你的覆盖层名称：

dtb-$(CONFIG_ARCH_ESPRESSIF) += esp32s31-overlay-NAME.dtbo

然后在主项目中构建并烧录完整匹配镜像集。按烧录指南选择端口并准备串口连接：

make image
make flash-existing-all PORT=/dev/ttyUSB0

DTBO 生成在 out/linux/arch/riscv/boot/dts/espressif/ 中，并安装到根文件系统的 /usr/lib/s31-overlays。开发时直接复制到运行中开发板的文件，是否能在重启后继续使用，需遵循部署规则。

4. 在开发板上测试

更新镜像后，查看覆盖层设置，并尝试临时应用它。将 i2c0 替换为你的覆盖层名称：

s31-overlay routes i2c0
s31-overlay parameters i2c0
s31-overlay apply i2c0 --volatile
s31-overlay status
dmesg

测试外设，关闭使用它的程序，再移除覆盖层：

s31-overlay remove i2c0 --volatile

还应尝试有冲突的引脚选择和无效参数值。正常流程通过后，省略 --volatile 再次应用，并重启检查是否恢复。测试失败情况时，保存选择和回滚的行为见使用覆盖层。