YAML 标记与写法

[English]

本节集中说明 BMGR 在标准 YAML 之上额外约定的几种写法，覆盖填写标记、枚举书写、${BOARD_PATH} 变量与锚点合并语法。三份板级 YAML 文件均适用。

[IO] 标记

字段注释带有 [IO] 时，表示该字段对应真实硬件引脚，必须按实际原理图填写，不能照搬示例值或模板默认值（通常为 -1）。

- name: i2c_main
  type: i2c
  config:
    sda_io_num: 10   # [IO]
    scl_io_num: 11   # [IO]

[TO_BE_CONFIRMED] 标记

字段注释带有 [TO_BE_CONFIRMED] 时，表示当前值是占位值或通用默认值，适配开发板时必须逐项确认并替换为真实值。常见于屏幕分辨率、时序参数、电压档位、I2C 地址等需要查阅器件资料才能确定的字段。

枚举值

YAML 中的枚举字段直接使用 ESP-IDF 驱动或相关组件头文件中的原始枚举名，不使用自定义字符串或数值替代。例如 GPIO 方向字段填 GPIO_MODE_OUTPUT，不填 1 或 "output"；MIPI DPI 时钟源填 MIPI_DSI_DPI_CLK_SRC_DEFAULT，不使用数值或缩写。生成器会按字符串原样输出到 C 源码，枚举名拼写错误会在编译阶段暴露。

${BOARD_PATH} 变量

${BOARD_PATH} 在开发板 YAML 中指向当前开发板定义的根目录（即包含 board_devices.yaml 的目录）。引用开发板目录下的本地组件时，建议使用该变量代替手写相对路径。gen_bmgr_codes/idf_component.yml 由 BMGR 生成，相对路径以该目录为基准展开，容易出错。${BOARD_PATH} 由 BMGR 在生成阶段统一替换，写在开发板 YAML 中语义稳定：

dependencies:
  my_company/my_driver:
    version: "*"
    override_path: ${BOARD_PATH}/packages/my_driver

备注

变量名仅识别 ${BOARD_PATH} 这一种写法。{{BOARD_PATH}}、$BOARD_PATH 等写法均不会被替换。

YAML 锚点与合并（标准 YAML）

BMGR 不限制 YAML 解析行为，因此 & 锚点、* 引用、<<: 合并等标准语法均可直接使用，常用于消除同型外设的重复配置：

peripherals:
  - name: spi_lcd
    type: spi
    version: "1.0.0"
    role: master
    config: &spi_master_default
      mosi_io_num: 11        # [IO]
      miso_io_num: -1        # 仅写入设备时不需要
      sclk_io_num: 12        # [IO]
      max_transfer_sz: 32768

  - name: spi_touch
    type: spi
    version: "1.0.0"
    role: master
    config:
      <<: *spi_master_default
      mosi_io_num: 35        # [IO]
      sclk_io_num: 36        # [IO]

此文档对您有帮助吗？