ChipRV Studio IDE
基于 VS Code 的集成开发环境：一键创建工程、图形化配置、编译、下载与调试，支持代码补全、语法高亮与多核并行在线调试。
一、软件定位
ChipRV Studio 是一个 Visual Studio Code 扩展，用于统一完成嵌入式工程的配置、 编译、下载、运行与片上调试。它不包含 SDK 源码，也不重新实现编译器、调试器或调试服务， 而是把这些标准工具以及调试与外设查看扩展编排起来，让开发者用图形界面完成原本需要多个终端 手工串联的工作。
可结合已安装的代码补全与 AI 助手扩展辅助阅读、编写代码。AI 能力取决于相应扩展与服务；智能断点建议、自动诊断和性能监控应以实际交付版本为准。
二、系统要求
| 类别 | 要求 |
|---|---|
| 操作系统 | Windows / Linux |
| 宿主软件 | Visual Studio Code 1.85 或更高版本 |
| 构建环境 | Python 3、SCons |
| 编译器 | RISC-V GCC 交叉编译器 |
| 调试器 | RISC-V GDB |
| 在线调试 | 调试服务，且包含目标所需的接口与目标配置文件 |
| 依赖扩展 | 调试扩展、C/C++ 扩展包、外设查看扩展 |
三、安装与工程
3.1 调试界面
ChipRV Studio IDE 将工程操作、源码编辑与调试信息集中在同一工作区。下图标出主要功能区域，便于在调试过程中快速找到操作入口与目标状态。
3.2 安装扩展
- 安装 VS Code。
- 打开扩展面板（
Ctrl+Shift+X）。 - 点击右上角
...，选择从 VSIX 安装。 - 选择随包提供的扩展安装包。
- 自动安装依赖扩展后，重新加载 VS Code。
3.3 打开工程
- 点击 VS Code 左侧活动栏的扩展图标。
- 点击 Open 打开工程目录，或点击 New 创建新工程。
- 点击 Settings，确认 SDK、编译器、调试器、调试服务与固件路径正确。
SDK 根目录必须包含构建入口脚本、预置配置目录与工具目录，否则扩展无法定位构建入口。
四、五类配置
所有图形界面的配置最终都会写入工程根目录的工程配置文件， 因此配置变更可以纳入版本管理并逐行比对，团队之间共享一致的构建与调试环境。
| 页面 | 配置内容 |
|---|---|
| Project | 工程名称、芯片名称、SDK 根目录、工程类型（独立工程 / SDK 预置配置工程） |
| Build | 编译器路径、构建来源、所选预置配置、是否在运行或调试前自动构建 |
| Debugger | 调试服务与调试器可执行文件、接口与目标配置文件、主机地址与各核心 GDB 端口、命令行端口、多核开关与选定核心、启动超时、附加启动命令 |
| Startup | 各核心的固件文件、运行与重启前是否复位、复位类型、停止函数、程序计数器设置、加载后是否继续运行 |
| SVD | 外设描述文件路径，供外设视图解析寄存器与字段 |
4.1 构建来源
构建来源选为 SDK 预置配置时，扩展会先执行一次配置初始化命令，再执行编译命令； 选择独立工程时，则直接在工程目录运行构建命令。两种方式都通过终端输出完整日志， 出错时可直接定位到编译命令本身。
4.2 复位行为
复位类型选为暂停复位时，扩展使用目标级复位命令，按核心分别下发， 而不是对整个芯片做全局复位。
多核模式下不执行全局复位，避免一个核心的复位清除其它核心的共享调试状态。 如需复位，请在针对具体核心的 GDB 会话中执行目标级命令。
五、编译与运行
| 操作 | 行为 |
|---|---|
| Build | 在配置的工作目录执行构建，输出显示在编辑器终端 |
| Clean | 调用构建系统清理；SDK 使用 scons -c 时同时删除 .config，清理前应保存配置 |
| Menuconfig | 在 SDK 根目录打开菜单配置界面，保存后重新构建生成新固件 |
| Run | 检查固件 → 启动调试服务 → 建立调试连接 → 加载固件 → 按启动配置继续执行 → 退出临时会话 |
| Debug | 停止旧会话 → 启动共享调试服务 → 逐个建立各核心调试会话 → 加载固件 → 在停止函数设临时断点 → 暂停并打开源文件 |
| Settings | 修改工程、工具链与调试配置 |
固件必须包含调试信息，即构建配置中启用调试信息选项（编译器加入 -g）。
否则调试时只能看到汇编地址，无法定位到 C 源码行。
六、调试功能
在 C/C++ 源文件行号左侧单击即可设置断点，再次单击删除。断点命中后，编辑器与侧边栏同时呈现 当前停止位置、局部与全局变量、Watch 表达式、调用栈以及外设寄存器。
6.1 变量与寄存器
- 变量视图：显示当前可见的局部变量、全局变量与静态变量。
- Watch：手动添加重点变量、数组或任意表达式。
- 寄存器视图：查看通用寄存器、程序计数器与调试相关寄存器。
- 外设视图：基于 SVD 展开外设寄存器及其字段，含位域、读写属性与复位值。
寄存器内容只代表当前选中核心在当前暂停时刻的状态。目标运行中 部分寄存器无法读取，必须先暂停；多核调试时切换会话后应确认窗口标题中的核心名称， 避免误读其它核心的寄存器。
6.2 源码级单步
| 操作 | 行为 | 适用场景 |
|---|---|---|
| Step Into（步入） | 执行当前行并进入该行调用的函数内部 | 查看函数调用过程与被调函数的参数、局部变量 |
| Step Over（步过） | 执行当前行但不进入被调函数，在调用返回后的下一行暂停 | 快速浏览当前函数逻辑 |
| Step Out（步出） | 继续执行至当前函数返回，在调用者的下一行暂停 | 误入无需查看的函数时快速返回上层 |
单步操作必须在调试会话已连接且目标处于暂停状态时执行；多核调试时，单步只作用于当前选中的核心会话。
6.3 多核调试
多核调试使用一个共享的调试服务进程，为每个选定核心使用独立 GDB 端口。 扩展按序连接各核心，避免多个调试会话同时握手造成协议冲突。后台核心可能先产生停止事件， 扩展会尽量保持当前选定核心的源文件焦点，不让后台核心自动替换编辑器内容。
- 为不同核心分别指定匹配的固件，否则符号、源文件与断点地址会不一致。
- 不要在多核配置中使用全局复位命令。
- 确认各核心的 GDB 端口无冲突，且与目标配置文件中的数量、名称一致。
- 某个核心连不上时，先单独选择该核心验证其配置、固件与端口。
七、配置文件
工程主配置文件包含工程与 SDK 路径、构建目标与预置配置、工具链路径、接口与目标配置、 各核心的固件与端口、启动命令以及外设描述与多核选项。保存配置后，扩展会自动生成或更新 编辑器侧的 IntelliSense、启动与任务配置文件。
下一次保存工程配置时，自动生成文件的内容可能被覆盖。需要定制时应通过配置界面调整。
八、常见问题
| 现象 | 优先检查 |
|---|---|
| 调试器没有启动 | 依赖调试扩展是否安装；调试器路径与固件文件是否存在；查看调试控制台与扩展输出的报错 |
| 配置信息缺失或不正确 | 在配置界面重新指定 SDK、工具链、固件与外设描述文件路径后重试 |
| 源文件路径报错 | 重新保存配置，扩展会把头文件搜索路径重新指向 SDK 的相应目录 |
| 多核窗口自动切换 | 确认使用与当前版本匹配的扩展安装包，并在多核模式下只选择需要调试的核心 |
| 暂停超时 | 调试服务与目标配置版本是否匹配；目标板是否保持连接；是否误用全局复位；是否需要启用看门狗或定时器挂起命令 |
| 远程通信错误 | 调试连接已失效或残留旧会话；先保存文件，再重新加载编辑器窗口后启动调试 |
九、版本升级
安装新版本扩展前建议先卸载旧版；安装完成后重新加载编辑器窗口使扩展生效。 工程配置文件建议提交到版本管理系统，以便跟踪配置变更、在团队之间复用同一套环境。