1.1 主机、工具链和开发板的关系#

嵌入式 Linux 开发环境中的“Linux”通常指开发主机，而不是目标芯片运行 Linux。HPM5E3Y 上运行的是交叉编译生成的裸机固件。

这条链路里最容易混淆的是 CMake、Ninja 和 GCC 的职责：

1.2 推荐工作流#

开发过程中通常不需要反复重新配置 CMake。只要 SDK、板级目录、构建类型不变，日常循环就是“改代码、编译、烧录、观察现象”。

1.3 建议工程结构#

为了让工程更容易迁移，建议把应用代码、板级覆盖文件、OpenOCD 配置和文档分开。SDK 可以放在工程外部，作为只读依赖使用。

1
HPM_Project
2
├── app
3
│   └── gpio
4
│       ├── CMakeLists.txt
5
│       └── src
6
│           ├── gpio.c
7
│           ├── oled_ch1115_i2c.c
8
│           └── oled_ch1115_i2c.h
9
├── board
10
│   ├── hpm5e00evk
11
│   │   ├── board.c
12
│   │   ├── board.h
13
│   │   └── CMakeLists.txt
14
│   └── openocd
15
│       ├── boards
16
│       ├── probes
17
│       └── soc
18
├── docs
19
└── README.md

把 SDK 放在工程外部有两个好处：第一，工程仓库不会被 SDK 源码污染；第二，升级 SDK 时边界清楚，能更容易判断问题来自应用代码、板级文件还是 SDK 变化。

2.1 工具清单#

Linux 下最少需要安装这些工具：

在 Arch Linux / AUR 环境中，可以安装：

1
riscv64-elf-gcc
2
riscv64-elf-newlib
3
hpmicro-openocd-bin
4
hpmicro-manufacturing-tool-bin

其他发行版也可以使用包管理器安装 cmake、ninja 和 RISC-V GCC。OpenOCD 建议使用 HPMicro 提供或打过 HPM patch 的版本。

2.2 检查 CMake 和 Ninja#

1
cmake --version
2
ninja --version

两个命令都能输出版本号即可。CMake 版本过旧时，可能会出现 SDK CMake 脚本不兼容的问题，建议使用发行版较新的稳定版本。

2.3 检查 RISC-V GCC#

1
riscv64-elf-gcc --version
2
which riscv64-elf-gcc

正常情况下，能看到 GCC 版本和安装路径。若提示找不到命令，说明工具链没有安装，或者工具链目录没有加入 PATH。

HPM SDK 使用工具链时通常还需要知道工具链根目录。若编译器路径是：

1
/usr/bin/riscv64-elf-gcc

那么常见的工具链根目录就是：

1
/usr

2.4 检查 HPM patched OpenOCD#

HPM5E3Y 的 Flash 烧录需要支持 HPM Flash 算法的 OpenOCD。示例路径：

1
/opt/hpmicro/openocd/bin/openocd --version

不要误用系统自带的普通 OpenOCD：

1
/usr/bin/openocd

两者差别在烧录阶段非常关键：

2.5 检查 CMSIS-DAP 连接#

开发板上电并连接调试器后执行：

1
lsusb

若使用 CMSIS-DAP，通常能看到类似设备：

1
0d28:0204 CMSIS-DAP

如果没有识别，优先检查：

• USB 线是否支持数据传输
• 开发板是否上电
• 调试器固件是否正常
• Linux 用户是否有 USB 访问权限
• 是否被其他调试软件占用

3.1 使用变量替代硬编码路径#

教程里最不建议直接复制的是绝对路径。更稳妥的方式是先定义几组变量，再在命令中引用它们。

1
export PROJECT_ROOT="$HOME/Projects/HPM_Project"
2
export HPM_SDK_BASE="$HOME/Projects/sdk_env_v1.11.0/hpm_sdk"
3
export GNURISCV_TOOLCHAIN_PATH="/usr"
4
export HPM_SDK_TOOLCHAIN_VARIANT="gcc"
5
export OPENOCD="/opt/hpmicro/openocd/bin/openocd"
6
export BOARD="hpm5e00evk"
7
export BOARD_SEARCH_PATH="$PROJECT_ROOT/board"

这些变量的含义如下：

3.2 检查变量是否生效#

1
echo "$PROJECT_ROOT"
2
echo "$HPM_SDK_BASE"
3
echo "$GNURISCV_TOOLCHAIN_PATH"
4
echo "$HPM_SDK_TOOLCHAIN_VARIANT"
5
echo "$OPENOCD"

可以进一步检查关键目录和程序是否存在：

1
test -d "$PROJECT_ROOT" && echo "PROJECT_ROOT OK"
2
test -d "$HPM_SDK_BASE" && echo "HPM_SDK_BASE OK"
3
test -x "$OPENOCD" && echo "OPENOCD OK"

若这些变量每次开新终端都需要使用，可以写入 ~/.bashrc、~/.zshrc 或其他 shell 配置文件。

3.3 构建目录命名建议#

构建目录建议包含板卡、运行位置、构建类型和工具链信息。例如：

1
export BUILD_DIR="$PROJECT_ROOT/app/gpio/build/${BOARD}_flash_xip_debug_gcc"

这样的命名比简单的 build 更清楚，尤其适合同时维护多个构建配置。

4.1 关键 CMake 参数#

HPM SDK 工程的 CMake 配置参数比普通桌面工程更多，因为它需要同时描述板卡、工具链、运行位置和 RISC-V ABI。

这几个参数里，最容易出错的是 RV_ARCH、RV_ABI 和 HPM_BUILD_TYPE。它们会影响编译参数、链接脚本和启动方式。初学阶段建议先使用 SDK 示例或官方 board 已验证的组合。

4.2 生成构建文件#

进入工程根目录：

1
cd "$PROJECT_ROOT"

执行 CMake 配置：

1
cmake -S app/gpio \
2
  -B "$BUILD_DIR" \
3
  -G Ninja \
4
  -DBOARD="$BOARD" \
5
  -DBOARD_SEARCH_PATH="$BOARD_SEARCH_PATH" \
6
  -DCUSTOM_TARGET_TRIPLET=riscv64-elf \
7
  -DCMAKE_BUILD_TYPE=debug \
8
  -DHPM_BUILD_TYPE=flash_xip \
9
  -DRV_ARCH=rv32imac_zicsr_zifencei \
10
  -DRV_ABI=ilp32 \
11
  -DUSE_CCACHE=0 \
12
  -DOPENOCD="$OPENOCD"

配置成功时，通常会看到类似信息：

1
-- Application: .../app/gpio
2
-- Board (custom board): hpm5e00evk from .../board
3
-- Found toolchain: gnu (/usr)
4
-- hpm_sdk: 1.11.0 (.../hpm_sdk)
5
-- Configuring done
6
-- Generating done
7
-- Build files have been written to: ...

可以把这段输出看成一次构建体检：

4.3 执行编译#

1
cmake --build "$BUILD_DIR"

编译成功后，输出目录通常位于：

1
$BUILD_DIR/output

检查输出文件：

1
ls "$BUILD_DIR/output"

常见产物如下：

4.4 理解内存占用输出#

编译结束时通常会显示类似内存用量：

1
Memory region         Used Size  Region Size  %age Used
2
FLASH:                  ...
3
ILM:                    ...
4
DLM:                    ...
5
AXI_SRAM:               ...

这些信息不只是“编译成功提示”，还可以用于判断固件是否接近资源上限。

如果 FLASH 或 SRAM 占用异常，应优先查看 demo.map，而不是只看 C 源码大小。

4.5 重新配置和增量编译#

修改普通源文件后，只需要：

1
cmake --build "$BUILD_DIR"

以下情况建议清理或新建构建目录：

• 更换 HPM SDK 版本
• 更换 board
• 更换 HPM_BUILD_TYPE
• 更换 RISC-V ABI 或架构参数
• CMake 缓存中出现难以解释的路径残留

清理示例：

1
rm -rf "$BUILD_DIR"

然后重新执行 CMake 配置。

5.1 OpenOCD 配置文件组成#

一个完整的 OpenOCD 连接通常由三类配置组成：

以 CMSIS-DAP + HPM5E00EVK 为例：

如果调试器是 CMSIS-DAP，就不要误用 FT2232/FTDI 配置。探针配置错误时，OpenOCD 往往会在连接阶段就失败。

5.2 手动烧录命令#

建议先把 OpenOCD 搜索路径和固件路径定义成变量：

1
export OPENOCD_SCRIPTS="$PROJECT_ROOT/board/openocd"
2
export FIRMWARE_ELF="$BUILD_DIR/output/demo.elf"

烧录命令：

1
"$OPENOCD" \
2
  -s "$OPENOCD_SCRIPTS" \
3
  -f probes/cmsis_dap.cfg \
4
  -f soc/hpm5e00.cfg \
5
  -f boards/hpm5e00evk.cfg \
6
  -c "init; halt; init_clock; flash probe 0; flash write_image erase $FIRMWARE_ELF; verify_image $FIRMWARE_ELF; reset run; shutdown"

这条命令可以拆成几步理解：

5.3 烧录成功的典型输出#

连接成功时常见输出包括：

1
Using CMSIS-DAPv2 interface with VID:PID=0x0d28:0x0204
2
JTAG tap: hpm5e00.cpu tap/device found: 0x1000563d
3
[hpm5e00.cpu0] Target successfully examined.
4
clocks has been enabled!

写入成功时会看到擦除、写入、校验相关信息。最终执行 reset run 后，开发板会从新固件启动。

5.4 用 alias 或脚本减少重复输入#

手动命令适合验证流程，但日常开发不适合反复输入长命令。可以在 shell 中定义一个函数：

1
hpm_flash() {
2
  "$OPENOCD" \
3
    -s "$OPENOCD_SCRIPTS" \
4
    -f probes/cmsis_dap.cfg \
5
    -f soc/hpm5e00.cfg \
6
    -f boards/hpm5e00evk.cfg \
7
    -c "init; halt; init_clock; flash probe 0; flash write_image erase $FIRMWARE_ELF; verify_image $FIRMWARE_ELF; reset run; shutdown"
8
}

之后只需要：

1
hpm_flash

工程团队中更推荐把这类命令写入 Makefile、CMakePresets.json、justfile 或项目脚本中，避免每个人维护一份略有差异的本地 alias。

6.1 硬件连接#

假设工程中包含 CH1115 OLED I2C 示例，且 OLED 接在 I2C2：

1
I2C2.SCL -> PD02
2
I2C2.SDA -> PD03

连接关系如下：

1
┌────────────────────┐           ┌────────────────────┐
2
│ HPM5E3Y             │           │ CH1115 OLED         │
3
│                    │           │                    │
4
│ PD02 / I2C2.SCL    ├──────────>│ SCL                │
5
│ PD03 / I2C2.SDA    ├──────────>│ SDA                │
6
│ 3.3V               ├──────────>│ VDD                │
7
│ GND                ├──────────>│ VSS                │
8
└────────────────────┘           └────────────────────┘

6.2 软件文件#

示例相关文件：

1
app/gpio/src/oled_ch1115_i2c.c
2
app/gpio/src/oled_ch1115_i2c.h
3
app/gpio/src/gpio.c

程序启动后会初始化 I2C2，并在屏幕上显示类似内容：

1
HPM5E3Y
2
I2C2 OK

6.3 验证路径#

OLED 不亮时，不要直接怀疑驱动代码。建议按链路逐段验证：

常见检查项：

7.1 快速定位表#

7.2 HPM_SDK_BASE is not set yet#

报错示例：

1
HPM_SDK_BASE is not set yet

解决方法：

1
export HPM_SDK_BASE="$HOME/Projects/sdk_env_v1.11.0/hpm_sdk"
2
export GNURISCV_TOOLCHAIN_PATH="/usr"
3
export HPM_SDK_TOOLCHAIN_VARIANT="gcc"

然后重新执行 CMake 配置。注意，已经生成过的构建目录可能缓存了旧路径，必要时删除 BUILD_DIR 后重新配置。

7.3 flash driver 'hpm_xpi' not found#

这通常表示 OpenOCD 版本不对。检查当前 OpenOCD：

1
which openocd
2
openocd --version
3
"$OPENOCD" --version

烧录命令中应显式使用 HPM patched OpenOCD，例如：

1
/opt/hpmicro/openocd/bin/openocd --version

不要依赖 PATH 中排在前面的 /usr/bin/openocd。

7.4 CMake 配置成功但编译失败#

常见原因包括：

• 应用 CMakeLists.txt 没有正确添加源文件
• board 文件与芯片型号不匹配
• RV_ARCH / RV_ABI 与工程要求不一致
• SDK 版本和示例代码不匹配
• 本地 board 覆盖了 SDK 默认 board，但文件不完整

建议先确认 SDK 自带同类示例是否能编译，再对比自己的工程差异。

7.5 烧录成功但程序不运行#

优先检查以下项目：

8.1 需要替换的参数#

把本文流程迁移到其他 HPMicro 工程时，通常只需要替换这些内容：

8.2 推荐先跑 SDK 官方示例#

迁移时不要一开始就把所有自定义代码放进去。更稳妥的顺序是：

这样做的好处是每一步都有明确边界。一旦出错，可以快速判断是工具链、SDK、board、OpenOCD 还是应用代码的问题。

8.3 最小成功检查表#

环境是否真正跑通，可以用下面的检查表确认：

只要这八项都通过，Linux 下 HPM5E3Y GCC 开发环境就已经具备可持续开发能力。后续工作重点就从“环境是否能跑”转移到 board 配置、驱动质量、外设验证和应用逻辑本身。