沁恒 CH32V208(三): CH32V208 Ubuntu22.04 Makefile VSCode环境配置

硬件部分

CH32V208WBU6 评估板
WCH-LinkE 或 WCH-Link

硬件环境与Windows下相同, 不详细介绍

软件部分

沁恒已经开源WCH-Link的协议, 因此这部分的选项将会很丰富, 这里还是以沁恒官方的定制版 RISC-V Embedded GCC 和 OpenOCD 为例进行说明.

下载

从 http://mounriver.com/download 下载最新的工具链. 当前版本是 MRS_Toolchain_Linux_X64_V170.tar.xz, 对于 CH32V208, V1.60版本也能支持. 压缩包中包含 RISC-V Embedded GCC 和 OpenOCD.

配置

解压工具链,

sudo tar -xvf MRS_Toolchain_Linux_X64_V170.tar.xz

在解压后的目录下有一个README, 这个文件比较重要. 因为沁恒每次出新版本都可能有一些变动, 导致前一个版本的 cfg 或者命令行无法使用, 这个 README 中会列举当前版本可用的烧录和debug命令, 需要留意.

将工具链移动到合适的位置, 并修改owner为root避免误修改

sudo mkdir -p /opt/gcc-riscv/
sudo mv "MRS_Toolchain_Linux_x64_V1.70/RISC-V Embedded GCC" /opt/gcc-riscv/riscv-wch-embedded-gcc-v1.70
sudo chown -R root:root /opt/gcc-riscv/riscv-wch-embedded-gcc-v1.70

sudo mkdir -p /opt/openocd/
sudo mv MRS_Toolchain_Linux_x64_V1.70/OpenOCD /opt/openocd/wch-openocd-v1.70
sudo chown -R root:root /opt/openocd/wch-openocd-v1.70

额外的动态链接库, 在 beforeinstall/start.sh 里是直接复制到 /usr/lib, 稳妥起见, 还是单独建一个目录放进去

sudo mkdir -p /usr/lib/wch/
sudo cp -P beforeinstall/lib* /usr/lib/wch/
sudo ldconfig

配置设备权限

根据 start.sh 中执行的命令, 需要将两个规则文件复制到 /etc/udev/rules.d.
先检查一下 /etc/udev/ 下是否已经存在相关的配置, 如果有, 需要和这两个规则整合一下, 如果没有, 直接复制然后更新就可以了

sudo cp beforeinstall/50-wch.rules /etc/udev/rules.d
sudo cp beforeinstall/60-openocd.rules  /etc/udev/rules.d
# Reload rules
sudo udevadm control  --reload-rules

验证

执行这两个命令应该能看到正确的输出, 如果有报错, 需要先排查问题

~$ /opt/gcc-riscv/riscv-wch-embedded-gcc-v1.70/bin/riscv-none-embed-gcc --version
riscv-none-embed-gcc (xPack GNU RISC-V Embedded GCC, 64-bit) 8.2.0
Copyright (C) 2018 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

~$ /opt/openocd/wch-openocd-v1.70/bin/openocd --version
Open On-Chip Debugger 0.11.0+dev-02415-gfad123a16-dirty (2023-02-22-15:09)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html

运行示例项目

基于 CH32V20x 的参考例程 https://www.wch.cn/downloads/CH32V20xEVT_ZIP.html, 调整结构并增加 Makefile, 已经提交至 GitHub, 可以直接导出进行编译和烧录.

项目地址: https://github.com/IOsetting/ch32v208-template

从 GitHub 导出项目

git clone https://github.com/IOsetting/ch32v208-template.git

根据自己的环境, 调整 Makefile 中的路径信息, 其它内容可以保持默认

##### Toolchains #######

GCC_TOOCHAIN	?= /opt/gcc-riscv/riscv-wch-embedded-gcc-v1.70/bin

OPENOCD_PATH	?= /opt/openocd/wch-openocd-v1.70/bin

执行编译

make clean
make

如果CH32V208评估板已经通过 WCH-Link 连接上PC, 可以执行下面的命令进行烧录

make flash

沁恒V1.60 的 openocd 不支持 CH32V208, 烧录不报错, 但是不运行, 要用 V1.70 版本才行.

GDB Debug

打开终端, 用沁恒定制的 openocd 启动 GDB Server, 注意要连上 WCH-Link, 不然 Server 会报错退出.

/opt/openocd/wch-openocd-v1.70/bin$ ./openocd -f wch-riscv.cfg 
Open On-Chip Debugger 0.11.0+dev-02415-gfad123a16-dirty (2023-02-22-15:09)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'sdi'
Warn : Transport "sdi" was already selected
Ready for Remote Connections
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : WCH-Link-CH549  mode:RV version 2.8 
Info : wlink_init ok
Info : clock speed 6000 kHz
Info : [wch_riscv.cpu.0] datacount=2 progbufsize=8
Info : [wch_riscv.cpu.0] Examined RISC-V core; found 1 harts
Info : [wch_riscv.cpu.0]  XLEN=32, misa=0x40901105
[wch_riscv.cpu.0] Target successfully examined.
Info : starting gdb server for wch_riscv.cpu.0 on 3333
Info : Listening on port 3333 for gdb connections

在第二个终端中, 启动 GDB Client

/opt/gcc-riscv/riscv-wch-embedded-gcc-v1.70/bin/riscv-none-embed-gdb Build/app.elf
GNU gdb (xPack GNU RISC-V Embedded GCC, 64-bit) 8.3
Copyright (C) 2019 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-unknown-linux-gnu --target=riscv-none-embed".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://github.com/sifive/freedom-tools/issues>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from Build/app.elf...

设置GDB参数

(gdb) set mem inaccessible-by-default off
(gdb) set remotetimeout unlimited
(gdb) set architecture riscv:rv32
The target architecture is assumed to be riscv:rv32

连接到GDB服务, load 载入程序, b 设置断点, c 继续执行, i r 查看寄存器, i local 查看全部局部变量, list 查看代码. c过程中可以用Ctrl+C暂停, quit 退出

(gdb) target remote localhost:3333
Remote debugging using localhost:3333
0x00000428 in Delay_Ms (n=n@entry=1000) at Debug/debug.c:74
74	    while((SysTick->SR & (1 << 0)) != (1 << 0));
(gdb) i r pc
pc             0x428	0x428 <Delay_Ms+46>
(gdb) load
Loading section .init, size 0x38 lma 0x0
Loading section .vector, size 0x148 lma 0x38
Loading section .text, size 0x1e4c lma 0x180
Loading section .data, size 0x88 lma 0x1fcc
Start address 0x0, load size 8276
Transfer rate: 4 KB/sec, 2069 bytes/write.
(gdb) i r pc
pc             0x0	0x0 <_start>
(gdb) b main
Breakpoint 1 at 0x25e: file User/main.c, line 55.
(gdb) c
Continuing.
Note: automatically using hardware breakpoints for read-only addresses.

Breakpoint 1, main () at User/main.c:55
55	    NVIC_PriorityGroupConfig(NVIC_PriorityGroup_2);
(gdb) i r pc
pc             0x25e	0x25e <main>
(gdb) list
50	 */
51	int main(void)
52	{
53	    u8 i = 0;
54	
55	    NVIC_PriorityGroupConfig(NVIC_PriorityGroup_2);
56	    Delay_Init();
57	    USART_Printf_Init(115200);
58	    printf("SystemClk:%ld\r\n", SystemCoreClock);
59	
(gdb)

配置 VSCode 开发环境

如果以上步骤都已经顺利完成, 直接在 VSCode 中打开这个项目目录就可以了. VSCode 的 Makefile 扩展会自动识别对应的工具链和依赖库, 代码提示和高亮开箱即用.

需要配置的是编译和烧录的快捷命令, 可以通过 Ctrl+Shift+P 调出菜单, 用 Tasks:Configure Task 进行配置, 或者直接在 .vscode 目录下创建 tasks.json 进行配置

tasks.json 的例子

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "clean & build",
            "type": "shell",
            "command": "make clean; make -j4",
            "problemMatcher": []
        },
        {
            "label": "build",
            "type": "shell",
            "command": "make -j4"
        },
        {
            "label": "build & download",
            "type": "shell",
            "command": "make -j4; make flash"
        }
    ]
}

配置之后, 可以通过 Alt + Shift + F10 调出 task 菜单, 选择对应的任务进行编译或下载.

配置 VSCode Cortex Debug

VSCode 的 Cortex Debug 可以用于 debug CH32V208, 但是不能直接使用, 需要一些调整.

Cortex Debug 降级到 1.4.4

首先是 Cortex Debug 的版本, 当前版本是 1.10.0, 这个版本运行沁恒的 gdb client 会提示如下错误

ERROR: GDB major version should be >= 9, yours is 8; GDB could not start as expected. Bad installation or version mismatch. See if you can start gdb from a shell prompt and check its version (Must be >= 9)

沁恒定制的这个gcc已经8.3很久了, 等着沁恒升级不太现实, 只能将 Cortex Debug 降级到 1.4.4 使用, 这是支持gcc 8的最后一个版本. 在 VSCode 的扩展中打开 Cortex Debug 的介绍页, 在 Uninstall 右侧的小箭头点击展开, 能看到 Install Another Version 的菜单, 在里面选择 1.4.4 安装

配置文件 launch.json

在 .vscode 目录下新建文件 launch.json, 我使用的配置如下

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Cortex Debug",
            "cwd": "${workspaceFolder}",
            "executable": "${workspaceFolder}/Build/app.elf",
            "request": "launch",
            "type": "cortex-debug",
            "servertype": "openocd",
            "serverpath": "/opt/openocd/wch-openocd-v1.70/bin/openocd",
            "configFiles": [
                "${workspaceFolder}/Misc/wch-riscv.cfg.v1.70"
            ],
            "runToEntryPoint": "main",
            "runToMain": true,          // false: run to reset handler
            "preLaunchTask": "build",   // task from tasks.json
            // "preLaunchCommands": ["Build all"], if not using preLaunchTask
            "showDevDebugOutput": "raw", // log level: parsed, raw, both(include parsed and raw)
            "device": "CH32V208",
            "svdFile": "${workspaceFolder}/Misc/ch32v208xx.svd",
            "toolchainPrefix": "/opt/gcc-riscv/riscv-wch-embedded-gcc-v1.70/bin/riscv-none-embed"
        }
    ]
}

关于配置项的说明:

executable: 指向的是当前项目生成的 elf 文件
servertype: 只能是 openocd
serverpath: 这个很重要, 必须指向沁恒定制的 openocd 可执行文件
configFiles: 当前的 openocd 版本是 1.70, 用仓库里的cfg, 或者用 openocd 同目录下的 wch-ricsv.cfg 都可以
preLaunchTask: 填的是 tasks.json 中配置的任务, 如果找不到这个任务, 启动时会有提示
showDevDebugOutput: 用于在下方的 DEBUG CONSOLE 输出 GDB 日志, 可以选 both, parsed, raw, none, 其中 raw是显示原始内容, parsed 是格式化过的, both 是两种都显示
device: 对于 openocd 貌似可以随便填
svdFile: 标识外设寄存器名称与地址关系的文件, 在debug时可以直接通过寄存器名称查看对应地址的值, 仓库中的 svd 是从沁恒的 MounRiver 开发环境中复制过来的.
toolchainPrefix: 指向沁恒定制的 gcc, 注意是前缀, 不需要带后面的 -gcc

运行 Debug

配置完成后就可以开始 Debug了, 可以通过右侧的 Run And Debug 面板, 点绿色三角形启动, 也可以按 F5启动, 我使用的是 IntelliJ IDEA Keybinding, 所以debug快捷键和 IDEA 是一样的, 单步 F8, 继续 F9, 进入 F7. 在 Run And Debug 面板左侧可以观察变量和外设寄存器对应的值. 非常方便.

Milton