Zephyr rtos ESP32系列BSP提交流程指南

Sean_woo19982025-12-23 8:53

基于成功提交 esp32c3_lckfb BSP 的经验总结

📋 目录

  1. 准备工作
  2. 文件结构
  3. 必需文件详解
  4. CI合规性检查
  5. 提交流程
  6. 常见问题与解决方案

准备工作

1. 环境准备

bash 复制代码 
# 1. 克隆Zephyr仓库
git clone https://github.com/zephyrproject-rtos/zephyr.git
cd zephyr

# 2. 添加upstream远程仓库
git remote add upstream https://github.com/zephyrproject-rtos/zephyr.git

# 3. 确保在最新的main分支
git checkout main
git pull upstream main

2. 确定BSP位置

  • 官方Espressif开发板 : boards/espressif/<board_name>/
  • 第三方开发板 : boards/others/<board_name>/

3. 参考现有BSP

建议参考同系列SOC的现有BSP，例如：

  • ESP32-C3: boards/espressif/esp32c3_devkitc/
  • ESP32-S3: boards/espressif/esp32s3_devkitc/

文件结构

标准BSP目录结构

复制代码 
boards/
└── others/                    # 或 espressif/
    └── esp32c3_lckfb/         # 板级名称
        ├── board.yml          # 板级元数据（必需）
        ├── <board>.yaml       # 板级YAML定义（必需）
        ├── Kconfig            # 板级Kconfig（必需）
        ├── Kconfig.<board>    # 板级特定配置（可选）
        ├── Kconfig.sysbuild   # Sysbuild配置（可选）
        ├── board.cmake        # CMake配置（必需）
        ├── <board>_defconfig  # 默认配置（必需）
        ├── <board>.dts        # 设备树源文件（必需）
        ├── <board>-pinctrl.dtsi  # 引脚控制配置（必需）
        ├── doc/               # 文档目录
        │   ├── index.rst      # 板级文档（必需）
        │   └── img/           # 图片目录
        │       └── <board>.webp  # 板级图片（推荐WebP格式，<100KB）
        └── support/           # 支持文件（可选）
            └── openocd.cfg    # OpenOCD配置

必需文件详解

1. board.yml - 板级元数据

yaml 复制代码 
board:
  name: esp32c3_lckfb
  full_name: ESP32-C3 Development Board (LCKFB)
  vendor: others              # 或 "espressif"（官方板）
  socs:
  - name: esp32c3

注意:

  • 必须包含SPDX许可证头
  • vendor: others 用于第三方开发板
  • vendor: espressif 用于官方开发板

2. <board>.yaml - 板级YAML定义

yaml 复制代码 
identifier: esp32c3_lckfb
name: ESP32-C3 (LCKFB)
type: mcu
arch: riscv
toolchain:
  - zephyr
supported:
  - adc
  - gpio
  - i2c
  - i2s
  - watchdog
  - uart
  - dma
  - pwm
  - spi
  - counter
  - entropy
  - crypto
  - retained_mem
vendor: others

注意:

  • 必须包含SPDX许可证头
  • supported 列表必须与实际硬件功能匹配
  • 按字母顺序排序

3. Kconfig - 板级Kconfig

kconfig 复制代码 
# SPDX-License-Identifier: Apache-2.0

config BOARD_ESP32C3_LCKFB
	bool "ESP32-C3 Development Board (LCKFB)"
	depends on SOC_ESP32C3

注意:

  • 必须包含SPDX许可证头
  • 版权年份应为当前年份（2025）
  • 无尾随空行

4. <board>.dts - 设备树源文件

dts 复制代码 
/*
 * Copyright (c) 2025 LCKFB
 * SPDX-License-Identifier: Apache-2.0
 */

#include <espressif/esp32c3.dtsi>
#include "esp32c3_lckfb-pinctrl.dtsi"

/ {
	chosen {
		zephyr,console = &uart0;
		zephyr,shell-uart = &uart0;
	};

	/* 板级特定配置 */
};

&uart0 {
	status = "okay";
	current-speed = <115200>;
	pinctrl-0 = <&uart0_default>;
	pinctrl-names = "default";
};

/* Flash大小覆盖（如需要） */
&flash0 {
	reg = <0x0 DT_SIZE_M(8)>;
};

注意:

  • 必须包含SPDX许可证头
  • 版权年份应为当前年份
  • 无尾随空行和尾随空格
  • 引脚配置应在 -pinctrl.dtsi 文件中

5. <board>-pinctrl.dtsi - 引脚控制配置

dts 复制代码 
/*
 * Copyright (c) 2025 LCKFB
 * SPDX-License-Identifier: Apache-2.0
 */

#include <zephyr/dt-bindings/pinctrl/esp32c3-pinctrl.h>

&pinctrl {
	uart0_default: uart0_default {
		group1 {
			pinmux = <UART0_TX_GPIO21>;
		};
		group2 {
			pinmux = <UART0_RX_GPIO20>;
			bias-pull-up;
		};
	};
};

注意:

  • 使用 <zephyr/dt-bindings/...> 路径，不是 <dt-bindings/...>
  • 检查引脚冲突（如SPI和TWAI共用引脚）
  • 无尾随空行

6. board.cmake - CMake配置

cmake 复制代码 
# SPDX-License-Identifier: Apache-2.0

board_runner_args(openocd --file ${CMAKE_CURRENT_LIST_DIR}/support/openocd.cfg)
include(${ZEPHYR_BASE}/boards/common/openocd.board.cmake)

7. <board>_defconfig - 默认配置

kconfig 复制代码 
CONFIG_SOC_ESP32C3=y
CONFIG_BOARD_ESP32C3_LCKFB=y

8. doc/index.rst - 板级文档

rst 复制代码 
.. zephyr:board:: esp32c3_lckfb

Overview
********

The LCKFB ESP32-C3 is a feature-rich development board...

Hardware
********

.. include:: ../../../espressif/common/soc-esp32c3-features.rst
   :start-after: espressif-soc-esp32c3-features

Supported Features
==================

.. zephyr:board-supported-hw::

System Requirements
*******************

.. include:: ../../../espressif/common/system-requirements.rst
   :start-after: espressif-system-requirements

Programming and Debugging
*************************

.. zephyr:board-supported-runners::

.. include:: ../../../espressif/common/building-flashing.rst
   :start-after: espressif-building-flashing

.. include:: ../../../espressif/common/board-variants.rst
   :start-after: espressif-board-variants

Debugging
=========

.. include:: ../../../espressif/common/openocd-debugging.rst
   :start-after: espressif-openocd-debugging

References
**********

.. target-notes::

.. _`LCKFB ESP32-C3 Development Board`: https://wiki.lckfb.com/zh-hans/szpi-esp32c3/

注意:

  • 必须包含最终换行符
  • 图片路径使用相对路径 ../../../espressif/common/
  • 图片格式推荐WebP，大小<100KB

CI合规性检查

1. SPDX许可证头

所有文件必须包含：

c 复制代码 
/*
 * SPDX-FileCopyrightText: Copyright (c) 2025 <Your Name/Company>
 * SPDX-License-Identifier: Apache-2.0
 */

或对于YAML文件：

yaml 复制代码 
# SPDX-FileCopyrightText: Copyright (c) 2025 <Your Name/Company>
# SPDX-License-Identifier: Apache-2.0

2. 文件格式检查

  • ✅ 无尾随空行: 文件末尾不应有多余空行
  • ✅ 无尾随空格: 行末不应有空格
  • ✅ 版权年份: 新文件使用当前年份（2025）
  • ✅ 最终换行符: 文件末尾必须有单个换行符

3. 排序检查

  • ✅ CMakeLists.txt: 条目按字母顺序排序
  • ✅ Kconfig: 配置项按字母顺序排序
  • ✅ YAML文件: 列表项按字母顺序排序

4. 图片大小检查

  • ✅ 图片格式: 推荐WebP格式
  • ✅ 图片大小: <100KB
  • ✅ 图片位置 : doc/img/<board>.webp

5. Gitlint检查

  • ✅ 提交信息格式: 符合Zephyr规范
  • ✅ Signed-off-by: 必须包含，格式正确
  • ✅ 作者信息: Author name必须与Signed-off-by匹配

6. 设备树检查

  • ✅ 引脚冲突: 检查引脚复用冲突
  • ✅ 包含路径 : 使用 <zephyr/dt-bindings/...> 格式
  • ✅ Flash配置: 如需要，明确指定Flash大小

提交流程

步骤1: 创建新分支

bash 复制代码 
cd zephyr
git checkout -b boards-others-esp32c3-lckfb  # 或 boards-espressif-<board>

步骤2: 创建BSP文件

按照上述文件结构创建所有必需文件。

步骤3: 本地验证

bash 复制代码 
# 编译测试
west build -b esp32c3_lckfb samples/hello_world

# 检查代码风格
./scripts/checkpatch.pl --git <commit-range>

步骤4: 提交代码

bash 复制代码 
# 添加文件
git add boards/others/esp32c3_lckfb/

# 提交（单个提交）
git commit -s -m "boards: others: add esp32c3_lckfb board support

Add board support for LCKFB ESP32-C3 Development Board.

This board is based on ESP32-C3 with 8MB SPI flash and includes:
- Wi-Fi and Bluetooth Low Energy support
- Complete pin configuration for UART, I2C, SPI2, I2S
- OpenOCD debugging support
- Board documentation with WebP image (optimized size)

Signed-off-by: Your Name <your.email@example.com>"

重要:

  • 使用 -s 自动添加Signed-off-by
  • 确保Author name与Signed-off-by匹配
  • 单个提交包含所有更改

步骤5: 推送到远程

bash 复制代码 
# 推送到fork仓库
git push origin boards-others-esp32c3-lckfb

步骤6: 创建Pull Request

  1. 在GitHub上创建PR
  2. 填写PR描述
  3. 等待CI检查

步骤7: 修复CI错误

根据CI错误逐一修复：

bash 复制代码 
# 修复后更新提交
git add .
git commit --amend --no-edit
git push --force-with-lease origin boards-others-esp32c3-lckfb

步骤8: 响应审查意见

  • 及时回复审查者
  • 按要求修改代码
  • 合并提交（如需要）: git rebase -i HEAD~N

常见问题与解决方案

问题1: SPDX许可证头缺失

错误 : File has no SPDX-License-Identifier header

解决: 在所有文件开头添加SPDX许可证头

问题2: 尾随空行/空格

错误 : Trailing blank lines / Trailing whitespace

解决:

bash 复制代码 
# 检查并修复
sed -i 's/[[:space:]]*$//' <file>
# 删除文件末尾多余空行

问题3: 作者信息不匹配

错误 : author name and email needs to match one of the signed-off-by entries

解决:

bash 复制代码 
git commit --amend --author="Your Name <your.email@example.com>" --no-edit

问题4: 图片过大

错误 : Image file too large (>100kB)

解决:

  • 转换为WebP格式
  • 压缩图片大小
  • 删除原PNG文件

问题5: 引脚冲突

错误: 编译错误或运行时问题

解决:

  • 检查设备树中的引脚复用
  • 移除冲突的节点（如TWAI与SPI共用引脚）
  • 在文档中说明限制

问题6: 包含路径错误

错误 : 编译错误 No such file or directory

解决:

  • 使用 <zephyr/dt-bindings/...> 而不是 <dt-bindings/...>
  • 检查路径是否正确

问题7: 排序问题

错误 : Sorted block has out-of-order line

解决:

  • 在CMakeLists.txt、Kconfig、YAML中按字母顺序排序
  • 使用工具自动排序

问题8: 多个提交需要合并

审查者要求: "Please make it single commit"

解决:

bash 复制代码 
# 交互式rebase合并提交
git rebase -i HEAD~N
# 将后续提交标记为 'squash'
# 保存并编辑合并后的提交信息
git push --force-with-lease origin <branch>

最佳实践

  1. 参考现有BSP: 从同系列SOC的现有BSP开始
  2. 单个提交: 将所有更改包含在单个提交中
  3. 完整测试: 本地编译和测试通过后再提交
  4. 文档完善: 提供清晰的板级文档和图片
  5. 及时响应: 快速响应审查意见和CI错误
  6. 保持同步: 定期从upstream/main拉取更新

检查清单

提交PR前确认：

  • 所有文件包含SPDX许可证头
  • 无尾随空行和尾随空格
  • 版权年份为当前年份
  • 文件末尾有单个换行符
  • 图片格式为WebP，大小<100KB
  • 所有列表项按字母顺序排序
  • 设备树引脚配置正确，无冲突
  • 包含路径使用正确格式
  • 提交信息符合Zephyr规范
  • Author name与Signed-off-by匹配
  • 本地编译测试通过
  • 文档完整且格式正确

参考资源

相关推荐
polarislove02142 小时前
8.2 时钟树编程-嵌入式铁头山羊STM32笔记
笔记·stm32·嵌入式硬件
AI_56782 小时前
STM32开发的效率跃迁
stm32·单片机·嵌入式硬件
旧梦吟3 小时前
脚本网页 linux内核源码讲解
linux·前端·stm32·算法·html5
进阶的猪13 小时前
STM32 使用HAL库SPI读写FLASH（W25Q128JV）数据 Q&A
c语言·stm32·单片机
就是蠢啊17 小时前
51单片机——DAC数模转换实验（一）
单片机·嵌入式硬件·51单片机
就是蠢啊18 小时前
51单片机——ADC数模转换实验（二）
单片机·嵌入式硬件·51单片机
田甲19 小时前
EasyScale单总线数字调光
单片机·嵌入式硬件
电子工程师-C5119 小时前
基于51单片机的环境监测及窗帘控制系统
单片机·嵌入式硬件·51单片机
星一工作室19 小时前
STM32项目分享：基于stm32的旋转书架
stm32·单片机·嵌入式硬件
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03Linux下V2Ray安装配置指南04在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06Labelme从安装到标注：零基础完整指南07CentOS的ISO镜像下载08BongoCat - 跨平台键盘猫动画工具09jdk21下载、安装（Windows、Linux、macOS）10NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南