从野火到正点原子：手把手教你为Zephyr RTOS适配一块新的STM32开发板

从零开始为Zephyr RTOS适配STM32开发板的完整指南

引言

在嵌入式系统开发领域，实时操作系统(RTOS)已成为资源受限设备的首选解决方案。Zephyr RTOS作为一款专为物联网设备设计的开源实时操作系统，以其轻量级、模块化和高度可配置的特性赢得了广泛关注。然而，当开发者拿到一块Zephyr官方尚未支持的开发板时，如何从零开始为其添加支持成为了一项关键技能。

本文将深入探讨为Zephyr RTOS适配新STM32开发板的完整流程，特别针对国内流行的野火、正点原子等开发板型号。不同于简单的功能实现，我们将从硬件抽象层模型出发，系统性地讲解board、soc、dts配置文件的创建方法，重点解析设备树(DTS)编写与Kconfig配置的实战技巧。通过LED、按键、UART等外设的具体示例，帮助开发者掌握硬件移植的核心方法论，填补官方支持之外的空白。

1. Zephyr硬件支持架构解析

1.1 六层硬件抽象模型

Zephyr采用分层架构设计硬件支持，将硬件抽象划分为六个清晰层级：

这种分层设计使得硬件支持具有高度可扩展性，开发者可以根据目标硬件选择适当的抽象层级进行适配。

1.2 开发板与SoC的关系

以STM32为例，其硬件层级关系如下：

STM32 SoC Family ├── STM32F4 Series │ ├── STM32F401 SoC │ ├── STM32F429 SoC │ │ ├── 野火STM32F429挑战者开发板 │ │ └── 正点原子STM32F429阿波罗开发板 └── STM32G4 Series ├── STM32G474 SoC └── STM32G484 SoC

理解这种层级关系对后续创建正确的硬件描述文件至关重要。

2. 开发环境准备与工程结构

2.1 工具链安装与配置

为开始Zephyr开发，需要准备以下工具：

# 安装west工具 pip install west # 初始化工作区 west init ~/zephyrproject cd ~/zephyrproject west update # 安装依赖 west zephyr-export pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

2.2 Zephyr源码结构关键目录

了解Zephyr源码结构对硬件适配至关重要：

zephyrproject/ ├── zephyr/ # Zephyr主仓库 │ ├── arch/ # 架构相关代码 │ ├── boards/ # 板级支持包 │ │ └── arm/ # ARM架构开发板 │ ├── drivers/ # 设备驱动 │ ├── dts/ # 设备树绑定 │ ├── include/ # 公共头文件 │ ├── soc/ # SoC支持代码 │ └── samples/ # 示例代码 ├── modules/ # 外部模块 └── build/ # 构建目录

2.3 创建自定义板级支持目录

为新的STM32开发板创建支持，需要在boards/arm/下建立对应目录：

mkdir -p ~/zephyrproject/zephyr/boards/arm/my_stm32_board

3. 设备树(DTS)配置实战

3.1 设备树基础概念

设备树是描述硬件的分层数据结构，主要包含：

• 设备树源(.dts/.dtsi)：硬件描述文件
• 设备树绑定(.yaml)：描述节点内容与数据类型的规范

构建系统会将这些文件转换为C头文件供内核使用。

3.2 创建基础设备树文件

为STM32开发板创建my_stm32_board.dts：

/dts-v1/; #include <st/stm32f429xi.dtsi> / { model = "My Custom STM32F429 Board"; compatible = "mycompany,my-stm32-board", "st,stm32f429"; chosen { zephyr,console = &usart1; zephyr,sram = &sram0; zephyr,flash = &flash0; }; leds { compatible = "gpio-leds"; led0: led_0 { gpios = <&gpioc 13 GPIO_ACTIVE_HIGH>; label = "User LED"; }; }; buttons { compatible = "gpio-keys"; button0: button_0 { gpios = <&gpioa 0 GPIO_ACTIVE_LOW>; label = "User Button"; }; }; }; &usart1 { current-speed = <115200>; status = "okay"; };

3.3 关键设备树属性解析

3.4 设备树绑定示例

创建my-leds.yaml绑定文件：

description: My custom LED configuration compatible: "gpio-leds" include: base.yaml properties: label: type: string required: false description: LED label gpios: type: phandle-array required: true description: GPIO specifier for the LED

4. Kconfig系统配置详解

4.1 Kconfig基础结构

Zephyr使用Kconfig进行系统配置，主要文件包括：

1. Kconfig.board：板级特有配置选项
2. Kconfig.defconfig：默认配置设置
3. my_stm32_board_defconfig：板级默认配置

4.2 创建板级Kconfig文件

Kconfig.board示例内容：

config BOARD_MY_STM32_BOARD bool "My Custom STM32 Board" depends on SOC_STM32F429XX select HAS_DTS select HAS_DTS_GPIO select HAS_DTS_UART

my_stm32_board_defconfig示例内容：

CONFIG_GPIO=y CONFIG_SERIAL=y CONFIG_UART_CONSOLE=y CONFIG_UART_ASYNC_API=y

4.3 Kconfig与设备树联动

Kconfig可以通过预处理函数访问设备树信息：

config FLASH_BASE_ADDRESS hex "Flash base address" default $(dt_chosen_reg_addr_hex,flash)

5. SoC与板级支持实现

5.1 创建SoC支持文件

在soc/arm/st_stm32/stm32f4/中添加SoC特定支持：

/* pinmux.c */ static const struct pin_config pinconf[] = { {STM32_PIN_PA9, STM32F4_PINMUX_FUNC_PA9_USART1_TX}, {STM32_PIN_PA10, STM32F4_PINMUX_FUNC_PA10_USART1_RX}, }; static int pinmux_init(const struct device *port) { ARG_UNUSED(port); for (int i = 0; i < ARRAY_SIZE(pinconf); i++) { stm32_pinmux_set(pinconf[i].pin_num, pinconf[i].mode); } return 0; } SYS_INIT(pinmux_init, PRE_KERNEL_1, 0);

5.2 板级初始化代码

创建board.c实现板级初始化：

#include <init.h> #include <drivers/gpio.h> static int board_init(const struct device *dev) { ARG_UNUSED(dev); const struct device *gpio = DEVICE_DT_GET(DT_NODELABEL(gpioc)); if (!device_is_ready(gpio)) { return -ENODEV; } gpio_pin_configure(gpio, 13, GPIO_OUTPUT_ACTIVE); return 0; } SYS_INIT(board_init, POST_KERNEL, CONFIG_APPLICATION_INIT_PRIORITY);

6. 外设驱动适配实战

6.1 LED驱动适配

基于设备树中定义的LED节点，实现LED控制：

#define LED_NODE DT_ALIAS(led0) static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED_NODE, gpios); void blink_led(void) { if (!device_is_ready(led.port)) { return; } bool val = true; while (1) { gpio_pin_set(led.port, led.pin, (int)val); val = !val; k_msleep(500); } }

6.2 UART控制台配置

确保设备树中UART配置正确后，可通过以下方式使用：

const struct device *uart = DEVICE_DT_GET(DT_CHOSEN(zephyr_console)); void send_uart(const char *msg) { if (!device_is_ready(uart)) { return; } for (const char *p = msg; *p != '\0'; p++) { uart_poll_out(uart, *p); } }

6.3 按键中断实现

配置按键中断处理：

#define BUTTON_NODE DT_ALIAS(button0) static const struct gpio_dt_spec button = GPIO_DT_SPEC_GET(BUTTON_NODE, gpios); static void button_pressed(const struct device *dev, struct gpio_callback *cb, uint32_t pins) { printk("Button pressed at %" PRIu32 "\n", k_cycle_get_32()); } static struct gpio_callback button_cb; void init_button(void) { if (!device_is_ready(button.port)) { return; } gpio_pin_configure(button.port, button.pin, GPIO_INPUT | GPIO_PULL_UP); gpio_pin_interrupt_configure(button.port, button.pin, GPIO_INT_EDGE_FALLING); gpio_init_callback(&button_cb, button_pressed, BIT(button.pin)); gpio_add_callback(button.port, &button_cb); }

7. 构建与调试技巧

7.1 构建配置与编译

使用west工具进行构建：

# 创建构建目录 west build -b my_stm32_board samples/hello_world # 启用menuconfig调整配置 west build -t menuconfig # 编译工程 west build

7.2 烧录与调试

# 烧录固件 west flash # 启动调试会话 west debug # 查看串口输出 west espressif monitor

7.3 常见问题排查

1. 设备树错误：

   • 使用dts工具验证设备树语法
   • 检查.dts文件是否包含正确的SoC头文件

2. Kconfig问题：

   • 通过guiconfig界面检查依赖关系
   • 确认defconfig文件中的关键选项已启用

3. 驱动初始化失败：

   • 检查设备树节点status是否为"okay"
   • 验证时钟配置是否正确

4. 内存不足：

   • 调整CONFIG_HEAP_MEM_POOL_SIZE
   • 优化功能配置减少内存占用

8. 高级适配技巧

8.1 添加自定义外设支持

对于非标准外设，需要创建自定义驱动：

1. 在drivers/目录下创建新驱动目录
2. 实现标准的设备驱动接口
3. 创建对应的设备树绑定
4. 添加Kconfig配置选项

8.2 电源管理集成

为支持低功耗特性：

#include <pm/device.h> static int my_device_pm_action(const struct device *dev, enum pm_device_action action) { switch (action) { case PM_DEVICE_ACTION_SUSPEND: /* 进入低功耗模式 */ break; case PM_DEVICE_ACTION_RESUME: /* 退出低功耗模式 */ break; default: return -ENOTSUP; } return 0; } PM_DEVICE_DT_DEFINE(DT_NODELABEL(my_device), my_device_pm_action);

8.3 多核支持配置

对于多核STM32芯片：

cpus { #address-cells = <1>; #size-cells = <0>; cpu0: cpu@0 { device_type = "cpu"; compatible = "arm,cortex-m7"; reg = <0>; }; cpu1: cpu@1 { device_type = "cpu"; compatible = "arm,cortex-m4"; reg = <1>; }; };

9. 测试与验证

9.1 单元测试集成

创建测试用例验证硬件功能：

#include <ztest.h> void test_led(void) { const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED_NODE, gpios); zassert_true(device_is_ready(led.port), "LED device not ready"); gpio_pin_set(led.port, led.pin, 1); zassert_equal(gpio_pin_get(led.port, led.pin), 1, "LED state mismatch"); } void test_main(void) { ztest_test_suite(my_board_tests, ztest_unit_test(test_led) ); ztest_run_test_suite(my_board_tests); }

9.2 硬件验证清单

完成适配后应验证以下功能：

1. [ ] 系统时钟配置正确
2. [ ] 控制台UART输出正常
3. [ ] 用户LED可控制
4. [ ] 用户按键中断响应
5. [ ] 所有外设功能正常
6. [ ] 低功耗模式工作正常
7. [ ] 内存使用在合理范围内

10. 贡献回馈社区

10.1 准备提交内容

向Zephyr上游贡献适配代码需要包含：

1. 完整的板级支持目录
2. 设备树绑定文件
3. 测试用例
4. 文档更新

10.2 提交流程

1. Fork Zephyr项目仓库
2. 创建特性分支进行开发
3. 提交Pull Request
4. 根据评审意见修改
5. 等待合并

10.3 文档编写指南

提供清晰的板级文档：

# My STM32 Board ## Overview Brief description of the board ## Features - List of hardware features ## Supported Features - Zephyr features supported on this board ## Programming and Debugging Instructions for flashing and debugging ## References - [Board Website](http://example.com) - [Schematic](http://example.com/schematic.pdf)

11. 实战案例：正点原子STM32F429适配

11.1 创建板级目录结构

zephyr/boards/arm/atk_stm32f429 ├── board.cmake ├── Kconfig.board ├── Kconfig.defconfig ├── atk_stm32f429_defconfig ├── atk_stm32f429.dts ├── atk_stm32f429.yaml └── support/ └── atk_stm32f429.c

11.2 关键设备树配置

#include <st/stm32f429xi.dtsi> / { model = "ATK STM32F429 Apollo"; compatible = "alientek,atk-stm32f429", "st,stm32f429"; chosen { zephyr,console = &usart1; zephyr,sram = &sram0; zephyr,flash = &flash0; zephyr,ccm = &ccm0; }; leds { compatible = "gpio-leds"; led0: led_0 { gpios = <&gpiog 13 GPIO_ACTIVE_HIGH>; label = "LED0"; }; led1: led_1 { gpios = <&gpiog 14 GPIO_ACTIVE_HIGH>; label = "LED1"; }; }; gpio_keys { compatible = "gpio-keys"; key0: key_0 { gpios = <&gpioa 0 GPIO_ACTIVE_LOW>; label = "KEY0"; }; }; aliases { led0 = &led0; led1 = &led1; sw0 = &key0; }; }; &usart1 { current-speed = <115200>; status = "okay"; }; &i2c1 { status = "okay"; clock-frequency = <I2C_BITRATE_STANDARD>; }; &spi2 { status = "okay"; cs-gpios = <&gpiob 12 GPIO_ACTIVE_LOW>; };

11.3 外设驱动验证代码

#include <zephyr.h> #include <drivers/gpio.h> #include <drivers/uart.h> #define LED0_NODE DT_ALIAS(led0) #define LED1_NODE DT_ALIAS(led1) #define BUTTON_NODE DT_ALIAS(sw0) static const struct gpio_dt_spec led0 = GPIO_DT_SPEC_GET(LED0_NODE, gpios); static const struct gpio_dt_spec led1 = GPIO_DT_SPEC_GET(LED1_NODE, gpios); static const struct gpio_dt_spec button = GPIO_DT_SPEC_GET(BUTTON_NODE, gpios); static struct gpio_callback button_cb; void button_pressed(const struct device *dev, struct gpio_callback *cb, uint32_t pins) { gpio_pin_toggle(led0.port, led0.pin); } void main(void) { if (!device_is_ready(led0.port) || !device_is_ready(led1.port) || !device_is_ready(button.port)) { return; } gpio_pin_configure(led0.port, led0.pin, GPIO_OUTPUT_INACTIVE); gpio_pin_configure(led1.port, led1.pin, GPIO_OUTPUT_INACTIVE); gpio_pin_configure(button.port, button.pin, GPIO_INPUT | GPIO_PULL_UP); gpio_pin_interrupt_configure(button.port, button.pin, GPIO_INT_EDGE_FALLING); gpio_init_callback(&button_cb, button_pressed, BIT(button.pin)); gpio_add_callback(button.port, &button_cb); while (1) { gpio_pin_toggle(led1.port, led1.pin); k_msleep(1000); } }

12. 性能优化与调试

12.1 内存配置优化

调整内存区域定义：

/ { soc { sram0: memory@20000000 { compatible = "mmio-sram"; reg = <0x20000000 DT_SIZE_K(192)>; }; ccm0: memory@10000000 { compatible = "mmio-sram"; reg = <0x10000000 DT_SIZE_K(64)>; }; }; };

12.2 中断优先级配置

优化中断响应：

#include <irq.h> void configure_interrupts(void) { IRQ_CONNECT(DT_IRQN(DT_NODELABEL(usart1)), DT_IRQ(DT_NODELABEL(usart1), priority), usart1_isr, NULL, 0); irq_enable(DT_IRQN(DT_NODELABEL(usart1))); }

12.3 电源管理集成

实现低功耗模式：

#include <pm/pm.h> #include <pm/device.h> #include <pm/policy.h> static const struct pm_state_info states[] = { {PM_STATE_SUSPEND_TO_IDLE, 0, 10000}, {PM_STATE_STANDBY, 0, 5000}, }; void configure_power_management(void) { pm_policy_state_lock_get(PM_STATE_SUSPEND_TO_IDLE, PM_ALL_SUBSTATES); for (int i = 0; i < ARRAY_SIZE(states); i++) { pm_policy_state_add(0, &states[i], NULL); } }

13. 多板级支持与代码复用

13.1 共享SoC级配置

通过dtsi文件复用配置：

// stm32f4-common.dtsi #include <st/stm32f4.dtsi> / { soc { usart1: serial@40011000 { compatible = "st,stm32-usart"; reg = <0x40011000 0x400>; clocks = <&rcc STM32_CLOCK_BUS_APB2 0x00004000>; interrupts = <37 0>; status = "disabled"; }; }; };

13.2 板级覆盖配置

在板级dts中覆盖默认设置：

#include "stm32f4-common.dtsi" &usart1 { status = "okay"; current-speed = <115200>; };

13.3 Kconfig配置继承

使用source语句复用配置：

# boards/arm/stm32_common/Kconfig config STM32_COMMON_FEATURE bool "Common STM32 feature" default y help This is a feature shared by all STM32 boards.

在板级Kconfig中引用：

source "../stm32_common/Kconfig" config BOARD_MY_STM32 bool "My STM32 Board" depends on SOC_STM32F4

14. 调试技巧与工具链

14.1 OpenOCD配置

创建板级OpenOCD配置文件：

# board/stm32f4discovery.cfg source [find interface/stlink-v2.cfg] source [find target/stm32f4x.cfg] reset_config srst_only adapter speed 2000

14.2 GDB调试技巧

常用GDB命令：

# 启动GDB会话 arm-none-eabi-gdb build/zephyr/zephyr.elf # 在GDB中常用命令 (gdb) target remote :3333 (gdb) monitor reset halt (gdb) load (gdb) b main (gdb) c

14.3 日志与追踪

配置系统日志：

CONFIG_LOG=y CONFIG_LOG_BUFFER_SIZE=4096 CONFIG_LOG_DEFAULT_LEVEL=3

使用日志系统：

#include <logging/log.h> LOG_MODULE_REGISTER(my_module, LOG_LEVEL_DBG); void my_function(void) { LOG_DBG("Debug message"); LOG_ERR("Error occurred: %d", err_code); }

15. 持续集成与自动化测试

15.1 GitHub Actions配置

自动化构建测试：

name: Zephyr Build Test on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: '3.8' - name: Install dependencies run: | pip install west west init -m https://github.com/zephyrproject-rtos/zephyr cd zephyr west update west zephyr-export pip install -r scripts/requirements.txt - name: Build for my_stm32_board run: | west build -b my_stm32_board samples/hello_world

15.2 测试用例编写

创建硬件相关测试：

#include <ztest.h> #include <drivers/gpio.h> static void test_led_gpio(void) { const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios); zassert_true(device_is_ready(led.port), "LED device not ready"); /* Test LED toggle */ gpio_pin_set(led.port, led.pin, 1); zassert_equal(gpio_pin_get(led.port, led.pin), 1, "LED set high failed"); gpio_pin_set(led.port, led.pin, 0); zassert_equal(gpio_pin_get(led.port, led.pin), 0, "LED set low failed"); } void test_main(void) { ztest_test_suite(hardware_tests, ztest_unit_test(test_led_gpio) ); ztest_run_test_suite(hardware_tests); }

16. 安全考虑与最佳实践

16.1 安全启动配置

确保安全启动设置：

CONFIG_BOOTLOADER_MCUBOOT=y CONFIG_SECURE_BOOT=y CONFIG_HW_STACK_PROTECTION=y

16.2 内存保护单元(MPU)配置

启用MPU保护：

CONFIG_ARM_MPU=y CONFIG_MPU_STACK_GUARD=y CONFIG_APPLICATION_MEMORY=y

16.3 安全固件更新

实现安全OTA更新：

CONFIG_IMG_MANAGER=y CONFIG_MCUBOOT_IMG_MANAGER=y CONFIG_IMG_ENABLE_IMAGE_CHECK=y

17. 社区资源与进一步学习

17.1 官方资源

• Zephyr项目文档
• GitHub仓库
• 开发者邮件列表

17.2 推荐书籍

1. 嵌入式实时操作系统Zephyr开发实战
2. Mastering Zephyr RTOS
3. STM32与Zephyr实战指南

17.3 在线课程

• Zephyr官方培训课程
• Udemy上的Zephyr RTOS实战
• Coursera嵌入式系统专项课程

18. 未来发展与路线图

18.1 Zephyr 3.0新特性

1. 增强的多核支持
2. 改进的电源管理框架
3. 更丰富的驱动生态系统

18.2 硬件支持扩展计划

1. 更多国产芯片支持
2. AI加速器集成
3. 无线协处理器支持

18.3 社区参与建议

1. 从文档改进开始贡献
2. 参与驱动开发工作
3. 分享适配经验与案例