VS Code 使用指南

概述

Ameba 扩展插件是基于 Cline 开发的 VS Code 扩展插件，保留了原生 Cline 的所有功能，并针对 Realtek Ameba 系列芯片增加了开发环境检查和自动安装，SDK 配置、代码编译、固件烧录、串口监控等专用功能。这些功能通过直观的按钮界面提供，简化了 Ameba 系列芯片的开发流程。

Cline 相关资料

• Cline 官方文档

• Cline Github 仓库

• AmebaSerialServer 软件

使用流程

1. 插件的安装

在 VS Code 的扩展应用商店中搜索 Ameba，点击 安装 即可

2. 仅使用 Ameba 功能

• 首次使用的欢迎页面中可以登录 cline 账号或者使用自定义的 API Key

• 当您没有 Cline 账户或 API key 时，可以点击 USE Ameba Only 按钮仅使用 Ameba 相关功能

3. Ameba 相关功能区

下图中的红框展示了 Ameba 相关的功能区域

4. 开发环境检查和自动安装

插件会自动检查如下配置:

• 打开的文件夹和子文件夹内是否包含 Ameba SDK，SDK 的下载请参考 FreeRTOS SDK 下载

• 开发环境的软件合集包是否已正确安装，如果没有安装，将会在右下角提供 Install from GitHub 和 Install from Aliyun 两种安装选项（中国大陆地区用户建议使用 Aliyun），点击即可自动下载安装并创建 Python 虚拟环境

• 如果开发环境的软件合集包已正确安装，但 SDK 的 Python 虚拟环境未正确创建，将会在右下角进行提示，点击 Setup Now 按钮即可自动创建

通过上述所有检查后，插件才会激活 Ameba 相关功能按钮

5. 调试依赖插件安装

插件会自动检查开发环境是否安装调试功能所依赖的插件 Realtek.ride-debug。

• 如果开发环境的 Realtek.ride-debug 未安装，将会在右下角进行提示是否要进行安装，点击 Install Ride Debugger 按钮即可自动安装

• 如果开发环境的 Realtek.ride-debug 已安装但版本低于 1.4.5 ，将会在右下角进行提示是否要卸载重装，点击 Uninstall and reinstall 按钮即可自动卸载并重新安装

6. 芯片选择

通过下拉选择框选择要开发的 Ameba 系列芯片型号

7. 串口选择

自动扫描并更新系统中所有可用串口，通过下拉选择框选择开发板对应的串口名

8. 示例选择

• 通过下拉选择框选择对应的应用示例

• 选择示例后将打开对应示例的 README.md 的预览

• 默认情况下或者选择示例中的 None 将会编译基础项目配置

主要功能

插件可选配置

点击 设置 > 扩展 > Ameba 配置参数。插件支持可选配置如下：

类别	参数	说明
Debug	Adapter Speed	设置调试适配器的时钟频率（kHz），默认值为 4000
Debug	Adapter Type	指定调试适配器的类型： Daplink（默认） Jlink
Debug	Request Type	指定调试请求的类型： Attach（默认）：附加模式。用于连接正在运行的目标芯片。调试开始时，芯片不会被重置，程序从当前运行位置继续执行，保持运行状态。 Launch：启动模式。适用于常规开发。调试开始时会重置芯片，程序从设定的入口函数重新开始执行。
Debug	Run To Entry Point	仅在 Launch 模式下有效。指定程序启动后自动暂停的函数入口（例如 main）。
Debug	All Stop	全停模式，多核调试专用，默认启用。 当任意一个核因命中断点或点击暂停按钮而挂起时，所有核会自动挂起。
Debug	Run Sync	同步运行，多核调试专用，默认禁用。 当点击单步跳过、单步进入或“继续”按钮时，所有核会同步执行相应操作。需配合 All Stop 使用。
Debug	Live Watch	实时监控。配置是否启用变量实时刷新功能（无需暂停 CPU）。
Debug	Live Watch Core	在启用实时监控时设置。指定应用实时监控的目标核。
Debug	Live Watch Samples Per Second	在启用实时监控时设置。设置实时监控数据刷新频率，单位为次/秒。
Flash	Baud Rate	设置烧录波特率，默认值为 2000000 bps。
Flash	Include Vfs	烧录时是否包含 vfs.bin，默认不包含。
Flash	Memory Type	指定 Flash 类型为 Nor 或 Nand，默认 Nor Flash。
Flash	Reset Board	烧录完成后尝试重启设备，默认启用。
Monitor	Enable Log	是否启用监控日志保存功能，默认关闭。
Monitor	Log Directory	指定日志保存文件夹路径，仅在启用 Enable Log 时有效。
Monitor	Reset Board	监控开启时尝试重启设备，默认启用。

SDK 配置

1. 选择目标芯片

2. 点击 Ameba Menuconfig 按钮打开图形化 SDK 配置界面

3. SDK 配置相关信息请参考 配置 SDK（menuconfig）

4. 完成 SDK 配置后，必须保存并正确退出配置界面。如果未正确保存退出，将会影响后续的其余功能正常使用，插件会在右下角弹出提示信息提醒用户

项目清理

1. 选择目标芯片

2. 点击 Ameba Clean 按钮清理工程编译产物

3. 清理过程中将实时显示详细进度和日志信息

项目编译

1. 选择目标芯片

2. 点击 Ameba Build 按钮进行编译工程

• 如果已在下拉选择框选择应用示例，则编译指定示例

• 如果没有选择应用示例或者选择示例中的 None，则编译基础项目配置

3. 编译过程中将实时显示详细进度和日志信息

固件烧录

1. 选择目标芯片和目标串口

2. 参考 插件可选配置 (Flash) 设置烧录参数

3. 点击 Ameba Flash 按钮启动固件烧录流程

4. 根据 SDK 配置和 Flash 布局信息 进行烧录

• 配置异常（如 overlap ）时，将打开 Flash 布局信息 ，同时出现异常提示，方便用户检查

5. 提供烧录进度实时反馈和详细日志

串口监控

1. 选择目标串口

2. 参考 插件可选配置 (Monitor) 设置烧录参数

3. 点击 Ameba Monitor 按钮打开集成的串口监视器，自动选择波特率并连接串口

4. 实时显示和接收串口数据

5. 支持通过串口发送 AT 命令，并且可以根据支持的 ATCMD List 通过 Tab 键 自动补全

6. 支持历史记录功能，按 ↑ 键 可以快速查看和选择之前发送过的命令

代码调试

1. 硬件准备

• 调试适配器

  • 支持 DAP-Link 或 J-Link （任选其一）

• 调试目标芯片

2. 连接步骤

• 将适配器的 SWDIO（ SWD ）连接到目标芯片的 SWD DATA

• 将适配器的 SWCLK（ CLK ）连接到目标芯片的 SWD CLK

• 将适配器 GND 与目标芯片 GND 连接，确保共地

• 将适配器通过 USB 连接到 PC

3. 在插件中选择调试目标芯片

4. 参考 插件可选配置 (Debug) 配置调试参数

5. 点击 Ameba Debug 按钮启动集成的调试器，开始代码调试

备注

1. RTL8730E KM4 内核调试限制：

• 调试前需关闭 tickless 功能，否则会影响调试行为。

2. SWD 引脚差异：

• 不同芯片/封装的 SWD 引脚位置可能不同，请参考对应 PINMUX 表进行确认。

3. 连接稳定性：

• 若连接后无法识别目标，优先检查引脚映射是否正确。

• 若出现连接不稳，可适当降低 SWD 时钟频率。

调试框架

调试框架如下图所示:

1. 目标芯片通过调试适配器与 PC 相连。

2. 启动调试时， OpenOCD（ GDB 服务器）启动。你可以在 VS Code 的终端（ gdb-server ）查看 OpenOCD 输出日志与状态。

3. 工具链内置的 GDB 连接到 OpenOCD ，随后即可进行调试操作。

基础调试技巧

1. 调试工具栏

• 继续：恢复程序运行（默认快捷键 F5 ）。

• 暂停：暂停当前运行的程序（默认快捷键 F6 ）。

• 逐过程：执行当前行但不进入函数内部（默认快捷键 F10 ）。

• 单步调试：逐语句执行并进入函数内部（默认快捷键 F11 ）。

• 单步跳出：从当前函数返回到上层（默认快捷键 Shift+F11 ）。

2. 变量

这是调试时最常用的视图，它会显示当前程序停止位置可见的所有数据。系统会自动分类：

• Local: 当前函数作用域内的局部变量。

• Global: 全局变量。

• Static: 当前文件内的静态变量。

• Registers: 当前 CPU 核的寄存器值。

3. 监视

监视面板允许你监控你关注的变量。通过以下方式监控：

• 查看变量：

  • 在代码中右键点击变量 添加到监视，或在面板中点击 + 号输入变量名。

• 查看任意内存地址：

  • 直接输入地址转换表达式，例如*(int*)0x20000004 ，即可查看该地址的数值。

  • 内存视图：按 F1 输入 MemoryView 打开专用面板，支持查看大块内存区域的 Hex 数据。

• 强制类型转换：

  • 支持 C 语言风格的转换，例如 (char*)my_var 以查看字符串的值。

4. 调用堆栈

当代码逻辑复杂时，调用堆栈能清晰展示 程序执行路径。

• 层级导航：顶层为当前暂停行，第二层为调用者（父函数），依此类推。点击不同层级可跳转查看当时的上下文变量。

5. 多核调试控制

启动多核调试后，调用堆栈视图将列出所有核的调试会话。用户可通过点击视图标题栏上的按钮，在以下两种协作模式间进行切换。

模式	说明
Run Sync	含义：同步运行模式。所有核在暂停状态下，对任一核执行调试控制指令（如 继续、 单步调试 等）时，调试器会自动对所有其他关联的核执行相同的操作 目的：保持多核在时间轴上的同步运行，避免因核运行状态不一致，导致共享内存通信异常或逻辑错误 操作：点击 RS 按钮切换
All Stop	含义：全停模式。当任一核触发暂停条件（如断点）时，所有核均会被强制暂停 目的：确保调试现场的全局一致性；若关闭此模式，则允许对目标核进行独立调试 操作：点击 AS 按钮切换

备注

Run Sync 功能的完整实现通常依赖于 All Stop 机制，二者配合关系如下：

• 开启 All Stop 时，暂停/继续，单步调试动作会在所有核间同步。

• 关闭 All Stop 时，各核行为互不强制同步，适合单核排查。

6. RTOS-Aware

启用 RTOS-Aware 后，调试器能识别操作系统的内部结构。当调试挂起时，调试器将显示出 RTOS 中所有存在的线程。此外，它还允许你查看其他非活动线程的堆栈、寄存器和变量等信息。

多核调试时需要单独控制。在调用堆栈视图中点击 RA 按钮进行切换。

7. 断点管理

断点是调试过程中最常用的工具。当程序运行到断点位置时会自动暂停，允许您检查当前的变量状态或寄存器信息。

断点方式	断点管理
行号点击	添加断点：在编辑器中，直接点击代码行号左侧的空白区域（点击后会出现红点） 查看断点：左侧的 断点 面板，这里列出了所有断点的位置 删除断点：再次点击行号左侧的红点，即可取消该断点
右键菜单	添加断点：在代码区域点击鼠标右键，选择 Add Hardware Breakpoint 查看断点：左侧的 断点 面板，这里列出了所有断点的位置 删除断点：左侧的 断点 面板，选择相应断点删除
调试控制台	添加断点：在调试控制台输入 GDB 命令 b 函数名 （示例： b main，在函数入口暂停） b 函数名 thread ID （示例： b shared_func thread 8，当线程 ID 为 8 的任务运行到该函数时触发） b 行号 （示例： b 100，在当前文件第 100 行暂停） b 文件名:行号 （示例： b main.c:50 ） 查看断点： info b 删除断点： d 断点编号

备注

不同的芯片架构对硬件断点的数量有限制，超过限制可能导致断点无效或转为软件断点。

高级调试功能

1. 实时监视

变量和监视视图需要程序暂停才能刷新，而实时监视允许在程序全速运行时实时观察变量的变化。

• 监视类型：全局变量或者静态变量。

• 添加方式：

  • 在 LIVE WATCH 视图中监控变量的值。点击 + 号，输入变量名。

  • 暂停时，变量视图中所有变量都可以通过右键菜单中点击 Add to live watch 添加到实时监控。

  • 在 XPERIPHERALS 视图中所有寄存器都可以通过右键菜单中点击 Add to live watch 添加到实时监控。

备注

需要在调试开始前在配置中配置实时监控的参数。

2. 外设寄存器

XPERIPHERALS 视图允许查看芯片内部外设寄存器的值。

• 原理：基于芯片的 SVD（ System View Description ）文件，解析寄存器地址和位域。

备注

如果未正确配置 SVD 文件路径，此视图将为空。

3. RTOS 视图

RTOS 内核视图全面展示了由 RTOS 管理的各种内核对象。这些内核对象是嵌入式系统中用于实现任务管理、同步和通信的基础组件。请注意，这些视图仅在调试会话期间可用。

• RTOS-TASK：

  • 显示所有任务的状态（ Running, Ready, Blocked, Suspended ）。

  • 显示任务名称、地址、栈使用率/剩余栈空间（用于排查栈溢出）、运行时间、优先级。

• RTOS-QUEUE：

  • 显示队列的名称、容量、当前消息数、等待该队列的任务列表。

• RTOS-SOFTWARE TIMER：

  • 显示定时器名称、地址、状态（ Active/Inactive，One-shot/Autoreload，Static/Dynamic ）、周期、回调函数名称及地址。

• RTOS-HEAP：

  • 显示动态内存地址范围、分配情况、剩余堆大小、使用率。

• RTOS-TASK NOTIFICATION：

  • 显示任务名称、地址、已接收和正在等待通知的数量。

在线文档

点击 Ameba Doc 按钮将，打开默认浏览器，跳转到 Realtek Ameba 的官方网页

远程功能

如果您本机电脑是 Windows 系统，开发板也连接到本机电脑，但是选择将 SDK 下载到 Linux 服务器，通过 VS Code 的 Remote-SSH 的扩展进行 SDK 的开发，请按照如下步骤进行：

1. 在本机电脑下载 AmebaRemoteService 并启动，启动后默认不配置密码，有安全需要可以右击软件图置密码

2. 在 VS Code 中按下键盘 F1 按键，输入 ameba: Remote Servers，点击对应的选项

3. 点击 Add New Remote Server 选项

Server 名称:

输入想要自定义的服务器名称

Server 地址:

输入 Windows 本机电脑的 IP 地址

Server 密码:

如果 Windows 的服务器软件有配置密码，需要输入对应的密码，如服务器未设置，则直接回车跳过

4. 配置成功后，如果 VS Code 通过 Remote-SSH 连接打开了 Ameba SDK ，串口列表会更新出远程串口信息

5. 再次在 VS Code 中按下键盘 F1 按键，输入 ameba: Remote Servers，点击对应的选项可以查看已有 Server 信息，点击对应已有 Server 可以将其删除

远程串口烧录

1. 选择目标芯片和目标远程串口

2. 参考 插件可选配置 (Flash) 设置烧录参数

3. 点击 Ameba Flash 按钮启动固件烧录流程

4. 提供烧录进度实时反馈和详细日志

远程串口监控

1. 选择目标远程串口

2. 参考 插件可选配置 (Monitor) 设置烧录参数

3. 点击 Ameba Monitor 按钮打开集成的串口监视器，自动选择波特率并连接串口

4. 实时显示和接收串口数据

5. 监控功能和本地监控一致

远程调试

远程调试框架如下图所示:

1. 目标芯片通过调试适配器与本地 Windows PC 相连。

2. 安装在 Windows PC 的 VS Code 通过 SSH 连接到远程服务器。

3. 启动调试时， OpenOCD（ GDB 服务器）由 AmebaRemoteService 在本地 Windows PC 上启动。你可以在 AmebaRemoteService 窗口查看 OpenOCD 输出日志与状态。

4. 部署在远程服务器上的工具链内置的 GDB 连接到本地启动的 OpenOCD ，随后即可进行调试操作。

启动调试步骤：

1. 按照 代码调试 中要求完成硬件连接与基础配置。

2. 在插件中选择目标调试芯片和远程串口。

3. 点击 Ameba Debug 按钮启动集成的调试器。

4. 开启代码调试，调试技巧和 代码调试 所述一致。

故障排除

当使用 Ameba 扩展插件时遇到问题，可以按照以下步骤进行故障排除：

插件安装失败

问题现象： 插件无法正常安装或安装后无法启动

解决方案： 检查系统环境版本要求，确保满足以下最低版本要求：

• VS Code 版本需要 ≥ 1.84.0

• Node.js 版本需要 ≥ 18.16.0

可以通过以下方式检查版本信息：

• 菜单栏 帮助 → 关于 查看版本号

如果版本不满足要求，请先升级到对应版本后重新安装插件。

终端相关问题

问题现象： 插件功能异常、命令执行失败、或界面无响应

解决方案： 插件的核心功能是通过创建一个名为 Ameba 的专用终端来执行，当出现异常时：

• 如果发现 Ameba 终端出现错误或无响应，请手动关闭

• 插件会自动检测，并在下次执行功能时重新创建 Ameba 终端

• 关闭异常终端后，重新点击相应的功能按钮即可正常使用

工具链路径修改后插件异常

问题现象： 修改工具链安装路径后，插件无法正常识别开发环境或功能异常

解决方案： 如果您修改了工具链的安装路径（参考 安装工具链 ），需要执行以下步骤：

• 彻底关闭 VS Code（确保所有 VS Code 窗口都已关闭，仅重新加载窗口是不够的）

• 重新启动 VS Code 并打开 Ameba SDK 项目

• 插件会自动重新检测开发环境配置并更新相关路径信息