Zephyr

Zephyr 本工程板级定制分析

Zephyr 本工程板级定制分析

1. 定制范围

当前 Zephyr 主树中可明确识别的项目板级目录：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
boards/by/
├─ ipmc/
│  ├─ board.yml
│  ├─ ipmc.dts
│  ├─ ipmc_defconfig
│  ├─ ipmc_f103.dts
│  ├─ ipmc_f103_defconfig
│  ├─ Kconfig.ipmc
│  └─ Kconfig.ipmc_f103
├─ sct6030_lcd/
│  ├─ board.yml
│  ├─ sct6030_lcd.dts
│  ├─ sct6030_lcd_defconfig
│  └─ Kconfig.sct6030_lcd
└─ sct6030_smb/
   ├─ board.yml
   ├─ sct6030_smb.dts
   ├─ sct6030_smb_defconfig
   └─ Kconfig.sct6030_smb

此外存在项目 binding：

1
dts/bindings/ipmi/ipmi,gpio-sensor.yaml

对应应用驱动实现位于：

1
app/ipmc/sensor/gpio.c

说明项目采用“板级硬件描述放 Zephyr 主树，业务驱动放 application project”的混合组织方式。

2. board.yml

ipmc/board.yml 定义两个 board：

1
2
ipmc      → GD32F470
ipmc_f103 → STM32F103XE

sct6030_lcd 与 sct6030_smb：

1
2
vendor: olimex
SoC: stm32f103xb

这里 vendor 使用参考板厂商 olimex，而目录位于自定义 boards/by。技术上可以工作，但从维护和 board catalog 语义上看，最好为产品定义自己的 vendor prefix，避免被误认为 Olimex 官方板。

3. SCT6030 LCD

sct6030_lcd.dts 复用：

1
boards/olimex/stm32_h103/olimex_stm32_h103.dts

主要修改：

  • model：SCT6030 LCD board；
  • console/shell：USART1；
  • HSE：8 MHz；
  • PLL：mul = 27；
  • USART1 enabled。

defconfig 启用：

  • serial/console/UART console；
  • GPIO；
  • clock control；
  • pinctrl。

注意点

  1. include 使用相对路径 ../../olimex/...，对 boards 目录布局敏感；优先使用稳定 include path。
  2. compatible 仍为 olimex,stm32-h103，无法从 compatible 区分产品板。
  3. PLL 倍频必须核对 STM32F1 时钟驱动的 xtpre 语义和最终 SYSCLK，避免超频。
  4. DTS 未在本文件中定义 MCUboot partitions，若应用启用 MCUboot，应确认继承的参考板 DTS 或 overlay 提供正确布局。

4. SCT6030 SMB

sct6030_smb.dts 同样复用 STM32 H103，差异：

  • console/shell：USART2；
  • HSE disabled；
  • HSI：8 MHz enabled；
  • PLL 输入 HSI，mul = 27；
  • USART2 enabled；
  • independent watchdog enabled。

注意点

  • 内部 HSI 精度低于外部晶振，UART、时间基准和温漂需求需实测；
  • watchdog 设备 enabled 不代表应用已 setup/feed；
  • LCD 与 SMB 的 clock source 不同，共享固件配置时不能假定时钟完全一致。

5. IPMC（GD32F470）

ipmc.dts 基于：

1
gd/gd32f4xx/gd32f470vg.dtsi

chosen：

  • console/shell：USART0；
  • MCUmgr UART：USART5；
  • code partition：slot0_partition；
  • settings partition：settings_partition；
  • entropy：TRNG。

aliases：

  • mcuboot-led0；
  • watchdog0。

但当前 board DTS 中大量硬件被显式 disabled：

  • I2C0/1/2；
  • LED；
  • timer0；
  • GPIO A–E；
  • MPU/SYSCFG/EXTI；
  • USART2；
  • SPI/flash；
  • DMA；
  • watchdog；
  • TRNG。

USART5 和 internal flash 保持 enabled。

配置矛盾风险

chosen/aliases 只是引用节点，不会自动把节点改为 okay：

  • zephyr,entropy = &trng，但 &trng status = "disabled"；
  • watchdog0 = &fwdgt，但 watchdog disabled；
  • mcuboot-led0 = &led1，但 LED disabled；
  • hand_switch disabled，且其 GPIO controller 也 disabled。

这可能是“board 提供默认关闭，application overlay 再开启”的设计。每个实际应用构建都必须检查最终 zephyr.dts，不能仅看 board DTS。

6. IPMC F103

ipmc_f103.dts 复用 stm32f103_mini.dts，并覆盖：

  • SRAM：64 KiB；
  • flash：512 KiB；
  • console/shell：USART1；
  • HSE：8 MHz；
  • PLL：mul = 27；
  • GPIOA enabled，其余多组 GPIO disabled；
  • USART1 enabled；
  • UART4/UART5/I2C2 定义 pinctrl 但 disabled。

Flash layout

1
2
3
0x08000000 + 0x00000 : MCUboot  16 KiB
0x08000000 + 0x04000 : slot 0  248 KiB
0x08000000 + 0x42000 : slot 1  248 KiB

合计：

1
16 + 248 + 248 = 512 KiB

两个 slot 等大，适合常规 swap/overwrite；没有 scratch partition，因此 MCUboot 应使用 move、overwrite、direct-XIP 等无需 scratch 的模式。

关键风险

  • 16 KiB MCUboot 对启用签名、日志、串口恢复的配置可能不足，应以 boot ELF/map 验证；
  • 248 KiB slot 还需扣除 header、TLV 和 trailer；
  • STM32F1 flash page 大小、write block size 与 move swap sector 约束需核对；
  • DTS 中 write-block-size = <4> 必须与 flash driver 实际写粒度一致。

7. GPIO Sensor Binding

ipmi,gpio-sensor.yaml：

  • include ipmi,sensor.yaml；
  • gpios：phandle-array；
  • invert：boolean；
  • debounce：int，默认 0。

当前 gpios 的 required: true 被注释，但驱动无条件使用：

1
GPIO_DT_SPEC_INST_GET(n, gpios)

因此 enabled 节点若缺少 gpios 会在编译期失败。binding 应将 gpios 明确设为 required，错误信息会更直接。

8. GPIO Sensor 实例化

app/ipmc/sensor/gpio.c：

1
2
3
4
5
DT_DRV_COMPAT ipmi_gpio_sensor
→ DT_INST_FOREACH_STATUS_OKAY(SENS_DT_INIT)
→ 为每个 enabled instance 创建 gpio_sens_t
→ 读取 debounce/invert/gpios
→ SENS_INIT(...)

ipmc.dts 中 hand_switch 默认 disabled；应用 overlay 必须改为 okay 才会生成实例。

9. West Manifest 定制

zephyr/west.yml 除标准模块外还声明：

1
2
app_common → app/common
ipmc       → app/ipmc

说明应用目录也按 west project 参与 workspace。发布时应固定：

  • project remote；
  • revision；
  • path；
  • manifest repository commit。

当前片段未给这两个 project 显式 revision/remote，它们会继承 manifest defaults。若依赖纯本地目录，需确认全新 workspace 执行 west update 时仍可复现。

10. HC32/XHSC 移植

除 boards/by 外，本树还包含一套较完整的厂商移植：

1
2
3
4
5
boards/hc/hc32f4a0/
soc/xhsc/hc32f4xx/
dts/arm/xhsc/
modules/hal_xhsc/
../modules/hal/xhsc/

对应驱动覆盖 clock control、UART、flash、I2C、DMA、pinctrl、counter 和 interrupt controller 等类别。这部分不是普通 board overlay，而是从 SoC、DTS、HAL glue 到 driver 的完整移植链。

维护时应联动检查：

  • hal_xhsc west project revision；
  • SoC Kconfig 与 linker memory；
  • DTS interrupt/clock/pinctrl cells；
  • driver init priority；
  • board hc32f4a0_defconfig；
  • SDK 0.16.9 工具链兼容性。

当前 west manifest 中 hal_xhsc 未显式固定 revision，干净环境复现是主要风险。

11. BOARD=bmc 不一致

app/common/common.makefile 默认：

1
BOARD ?= bmc

但当前整个 zephyr_rtos 中未找到名称为 bmc 的 board.yml 或 bmc.dts。这意味着：

  • 默认值可能是旧板名；
  • 实际构建必须从命令行传入 board；
  • 或 board 来自未包含的外部 module。

若无外部 board root，直接使用默认值会在 CMake board 查找阶段失败。环境文档中的构建命令若未传 BOARD，应结合实际构建环境修正。

同时，当前 .west/config 的默认 board 是 ipmc。但 common.makefile 在命令中显式传入 -b $(BOARD)，所以 Makefile 的 bmc 会覆盖 west 默认值，不能依赖 .west/config 自动纠正。

12. 板级维护建议

  1. 为产品板建立正式 vendor prefix；
  2. 避免相对跨目录 include；
  3. chosen/alias 所指节点默认保持 okay，或在文档中明确 overlay 责任；
  4. binding 的驱动必需属性设为 required；
  5. 每个 board 增加 hello_world、GPIO、console 编译/运行测试；
  6. MCUboot board 增加 partition 容量和 trailer 自动检查；
  7. 固化 west project revision；
  8. 清理失效的默认 BOARD=bmc；
  9. 对 PLL、flash/SRAM 容量和 pinctrl 与原理图交叉审核；
  10. 发布保存最终 .config 和 zephyr.dts。

13. 构建核对命令

1
2
3
4
5
west boards | rg 'ipmc|sct6030'

west build -b ipmc_f103 -d build/ipmc_f103 samples/hello_world
west build -b sct6030_lcd -d build/sct6030_lcd samples/hello_world
west build -b sct6030_smb -d build/sct6030_smb samples/hello_world

查看最终硬件状态：

1
2
rg 'chosen|slot0_partition|slot1_partition|trng|fwdgt|usart' \
  build/<board>/zephyr/zephyr.dts

文章互动

阅读 --

留言

0 条留言

正在加载留言…