先楫半导体 HPM_SDK 使用 VSCode（CMake）开发指南

示例环境

示例环境：WSL Arch Linux + VSCode（Remote WSL），日期：2026/1/10。其它 Linux 发行版思路类似，只是包管理命令不同。

前言

目前先楫半导体主要推荐使用 SEGGER Embedded Studio 进行开发，可以免费进行商业应用。但对于习惯使用 VS Code 的开发者来说，配置一个 VS Code + CMake 的开发环境也是可行的。本文档旨在提供一个基于 VS Code 使用 HPM SDK 进行开发的参考指南，涵盖环境准备、工具链配置、CMake 设置等方面的内容。

在进入正题之前，首先需要明确的是无论 SEGGER Embedded Studio 还是 VS Code，都只是一个开发环境，并不绑定具体的编译器。针对 HPM6800 系列，常见可用的交叉编译器包括（但不限于）：

编译器前缀	说明	获取方式
riscv32-unknown-elf	官方 GNU RISC‑V 工具链（通用），可用于构建 newlib/glibc 多种 multilib 版本，使用时可能需要根据 HPM SDK 做少量适配（链接脚本、启动文件等）。	GitHub
riscv32-unknown-elf（厂商/SDK 修改）	HPM 或厂商发布的定制版工具链，通常包含针对板级支持包（BSP）、专用启动文件与预构建库，便于开箱即用。	随 HPM SDK 或厂商发布包获取（查看 SDK 文档）
NDSGCC (`nds-gnu-toolchain`)	Andes 提供的定制 GNU 工具链，包含对 Andes ISA/厂商扩展的支持，仓库提供源码、子模块与一组 `build_*` 脚本，可构建 newlib 或 glibc 目标；适合基于 Andes 内核的芯片/板卡。	GitHub
ZCC	Terapines（兆松科技）基于 LLVM 的 RISC‑V 编译器，支持 RV32/RV64 与大量标准/厂商扩展（包括向量/加密等），提供 GUI/CLI 安装器与产品管理器，社区版可直接使用，商业版有许可证管理。文档包含支持的 ISA、安装方式、multilib 与常见兼容性提示（与 GCC/ld 的差异）。	文档下载/Installer

准备工作

关于 NDSGCC 与 ZCC 的补充说明

NDSGCC（Andes nds-gnu-toolchain）

仓库：https://github.com/andestech/nds-gnu-toolchain。
常见目标前缀示例：nds32le-elf-*, nds64le-elf-*（对应 rv32/rv64、不同 ABI 与 multilib）。
快速构建提示：

git clone https://github.com/andestech/nds-gnu-toolchain.git
cd nds-gnu-toolchain
git submodule update --init --recursive
./build_elf_toolchain.sh

ZCC（Terapines）

文档/下载：文档，下载/Installer。
ZCC 基于 LLVM（文档版面指出基于 LLVM 19.x），支持 RV32/RV64、丰富的标准扩展与厂商扩展（向量 RVV、加密/位操作、供应商自定义扩展等）。
建议：首次在 HPM SDK 上试用 ZCC 时，先用最小示例（hello world）验证链接与运行时（如 newlib/semihost/nosys）行为，再将复杂示例迁移，必要时调整链接脚本与启动文件。

环境准备（概览）

Windows

安装 VSCode，并安装 Remote - WSL 插件用于在 WSL 中开发。

WSL

建议使用 Arch（本文基于 Arch 测试），在 WSL 内安装构建工具和交叉编译器。

工具链

使用厂商或 AUR 提供的 RISC‑V / ARM 交叉编译器，根据目标平台选择对应的工具链二进制包或源码构建。

VSCode 与推荐扩展

推荐安装（至少）：

Remote - WSL (ms-vscode-remote.remote-wsl)
C/C++ (ms-vscode.cpptools)
CMake Tools (ms-vscode.cmake-tools)
clangd (llvm-vs-code-extensions.vscode-clangd，可选)
Cortex-Debug (marus25.cortex-debug，用于 GDB + OpenOCD 调试)

一、整体思路（简要）

准备开发环境：装 VSCode、CMake、Ninja、GDB/OpenOCD 等基础工具；
准备交叉工具链：装 RISC‑V GCC（或自行编译以确保 ABI/multilib 匹配）；
克隆 HPM SDK；
在 VSCode 里配 CMake（把 SDK 路径、toolchain 路径等写入工作区设置）。

二、系统层工具（以 Arch 为例）

sudo pacman -Syu
sudo pacman -S --needed \
  base-devel cmake ninja git python python-pip pkgconf make gcc \
  openocd llvm lldb gdb clang curl

三、工具链（RISC‑V）与 AUR 的注意点

AUR 的 riscv-gnu-toolchain-bin 在 HPM6800 上可能因为浮点 ABI / multilib 配置与工程不匹配，导致链接阶段失败。
建议为 HPM6800 单独编译工具链，并在 VSCode 的 CMake 配置中指定该工具链（例如 /opt/riscv-hpm6800）。

示例：自行编译工具链（简略）

git clone https://github.com/riscv/riscv-gnu-toolchain.git
cd riscv-gnu-toolchain
./configure --prefix=/opt/riscv-hpm6800
make -j"$(nproc)"
# 完成后可用 /opt/riscv-hpm6800/bin 下的工具

四、获取 HPM SDK

git clone https://github.com/hpmicro/hpm_sdk.git ~/hpm_sdk

常用路径示例（按实际替换）：

SDK 根目录：~/hpm_sdk
示例工程：~/hpm_sdk/samples/hello_world
SDK cmake 模块：~/hpm_sdk/cmake
OpenOCD 脚本目录：~/hpm_sdk/boards/openocd

Python 环境配置

HPM SDK 需要 Python 3.8+ 及一些 Python 脚本。推荐使用虚拟环境（venv）来隔离项目依赖，避免污染系统 Python 环境。

方式一：使用虚拟环境（推荐）

创建虚拟环境：

# 在项目根目录创建虚拟环境
cd ~/hpm_sdk
python3 -m venv .venv

# 或者在工作区目录创建（适合多项目开发）
cd /path/to/workspace
python3 -m venv .venv

激活虚拟环境：

# Linux/macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (CMD)
.venv\Scripts\activate.bat

激活后，命令行提示符会显示 (.venv)，表示已进入虚拟环境。

安装 HPM SDK 依赖：

# 确保虚拟环境已激活
pip install -r "$HOME/hpm_sdk/scripts/requirements.txt"

VSCode 集成虚拟环境：

VSCode 会自动检测 .venv 目录。如需手动指定，在 .vscode/settings.json 中添加：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

退出虚拟环境：

deactivate

方式二：全局安装（不推荐）

直接在系统 Python 环境中安装依赖：

pipx install --user -r "$HOME/hpm_sdk/scripts/requirements.txt"

注意：

如果 pip 安装失败，请检查是否正确设置了 HPM_SDK_BASE 环境变量（如果在命令行中使用）
全局安装可能与其他项目的依赖冲突，推荐使用虚拟环境

虚拟环境的优势

✅ 项目依赖隔离，不同项目可使用不同版本的库
✅ 不污染系统 Python 环境
✅ 便于团队协作，可通过 requirements.txt 同步依赖
✅ 易于清理，删除 .venv 目录即可移除所有依赖

常见问题

Q: 虚拟环境创建失败？

# 确保已安装 python3-venv
sudo apt install python3-venv  # Ubuntu/Debian
sudo pacman -S python          # Arch Linux（自带 venv）

Q: 每次都要激活虚拟环境吗？

是的，每次打开新终端都需要激活。VSCode 的集成终端会自动激活配置的虚拟环境。

Q: 如何在 CI/CD 中使用虚拟环境？

# CI 脚本示例
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cmake -S . -B build

五、环境变量详解与配置方式对比

5.1 核心环境变量说明

HPM SDK 的 CMake 脚本依赖以下环境变量来定位工具链和相关资源。如果在构建时遇到"找不到 XXX"的错误，首先检查环境变量配置。

环境变量	说明	示例值	必需性
`HPM_SDK_BASE`	SDK 根目录的绝对路径	`/home/dev/hpm_sdk` 或 `~/hpm_sdk`	必需
`GNURISCV_TOOLCHAIN_PATH`	RISC-V 交叉编译工具链的安装目录（该目录下的 `bin/` 应包含 `riscv32-elf-gcc` 等可执行文件）	`/opt/riscv-hpm6800`	必需
`HPM_SDK_TOOLCHAIN_VARIANT`	指定工具链类型，常用值：`gcc`（默认）、`nds-gcc`（使用 Andes 工具链时）	`gcc` 或 `nds-gcc`	可选（默认 gcc）
`OPENOCD_SCRIPTS`	OpenOCD 配置脚本目录（HPM SDK 提供的专用 OpenOCD 配置）	`~/hpm_sdk/boards/openocd`	调试时需要
`PATH`	系统可执行文件搜索路径（需包含工具链的 `bin` 目录）	`$GNURISCV_TOOLCHAIN_PATH/bin:$PATH`	必需

重要提示：

HPM_SDK_BASE 和 GNURISCV_TOOLCHAIN_PATH 必须使用绝对路径

GNURISCV_TOOLCHAIN_PATH 指向的目录结构应为：

/opt/riscv-hpm6800/
├── bin/
│   ├── riscv32-elf-gcc
│   ├── riscv32-elf-g++
│   ├── riscv32-elf-gdb
│   └── ...
├── lib/
└── ...

OpenOCD 必须使用 HPMicro 提供的定制版本，系统自带的 OpenOCD 不兼容

5.2 两种配置方式对比

方式一：全局 shell 配置（不推荐用于 VSCode 开发）

适用场景：命令行构建、CI/CD 流水线、多项目共享同一工具链

Ubuntu/Arch Linux 配置：

编辑 ~/.bashrc 或 ~/.zshrc，添加：

# HPM SDK 环境变量配置
export HPM_SDK_BASE="$HOME/hpm_sdk"
export GNURISCV_TOOLCHAIN_PATH="/opt/riscv-hpm6800"
export HPM_SDK_TOOLCHAIN_VARIANT="gcc"  # 或 nds-gcc
export OPENOCD_SCRIPTS="$HPM_SDK_BASE/boards/openocd"
export PATH="$GNURISCV_TOOLCHAIN_PATH/bin:$PATH"

使配置生效：

source ~/.bashrc  # 或 source ~/.zshrc

Windows 配置：

右键"此电脑" → 属性 → 高级系统设置 → 环境变量

在"用户变量"或"系统变量"中添加：

HPM_SDK_BASE = C:\hpm_sdk
GNURISCV_TOOLCHAIN_PATH = C:\toolchains\riscv-hpm6800
HPM_SDK_TOOLCHAIN_VARIANT = gcc
OPENOCD_SCRIPTS = C:\hpm_sdk\boards\openocd

编辑 Path 变量，添加：%GNURISCV_TOOLCHAIN_PATH%\bin

优点：

在任何终端/命令行中都可用
适合使用 CLion、命令行构建等场景

缺点：

污染全局环境，影响其他项目
不同项目使用不同工具链版本时需频繁切换
团队协作时每个人的路径可能不同，难以统一

方式二：VSCode 工作区配置（推荐）

适用场景：VSCode + CMake Tools 开发

在项目的 .vscode/settings.json 中配置（参见"六、VSCode 的 CMake 示例配置"），环境变量仅在该工作区的 CMake 构建中生效。

优点：

不污染全局环境，各项目独立配置
配置文件可纳入版本控制，团队成员共享
切换项目时自动应用对应配置

缺点：

仅在 VSCode CMake Tools 中生效，命令行构建需单独配置
初次配置略显繁琐

5.3 推荐实践

VSCode 开发：使用方式二（工作区配置），将 .vscode/settings.json 加入版本控制，团队成员只需根据本地路径做少量调整

命令行/脚本构建：临时 export 环境变量，或在构建脚本开头设置：

export HPM_SDK_BASE="$PWD/hpm_sdk"
export GNURISCV_TOOLCHAIN_PATH="/opt/riscv-hpm6800"
export PATH="$GNURISCV_TOOLCHAIN_PATH/bin:$PATH"
cmake -S . -B build -G Ninja -DBOARD=hpm6800evk

CI/CD 流水线：在流水线配置文件中设置环境变量

5.4 CLion 开发中的环境变量配置

如果使用 CLion（参考 CLion 开发指南），环境变量的配置方式与 VSCode 不同：

CLion 依赖系统环境变量（方式一），需在 ~/.bashrc 或 Windows 系统环境变量中设置
CMake Options 通过 GUI 界面配置，如 -DBOARD=hpm6750evkmini -DCMAKE_BUILD_TYPE=flash_sdram_xip
OpenOCD 路径在"嵌入式开发"设置中单独配置

六、不要乱改全局 shell 配置（VSCode 开发）

对于 VSCode 开发，推荐把与项目相关的环境变量写在 VSCode 工作区的 CMake 配置里（.vscode/settings.json），避免污染全局环境。

若确实需要在 shell 中使用交叉编译器（如命令行调试、手动构建），可临时 export：

export GNURISCV_TOOLCHAIN_PATH=/opt/riscv-hpm6800
export PATH="${GNURISCV_TOOLCHAIN_PATH}/bin:${PATH}"

七、VSCode 的 CMake 示例配置（放在 .vscode/settings.json）

下面示例可直接复制并按路径替换。它把构建/配置阶段所需的环境变量注入到 CMake Tools，实现项目级的环境隔离。

配置说明：

cmake.buildEnvironment 和 cmake.configureEnvironment：在 CMake 构建/配置时注入环境变量
cmake.configureArgs：传递给 CMake 的额外参数（板卡型号、SDK 路径等）
cmake.sourceDirectory：CMake 源码目录（包含 CMakeLists.txt 的目录）

{
  "cmake.generator": "Ninja",
  "cmake.buildDirectory": "${workspaceFolder}/build",
  "cmake.configureOnOpen": true,
  "cmake.loggingLevel": "debug",

  "cmake.buildEnvironment": {
    "OPENOCD_SCRIPTS": "/home/dev/develop/HPM/hpm_sdk/boards/openocd",
    "HPM_SDK_BASE": "/home/dev/develop/HPM/hpm_sdk",
    "GNURISCV_TOOLCHAIN_PATH": "/opt/riscv-hpm6800",
    "HPM_SDK_TOOLCHAIN_VARIANT": "gcc",
    "PATH": "/opt/riscv-hpm6800/bin:/usr/bin:/usr/sbin:${env:PATH}"
  },

  "cmake.configureEnvironment": {
    "HPM_SDK_BASE": "/home/dev/develop/HPM/hpm_sdk",
    "OPENOCD_SCRIPTS": "/home/dev/develop/HPM/hpm_sdk/boards/openocd",
    "GNURISCV_TOOLCHAIN_PATH": "/opt/riscv-hpm6800",
    "HPM_SDK_TOOLCHAIN_VARIANT": "gcc",
    "PATH": "/opt/riscv-hpm6800/bin:/usr/bin:/usr/sbin:${env:PATH}"
  },

  "cmake.configureArgs": [
    "-DBOARD=hpm6800evk",
    "-Dhpm-sdk_DIR=/home/dev/develop/HPM/hpm_sdk/cmake"
  ],

  "cmake.sourceDirectory": "/home/dev/develop/HPM/hpm_sdk/samples/hello_world"
}

路径替换提示：

将所有 /home/dev/develop/HPM/hpm_sdk 替换为你的 HPM SDK 实际路径
将 /opt/riscv-hpm6800 替换为你的工具链安装路径
将 hpm6800evk 替换为你使用的板卡型号（如 hpm6750evkmini）
将 samples/hello_world 替换为你的项目路径

7.1 纯编译构建场景（不生成 IDE 项目）

如果只需要使用 VSCode + CMake Tools 进行编译和调试，不需要生成 SES/IAR 项目文件，可以采用更简洁的配置：

CMakeLists.txt 配置（不生成 IDE）：

cmake_minimum_required(VERSION 3.13)

# 设置链接器配置
set(HPM_BUILD_TYPE "flash_xip")

# 查找 HPM SDK
find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})

# 定义项目
project(my_application)

# 添加源文件
sdk_app_src(src/main.c)

# 注意：这里不调用 generate_ide_projects()
# 如果不需要 SES/IAR 项目文件，直接省略此函数即可

VSCode settings.json 配置（简化版）：

{
  "cmake.generator": "Ninja",
  "cmake.buildDirectory": "${workspaceFolder}/build",
  "cmake.configureOnOpen": true,

  // CMake 构建环境变量
  "cmake.buildEnvironment": {
    "HPM_SDK_BASE": "/home/dev/develop/HPM/hpm_sdk",
    "GNURISCV_TOOLCHAIN_PATH": "/opt/riscv-hpm6800",
    "PATH": "/opt/riscv-hpm6800/bin:/usr/bin:/usr/sbin:${env:PATH}"
  },

  // CMake 配置环境变量
  "cmake.configureEnvironment": {
    "HPM_SDK_BASE": "/home/dev/develop/HPM/hpm_sdk",
    "GNURISCV_TOOLCHAIN_PATH": "/opt/riscv-hpm6800",
    "PATH": "/opt/riscv-hpm6800/bin:/usr/bin:/usr/sbin:${env:PATH}"
  },

  // 板卡配置
  "cmake.configureArgs": [
    "-DBOARD=hpm6750evkmini"
  ],

  // 项目源码目录
  "cmake.sourceDirectory": "${workspaceFolder}"
}

使用流程：

配置项目：VSCode 打开项目后自动执行 CMake 配置（或按 F1 → "CMake: Configure"）
选择构建类型：点击 VSCode 底部状态栏的构建类型（Debug/Release）
编译：点击状态栏的 "Build" 按钮或按 F7
输出文件：生成的 .elf 和 .bin 文件位于 build/output/ 目录

优势对比：

配置方式	优点	缺点	适用场景
生成 IDE 项目	可在 SES/IAR 中打开调试	每次 CMake 配置都生成项目文件，构建稍慢	需要使用 SES/IAR 的高级调试功能
纯 CMake 构建	配置简洁，构建速度快，不生成冗余文件	仅能在 VSCode 中调试	仅使用 VSCode 开发，通过 GDB + OpenOCD 调试

调试配置（使用 Cortex-Debug）：

如果使用纯 CMake 构建，可以配置 .vscode/launch.json 通过 OpenOCD 调试：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Cortex Debug",
      "type": "cortex-debug",
      "request": "launch",
      "servertype": "openocd",
      "cwd": "${workspaceFolder}",
      "executable": "${workspaceFolder}/build/output/demo.elf",
      "configFiles": [
        "${env:HPM_SDK_BASE}/boards/openocd/probes/ft2232.cfg",
        "${env:HPM_SDK_BASE}/boards/openocd/soc/hpm6750-dual-core.cfg"
      ],
      "svdFile": "${env:HPM_SDK_BASE}/soc/HPM6750/hpm6750.svd",
      "runToEntryPoint": "main",
      "showDevDebugOutput": "parsed"
    }
  ]
}

八、CMake 构建类型详解

8.1 两种构建类型的区别

HPM SDK 使用两种不同的构建类型概念，初学者容易混淆：

CMAKE_BUILD_TYPE：编译优化级别（控制编译器优化）

debug：调试构建，包含符号信息，最小优化（-O0 -g），便于调试
release：发布构建，完全优化（-O2/-O3），无调试符号，体积更小、速度更快

HPM_BUILD_TYPE：链接器配置（控制内存布局和代码运行位置）

ram：代码运行在 RAM 中（默认），适合快速调试，断电丢失
flash_xip：代码在 Flash 中执行（XIP = eXecute In Place），适合生产部署
flash_sdram_xip：代码在 Flash 中执行，数据在 SDRAM 中，适合大内存需求
flash_hybrid_xip：代码在 RAM 映射的 Flash 中，数据在 RAM，混合模式
sec_core_img：次核心镜像（多核应用的 Core1）

8.2 常见使用场景

场景一：日常开发调试

cmake -B build -S . -DBOARD=hpm6750evkmini -DCMAKE_BUILD_TYPE=debug
# HPM_BUILD_TYPE 默认为 ram，适合快速烧录和调试

场景二：生产固件

cmake -B build -S . -DBOARD=hpm6750evkmini \
  -DCMAKE_BUILD_TYPE=release \
  -DHPM_BUILD_TYPE=flash_xip
# 优化编译 + Flash 执行，适合批量生产

场景三：大内存应用（需要 SDRAM）

cmake -B build -S . -DBOARD=hpm6750evkmini \
  -DCMAKE_BUILD_TYPE=release \
  -DHPM_BUILD_TYPE=flash_sdram_xip

8.3 在 CMakeLists.txt 中设置

推荐在项目的 CMakeLists.txt 中设置 HPM_BUILD_TYPE（编译类型仍通过命令行控制）：

cmake_minimum_required(VERSION 3.13)

# 为此项目设置链接器配置（推荐在这里设置）
set(HPM_BUILD_TYPE "flash_xip")

find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})
project(my_application)

sdk_app_src(src/main.c)
generate_ide_projects()

通过命令行覆盖：

# 命令行参数优先级更高，可覆盖 CMakeLists.txt 中的设置
cmake -B build -S . -DBOARD=hpm6750evkmini -DHPM_BUILD_TYPE=ram

九、CMake 常用函数详解

9.1 添加源文件和头文件

sdk_app_src()：添加应用程序源文件

# 单个文件
sdk_app_src(src/main.c)

# 多个文件
sdk_app_src(
    src/main.c
    src/gpio_handler.c
    src/uart_handler.c
)

# 使用变量
set(MY_SOURCES
    src/main.c
    src/app.c
)
sdk_app_src(${MY_SOURCES})

sdk_app_inc()：添加头文件搜索路径

# 添加单个目录
sdk_app_inc(include)

# 添加多个目录
sdk_app_inc(
    include
    include/drivers
    include/utils
)

9.2 编译选项和宏定义

sdk_compile_options()：添加编译器选项（跨工具链）

# 添加编译器优化选项
sdk_compile_options("-O2")
sdk_compile_options("-Wall")

# 条件编译选项
sdk_compile_options_ifdef(CONFIG_DEBUG "-g")
sdk_compile_options_ifndef(CONFIG_RELEASE "-DNDEBUG")

sdk_compile_definitions()：添加宏定义

# 添加宏定义
sdk_compile_definitions("DEBUG_MODE=1")
sdk_compile_definitions("VERSION=\"1.0.0\"")

# 条件宏定义
sdk_compile_definitions_ifdef(CONFIG_USB "USB_ENABLED=1")

9.3 组件和中间件

sdk_inc()：添加 SDK 组件头文件路径

# 包含 SDK 组件头文件
sdk_inc(components/debug_console)
sdk_inc(middleware/freertos)

sdk_src()：添加 SDK 源文件

# 添加 SDK 源文件
sdk_src(components/debug_console/debug_console.c)

9.4 内存配置

# 配置堆和栈大小（在 find_package 之前设置）
set(HEAP_SIZE 0x8000)   # 32KB 堆
set(STACK_SIZE 0x2000)  # 8KB 栈

# 配置 RISC-V 架构和ABI
set(RV_ARCH "rv32imac_zicsr_zifencei")
set(RV_ABI "ilp32")

find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})

9.5 生成 IDE 项目

# 为所有支持的 IDE 生成项目文件（SES、IAR）
generate_ide_projects()

生成后的项目文件位于：

Segger Embedded Studio: build/segger_embedded_studio/*.emProject
IAR Embedded Workbench: build/iar_embedded_workbench/*.ewp

十、板卡配置详解

10.1 使用 SDK 自带板卡

HPM SDK 提供了多款官方开发板配置，位于 hpm_sdk/boards/ 目录：

# 查看可用板卡
ls ~/hpm_sdk/boards/
# hpm6750evkmini, hpm6750evk, hpm6800evk, hpm5300evk, ...

# 使用官方板卡
cmake -B build -S . -DBOARD=hpm6750evkmini

10.2 创建自定义板卡配置

步骤一：创建板卡目录结构

mkdir -p /path/to/my_boards/my_custom_board
cd /path/to/my_boards/my_custom_board

重要：目录名、YAML 文件名、CFG 文件名必须完全相同（例如都是 my_custom_board）。

步骤二：创建板卡配置文件 my_custom_board.yaml

board:
    soc: HPM6750                    # SOC 型号
    device: HPM6750xVMx             # 设备名称（用于 J-Link）
    openocd-soc: hpm6750-dual-core  # OpenOCD SOC 配置文件名
    openocd-probe: ft2232           # OpenOCD 探针配置文件名
    on-board-ram:
      type: sdram
      size: 16M                     # 板载 RAM 大小（用于链接脚本）
      width: 16bit
    on-board-flash:
      type: qspi-nor-flash
      size: 8M                      # 板载 Flash 大小（用于链接脚本）

可选字段（用于 SDK 内部维护，自定义板卡通常不需要）：

    # 可选：指定板卡支持的功能（用于示例兼容性）
    feature:
      - board_audio_in
      - board_motor_control
      - board_gpio_led
    # 可选：排除不兼容的示例
    excluded_samples:
      - samples/motor_ctrl/bldc_hfi

步骤三：创建 OpenOCD 配置文件 my_custom_board.cfg

# OpenOCD 调试器配置（根据你的调试器硬件修改）
source [find interface/ftdi/ft2232h.cfg]
source [find target/hpm6750.cfg]

步骤四：使用自定义板卡

# 指定自定义板卡搜索路径
cmake -B build -S . \
  -DBOARD=my_custom_board \
  -DBOARD_SEARCH_PATH=/path/to/my_boards

cmake --build build

10.3 板卡配置文件说明

板卡 YAML 文件的关键字段：

字段	说明	示例值
`soc`	SOC 型号	`HPM6750`, `HPM6800`
`device`	J-Link 设备名称	`HPM6750xVMx`
`openocd-soc`	OpenOCD SOC 配置文件（不含 .cfg）	`hpm6750-dual-core`
`openocd-probe`	OpenOCD 探针配置文件（不含 .cfg）	`ft2232`, `jlink`
`on-board-ram.size`	板载 RAM 大小	`16M`, `32M`
`on-board-flash.size`	板载 Flash 大小	`8M`, `16M`

十一、在 CMakeLists 中使用这些变量

HPM SDK 的 CMake 脚本会自动读取环境变量，开发者也可以在自己的 CMakeLists.txt 中访问这些变量：

读取环境变量：

if(DEFINED ENV{HPM_SDK_BASE})
  message(STATUS "HPM_SDK_BASE=" $ENV{HPM_SDK_BASE})
  set(HPM_SDK_BASE $ENV{HPM_SDK_BASE})
endif()

或通过 -D 传入并缓存：

if(NOT DEFINED HPM_SDK_BASE)
  set(HPM_SDK_BASE "/default/path/if/none" CACHE PATH "Path to HPM SDK")
endif()
message(STATUS "Using HPM_SDK_BASE=${HPM_SDK_BASE}")

注意：HPM SDK 自带的 CMake 脚本已经处理了这些逻辑，通常不需要额外编写。

九、命令行 / CI 等价写法

对于不使用 VSCode 的场景（如命令行构建、持续集成），可在脚本中设置环境变量后调用 cmake：

export HPM_SDK_BASE=/home/dev/develop/HPM/hpm_sdk
export GNURISCV_TOOLCHAIN_PATH=/opt/riscv-hpm6800
export PATH="${GNURISCV_TOOLCHAIN_PATH}/bin:/usr/bin:/usr/sbin:$PATH"

cmake -S /home/dev/develop/HPM/hpm_sdk/samples/hello_world \
      -B build -G Ninja \
      -DBOARD=hpm6800evk \
      -Dhpm-sdk_DIR=$HPM_SDK_BASE/cmake

cmake --build build

CI/CD 配置示例（GitHub Actions）：

env:
  HPM_SDK_BASE: ${{ github.workspace }}/hpm_sdk
  GNURISCV_TOOLCHAIN_PATH: /opt/riscv-hpm6800
  
steps:
  - name: Build
    run: |
      export PATH="${GNURISCV_TOOLCHAIN_PATH}/bin:$PATH"
      cmake -S $HPM_SDK_BASE/samples/hello_world -B build -G Ninja -DBOARD=hpm6800evk
      cmake --build build

十二、常见问题与排查建议（要点）

12.1 环境变量相关问题

问题现象	可能原因	解决方法
CMake 报错"Could not find HPM SDK"	`HPM_SDK_BASE` 未设置或路径错误	检查 VSCode settings.json 或命令行环境变量，确保路径正确
找不到 `riscv32-elf-gcc`	`GNURISCV_TOOLCHAIN_PATH` 或 `PATH` 未正确设置	验证工具链路径，确保 `$GNURISCV_TOOLCHAIN_PATH/bin/riscv32-elf-gcc` 存在
CMake 提示 toolchain variant 错误	`HPM_SDK_TOOLCHAIN_VARIANT` 设置与实际工具链不匹配	使用 Andes 工具链时设为 `nds-gcc`，否则设为 `gcc` 或不设置
OpenOCD 连接失败	`OPENOCD_SCRIPTS` 路径错误或使用了非 HPM 版本的 OpenOCD	确保使用 HPM SDK 提供的 OpenOCD，路径指向 `hpm_sdk/boards/openocd`

12.2 通用排查步骤

查看 CMake 配置日志
- VSCode：查看 CMake Tools 的 Output 面板，检查 configure 日志中环境变量是否正确
- 命令行：加 --debug-output 或 --trace 参数查看详细输出

验证工具链

# 检查工具链是否可用
$GNURISCV_TOOLCHAIN_PATH/bin/riscv32-elf-gcc --version

# 检查 ABI 支持
$GNURISCV_TOOLCHAIN_PATH/bin/riscv32-elf-gcc -print-multi-lib

AUR 工具链链接失败
优先怀疑浮点 ABI / multilib 不匹配，建议编译专用工具链（参见"三、工具链"章节）
CMake 找不到交叉编译器
- 确认 configureEnvironment / buildEnvironment 中的 PATH 包含交叉工具链 bin 目录
- 必要时在 toolchain 文件中写入完整编译器路径
WSL 路径问题
- 避免使用 Windows 路径（如 /mnt/c/...），将 SDK 和工具链放在 WSL 文件系统中（如 ~/ 或 /opt/）
- 使用绝对路径而非相对路径

12.3 调试技巧

使用 message(STATUS "HPM_SDK_BASE=${HPM_SDK_BASE}") 在 CMakeLists.txt 中打印变量值
在 VSCode 中启用 "cmake.loggingLevel": "debug" 查看详细日志
对比工作配置与失败配置的环境变量差异

十三、小结

核心要点：

环境变量配置策略
- VSCode 开发：使用工作区配置（.vscode/settings.json），实现项目级隔离
- CLion 开发：配置系统环境变量（~/.bashrc 或 Windows 环境变量）
- 命令行/CI：在脚本中临时 export 或在 CI 配置文件中设置
路径必须正确
- HPM_SDK_BASE 和 GNURISCV_TOOLCHAIN_PATH 使用绝对路径
- 工具链 bin 目录必须在 PATH 中
- WSL 开发时避免使用 Windows 路径（/mnt/c/...）
工具链选择
- AUR 的预编译工具链可能存在 ABI 配置差异，自己编译一套工具链更稳
- 追求性能时选择 Andes nds-gcc（需设置 HPM_SDK_TOOLCHAIN_VARIANT=nds-gcc）
- 通用兼容性选择官方 riscv32-unknown-elf 或 HPM 定制版
构建类型理解
- CMAKE_BUILD_TYPE：控制编译优化（debug/release）
- HPM_BUILD_TYPE：控制内存布局（ram/flash_xip/flash_sdram_xip）
- 两者独立配置，根据使用场景组合使用
灵活应用
- 模板跑通后，切换示例或板卡时只需修改几个路径与 BOARD 名称即可继续开发
- 团队协作时将 .vscode/settings.json 加入版本控制，成员仅需调整本地路径