📚 课程目录第4章开发环境搭建

4、开发环境搭建：安装MounRiver Studio、配置调试器（WCH-Link）、创建工程、编译下载与串口调试流程

沁恒RISC-V CH32系列MCU的开发，官方主推的IDE是MounRiver Studio（以下简称MRS）。MRS基于Eclipse框架深度定制，内置了RISC-V GCC工具链、调试插件、Flash下载算法以及针对CH32系列的芯片支持包。本章将完整梳理从零开始的环境搭建过程，涵盖IDE安装、WCH-Link调试器配置、工程创建、编译下载以及串口调试的完整闭环。对于初学者而言，这一章是进入嵌入式开发的第一道门槛；对于有经验的工程师，本章也能帮助规避许多因工具链版本不匹配或调试器配置不当而引发的低级错误。

上图展示了从安装到调试的完整链路。下面将按照实际操作顺序，逐步拆解每个环节的具体步骤、关键参数与常见问题。

4.1 MounRiver Studio 安装与首次启动

核心原理：MRS 并非简单的 Eclipse 换皮，它针对沁恒 RISC-V 芯片做了大量底层适配。其内置的 GCC 工具链（riscv-none-embed-gcc 或 riscv64-unknown-elf-gcc）支持 RV32IMAC 指令集，并带有沁恒特有的链接脚本和启动文件。安装包中已集成 OpenOCD 的定制版本，用于与 WCH-Link 通信。

操作流程：

获取安装包：从沁恒官网（www.wch.cn）下载最新版 MRS 安装程序。注意区分 Windows 与 Linux 版本。
安装过程：双击安装包，建议保持默认路径（如 C:\MounRiverStudio）。安装过程中会提示安装驱动，务必勾选“WCH-Link 驱动”和“USB 转串口驱动（CH340/CH9102）”。
首次启动：启动 MRS，选择工作空间目录（建议使用英文路径，避免中文或空格导致编译异常）。
确认工具链：点击菜单栏 窗口 → 首选项 → RISC-V，查看工具链路径是否正确。若路径为空，手动指定 MRS 安装目录下的 toolchain 文件夹。

经验提醒：安装完成后，建议先创建一个空工程并编译一次，以验证工具链是否正常。若编译报错“riscv-none-embed-gcc: 找不到命令”，请检查环境变量或重新安装。

4.2 WCH-Link 调试器配置与模式切换

核心原理：WCH-Link 是一款多功能调试器，支持 RISC-V 和 ARM 两种架构。对于 CH32V 系列（RISC-V 内核），必须将 WCH-Link 切换到 RISC-V 模式；对于 CH32F 系列（ARM Cortex-M3），则需切换到 ARM 模式。模式切换通过 WCH-Link 上的 Mode 按键实现，不同模式对应不同的指示灯颜色（通常 RISC-V 为蓝色，ARM 为绿色）。

接线规范：

WCH-Link 引脚	CH32 目标板引脚	说明
3V3	VDD (3.3V)	电源输出（若目标板自供电，可不接）
GND	GND	共地必须连接
SWDIO	PA13 (SWDIO)	数据线
SWCLK	PA14 (SWCLK)	时钟线
TX	PA10 (USART1_RX)	调试器发送 → 目标板接收
RX	PA9 (USART1_TX)	目标板发送 → 调试器接收

风险提示：切勿在目标板供电的情况下同时连接 WCH-Link 的 3V3 引脚，否则可能因电压差异导致芯片损坏。建议使用“共地不共电”的方式，即只连接 GND、SWDIO、SWCLK，目标板独立供电。

模式切换操作：将 WCH-Link 插入 PC USB 口，按住 Mode 按键约 2 秒，指示灯颜色变化即表示切换成功。在 MRS 中，点击 运行 → 调试配置 → WCH-Link，确认接口类型选择为“SWD”，目标芯片型号与工程一致。

4.3 创建工程与芯片选型

操作流程：

点击 文件 → 新建 → MounRiver RISC-V 工程。
在弹出对话框中，输入工程名称（如 CH32V307_GPIO_LED），选择保存位置。
在“芯片型号”下拉列表中，选择对应的具体型号（如 CH32V307VCT6）。注意区分 Flash 大小和封装。
选择工程模板：建议选择“空工程”或“带启动文件和链接脚本的模板”。对于初学者，推荐选择“Hello World”模板，该模板已包含串口初始化代码。
点击“完成”，MRS 会自动生成启动文件（startup_ch32v30x.S）、链接脚本（link.ld）以及系统初始化文件（system_ch32v30x.c）。

工程结构解析：

core 目录：包含内核相关文件，如中断控制、系统时钟初始化。
peripheral 目录：包含外设驱动库（如 GPIO、USART、SPI 等）。
debug 目录：包含调试相关的配置文件。
User 目录：用户主函数 main.c 所在位置。

案例拆解：假设我们需要点亮 CH32V307 评估板上的 LED（连接在 PC13 引脚）。在 main.c 中编写如下代码：

#include "debug.h"
void GPIO_Toggle_INIT(void)
{
    GPIO_InitTypeDef GPIO_InitStructure = {0};
    RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOC, ENABLE);
    GPIO_InitStructure.GPIO_Pin = GPIO_Pin_13;
    GPIO_InitStructure.GPIO_Mode = GPIO_Mode_Out_PP;
    GPIO_InitStructure.GPIO_Speed = GPIO_Speed_50MHz;
    GPIO_Init(GPIOC, &GPIO_InitStructure);
}
int main(void)
{
    Delay_Init();
    GPIO_Toggle_INIT();
    while(1)
    {
        GPIO_WriteBit(GPIOC, GPIO_Pin_13, Bit_SET);
        Delay_Ms(500);
        GPIO_WriteBit(GPIOC, GPIO_Pin_13, Bit_RESET);
        Delay_Ms(500);
    }
}

4.4 编译、下载与串口调试

编译操作：点击工具栏上的锤子图标（或按 Ctrl+B）进行编译。编译信息会在“控制台”窗口输出。若出现错误，双击错误信息可跳转到对应代码行。常见的编译错误包括：未包含头文件、引脚号写错、语法错误等。

下载操作：确保 WCH-Link 已连接且目标板已上电。点击“下载”按钮（或按 F4），MRS 会调用 OpenOCD 通过 SWD 协议将生成的 .hex 文件烧录到芯片 Flash 中。下载成功后，控制台会显示“Download successful”字样。

串口调试流程：

使用 USB 线连接 WCH-Link 的 USB 口到 PC（若目标板有独立串口芯片，则直接连接目标板的串口）。
打开 MRS 内置的串口终端：窗口 → 显示视图 → 其他 → 终端。
在终端窗口中，点击“打开串口”图标，设置参数：波特率 115200，数据位 8，停止位 1，无校验。
在代码中调用 printf("Hello CH32\r\n"); 或 USART_SendData() 函数，即可在终端中看到输出。

常见误区：很多初学者在串口调试时发现乱码，原因往往是波特率不匹配或 GND 未共地。另外，CH32V 系列默认使用内部 HSI 时钟（8MHz），若未配置 PLL 倍频，串口波特率会不准确。建议在 main 函数开头调用 SystemInit() 并配置外部晶振（如 8MHz 或 25MHz）。

总结复盘：本章节的核心在于建立“IDE + 调试器 + 目标芯片 + 串口工具”的完整工具链认知。在实际项目开发中，建议按照以下顺序排查问题：先检查硬件连接（电源、GND、SWD 线序），再确认调试器模式，然后检查工程配置（芯片型号、Flash 大小），最后才是代码逻辑。MRS 的编译下载速度较快，适合日常开发迭代。对于量产烧录，建议使用 WCH-Link 配合官方烧录软件 WCHISPTool 进行离线烧录，以提高效率。