[Zephyr] Zephyr SDK Glue 开发指南

3 周 ago
                            16 次浏览
HPMicro
4 minutes

本文档提供完整的 Zephyr SDK Glue 开发环境搭建、代码拉取、工程构建和烧录的详细步骤。

目录

概述

Zephyr SDK Glue 是 HPMicro 基于 Zephyr RTOS 开发的清单仓库，包含 HPMicro MCU 适配 Zephyr 的所有源程序文件。与 HPMicro 官方软件开发包（HPM_SDK）共同组成完整的 Zephyr 开发套件。

项目特点

  • 独立清单文件：以 Glue 仓库为起点获取所有所需源码
  • 基于 HPM_SDK：实时更新HPM_SDK最新版本驱动
  • 版本绑定：目前基于 Zephyr v3.7.0 (LTS) 版本

项目结构

workspace/
├── sdk_glue/          # SDK Glue 主目录
│   ├── boards/        # 开发板支持
│   ├── cmake/         # CMake 脚本
│   ├── drivers/       # 驱动文件
│   ├── dts/           # 设备树文件
│   ├── samples/       # 示例程序
│   └── soc/           # SoC 相关文件
├── zephyr/            # Zephyr RTOS 源码
├── sdk_env/           # HPM SDK 环境
│   ├── hpm_sdk/       # HPM SDK 源码
│   └── toolchains/    # 工具链
└── build/             # 构建输出目录

环境搭建

Linux 环境搭建

1. 系统要求

  • 操作系统：Ubuntu 18.04 或更高版本（推荐 Ubuntu 20.04/22.04）
  • Shell：Bash

2. 安装依赖工具

更新软件包列表并安装必要的依赖：

sudo apt update
sudo apt upgrade

安装开发工具：

sudo apt install --no-install-recommends git cmake ninja-build gperf \
    ccache dfu-util device-tree-compiler wget \
    python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
    make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

3. 验证工具版本

确保以下工具满足最低版本要求：

工具 最低版本
CMake 3.20.5
Python 3.8
Devicetree compiler 1.4.6

检查版本：

cmake --version
python3 --version
dtc --version

如果版本不满足要求，需要升级相应工具。

4. 安装 West 工具

West 是 Zephyr 项目的多仓库管理工具：

pip3 install --user -U west

将 ~/.local/bin 添加到 PATH 环境变量：

echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc

验证安装：

west --version

5. 安装 OpenOCD（可选）

Linux 环境下需要自行安装 hpmicro riscv-openocd，在系统路径下查找所使用的openocd。

Windows 环境搭建

1. 使用 Chocolatey 安装工具

安装 Chocolatey：

打开 PowerShell（以管理员身份运行）：

Set-ExecutionPolicy AllSigned
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

配置 Chocolatey：

打开 cmd.exe：

choco feature enable -n allowGlobalConfirmation

安装开发工具：

choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
choco install ninja gperf python git dtc-msys2 wget 7zip

安装完成后，重启 cmd.exe 使环境变量生效。

2. 安装 West 工具

pip3 install -U west

3. 安装 FT2232 驱动（用于调试）

如果使用 FT2232 调试器，需要安装相应的驱动程序。

代码拉取

1. 创建工作空间

选择一个合适的位置创建工作空间目录：

Linux：

mkdir ${workspace}
cd ${workspace}

Windows：

mkdir %workspace%
cd %workspace%

2. 初始化 West 工作空间

使用 Glue 仓库作为清单源初始化工作空间：

Linux/Windows：

west init -m https://github.com/hpmicro/zephyr_sdk_glue.git --mr main

3. 配置清单文件（可选）

如果需要使用国内镜像源（Gitee），可以切换到 Gitee 清单：

west config manifest.file west_gitee.yml

4. 拉取所有源码

更新所有子仓库：

west update

此命令目前会拉取以下仓库：

  • zephyr：Zephyr RTOS 源码
  • sdk_env：HPM SDK 环境（包含 hpm_sdk 和工具链）
  • canopennode：CANopen 协议栈
  • lvgl：LVGL 图形库
  • CherryUSB：USB 协议栈
  • fatfs：FAT 文件系统
  • mcuboot：MCUboot 引导程序

5. 导出 Zephyr 环境

配置 CMake 变量：

west zephyr-export

6. 安装 Python 依赖

安装 Zephyr 所需的 Python 包：

Linux：

pip3 install --user -r ~/${workspace}/zephyr/scripts/requirements.txt

Windows：

pip3 install -r %workspace%\zephyr\scripts\requirements.txt

7. 应用 HPM SDK 补丁

应用 HPM SDK 相关的补丁：

west supply

工具链配置

安装 Zephyr SDK

Zephyr SDK 包含编译工具链和调试工具。

Linux 安装

cd ${workspace}
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.5/zephyr-sdk-0.16.5_linux-x86_64.tar.xz
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.5/sha256.sum | shasum --check --ignore-missing
tar xvf zephyr-sdk-0.16.5_linux-x86_64.tar.xz
cd zephyr-sdk-0.16.5
source setup.sh

Windows 安装

cd %workspace%
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.5/zephyr-sdk-0.16.5_windows-x86_64.7z
7z x zephyr-sdk-0.16.5_windows-x86_64.7z
cd zephyr-sdk-0.16.5
setup.cmd

使用自定义工具链（zcc）

如果需要使用 zcc 工具链，需要设置相应的环境变量：

export ZEPHYR_TOOLCHAIN_VARIANT=zcc
export ZCC_TOOLCHAIN_PATH=~/sdk_env/toolchains/zcc-4.1.7/
export TOOLCHAIN_ROOT=~/aa_diskext/ZSG/sdk_glue/

或者使用提供的脚本：

source sdk_glue/zcc.sh

更多关于工具链切换的信息，请参考 工具链切换机制文档。

工程构建

基本构建命令

使用 west build 命令构建工程：

west build -p always -b <BOARD> <SOURCE_DIR>

参数说明：

  • -p always：强制清理并重新构建（auto 为增量编译）
  • -b ：指定目标开发板
  • ``：源代码目录路径

构建示例

示例 1：构建 button 示例

cd ${workspace}/zephyr
west build -p always -b hpm6750evk2 samples/basic/button

示例 2：使用 Snippet

某些示例支持硬件特定的配置选项（snippet）：

west build -p always -b hpm6750evk2 -S blinky_pwm samples/basic/blinky_pwm

示例 3：指定构建目录

west build -p always -b hpm6750evk2 -d build/my_build samples/basic/button

查看支持的开发板

列出所有支持的开发板：

Linux：

west boards | grep hpm

Windows：

west boards | findstr hpm

使用 CMake 直接构建

也可以直接使用 CMake 和 Ninja：

cmake -GNinja -B build -DBOARD=hpm6750evk2 samples/basic/button
ninja -C build

Kconfig 配置

使用菜单配置系统：

west build -t menuconfig

或者从构建目录：

cd build
ninja menuconfig

构建选项说明

选项 说明
-p always 清理构建目录并重新构建
-p auto 自动检测是否需要清理（默认）
-p never 不清理，仅增量编译
-c / --cmake 强制重新运行 CMake
-t 指定构建目标（如 menuconfig）
-d 指定构建目录
-S 使用硬件配置片段

构建输出

构建成功后，生成的文件位于构建目录中：

  • zephyr/zephyr.elf：ELF 格式可执行文件
  • zephyr/zephyr.hex：HEX 格式文件
  • zephyr/zephyr.bin：二进制文件
  • zephyr/zephyr.map：链接映射文件

烧录与调试

烧录程序

使用 west flash

从构建目录烧录：

west flash

从任意位置指定构建目录：

west flash --build-dir path/to/build/directory

烧录选项

查看支持的烧录选项：

west flash --context

选择烧录器（Runner）

如果开发板支持多种烧录方式，可以指定：

west flash --runner openocd

调试程序

启动调试会话

west debug

这会启动 GDB 调试会话并连接到目标板。

启动调试服务器

如果需要使用 IDE 或其他调试工具连接：

west debugserver

这会启动 GDB 服务器，默认监听端口 3333。

指定调试器

west debug --runner openocd
west debugserver --runner openocd

调试选项

查看调试选项：

west debug --context
west debugserver --context

手动烧录

如果不想使用 west flash，可以手动使用 OpenOCD 或其他工具：

使用 OpenOCD：

openocd -f board/hpmicro_hpm6750evk2.cfg -c "program zephyr/zephyr.hex verify reset exit"

使用其他工具：

构建目录中包含了各种格式的二进制文件，可以使用任何支持的工具进行烧录。

常见问题

1. 构建失败：找不到工具链

问题： 构建时提示找不到编译器或工具链。

解决方案：

  1. 确认已安装 Zephyr SDK 并运行了 setup.sh（Linux）或 setup.cmd（Windows）
  2. 检查环境变量是否正确设置
  3. 如果使用自定义工具链，确认 ZEPHYR_TOOLCHAIN_VARIANT 和工具链路径正确

2. west update 失败

问题： 拉取代码时网络超时或失败。

解决方案：

  1. 使用国内镜像源：

    west config manifest.file west_gitee.yml
west update

  2. 检查网络连接和代理设置

  3. 手动克隆仓库后使用 west update 更新

3. 找不到开发板

问题： west build 提示找不到指定的开发板。

解决方案：

  1. 确认开发板名称正确：

    west boards | grep hpm

  2. 检查是否在正确的工作空间中

  3. 确认已正确执行 west update 和 west zephyr-export

4. 烧录失败

问题： west flash 无法连接到目标板。

解决方案：

  1. 检查调试器连接（USB 线、驱动等）
  2. 确认开发板已上电
  3. 检查 OpenOCD 配置是否正确
  4. 尝试手动启动 OpenOCD 查看详细错误信息

5. Python 版本问题

问题： 某些 Python 脚本无法运行。

解决方案：

  1. 确认 Python 版本 >= 3.8
  2. 安装所有必需的依赖： 
    pip3 install --user -r zephyr/scripts/requirements.txt

6. Windows 路径长度限制

问题： Windows 10 默认路径长度限制可能导致构建失败。

解决方案：

  1. 启用长路径支持（需要管理员权限）
  2. 将工作空间放在靠近根目录的位置（如 D:\workspace）
  3. 缩短构建输出路径

7. 增量编译问题

问题： 修改代码后重新编译，更改未生效。

解决方案：

使用 -p always 强制清理构建：

west build -p always -b <BOARD> <SOURCE_DIR>

8. 查看详细构建信息

问题： 需要查看详细的编译命令和输出。

解决方案：

使用 verbose 模式：

west -v build -b <BOARD> <SOURCE_DIR>

或者设置 CMake 变量：

west build -b <BOARD> -- -DCMAKE_VERBOSE_MAKEFILE=ON

快速参考

常用命令速查

# 初始化工作空间
west init -m https://github.com/hpmicro/zephyr_sdk_glue.git --mr main

# 更新代码
west update

# 导出环境
west zephyr-export

# 应用补丁
west supply

# 构建工程
west build -p always -b hpm6750evk2 samples/basic/button

# 烧录
west flash

# 调试
west debug

# 查看开发板
west boards | grep hpm

# 配置菜单
west build -t menuconfig

参考资源

0
0

订阅

发表回复 0

Your email address will not be published. Required fields are marked *

captcha
Enter the characters shown in the image:
Reload

This CAPTCHA helps ensure that you are human. Please enter the requested characters.