跳到主要内容

5.5 在线调试与断点视图​

ChipON VSCode Extension 基于定制优化的 LLDB + OpenOCD 架构，为 KF32 系列微控制器提供专业的嵌入式在线调试体验，支持硬件断点、数据观察点、外设寄存器位域解析、内存直接读写、源码-反汇编对照以及 FreeRTOS 实时内核监控。

调试配置​

项目的调试任务定义在 .vscode/launch.json 文件中。新建工程时插件默认预置了两种模式：

.vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "KF32-LLDB: Launch",
      "type": "kf32-lldb",
      "request": "launch",
      "programBeforeDebug": false,
      "startSettings": {
        "startmode": "main",
        "port": 3333
      }
    },
    {
      "name": "KF32-LLDB: Attach",
      "type": "kf32-lldb",
      "request": "attach",
      "startSettings": {
        "startmode": "halt",
        "port": 3333,
        "openocdReadyTimeout": 5000
      }
    }
  ]
}

调试核心参数解析​

参数项数据类型说明
nameString该调试会话配置在 VSCode 调试下拉栏中的显示名称
typeString调试适配器类型，固定为 kf32-lldb
requestString启动请求类型，支持 launch（烧录并启动调试）与 attach（附加到当前正在运行的芯片）
elfPathString (可选)目标可执行 ELF 文件路径。默认无需配置，插件会自动拉取当前 Build Preset 生成的 .elf 文件
programBeforeDebugBoolean进入调试会话前是否先触发烧录（默认为 false）
startSettings.startmodeString启动行为。launch 模式下为 main（停在主入口），attach 模式下为 halt（立即挂起）
startSettings.portNumberGDB/LLDB Server 与芯片通信的端口号（默认 3333）
startSettings.openocdReadyTimeoutNumber调试底层服务初始化超时时间，单位毫秒（默认 5000 ms）

自定义 OpenOCD 配置文件​

除内置 OpenOCD 模板外，插件支持使用项目内的自定义配置文件启动 OpenOCD。只要项目根目录下存在 .vscode/chipon_openocd.cfg，调试（Launch / Attach）以及通过 OpenOCD 执行的烧录流程都会使用该文件，无需修改 launch.json。

生成配置文件​

可通过以下任一方式生成：

  • PROJECTS 视图：右键项目根节点，选择 生成 OpenOCD 配置文件。
  • 命令面板：按 Ctrl + Shift + P，执行 ChipON: 生成 OpenOCD 配置文件（命令 ID：chipon.generateOpenocdCfg）。

插件会根据当前芯片选择对应的内置模板，生成 .vscode/chipon_openocd.cfg 并自动打开。文件顶部的注释列出了全部可用占位符及其含义。

备注

若 .vscode/chipon_openocd.cfg 已存在，生成前会提示是否覆盖，覆盖后自定义内容将丢失。

模板变量​

配置文件中可使用以下占位符，启动 OpenOCD 时由插件自动替换：

占位符说明
{{activePath}}KFLINK 虚拟串口设备路径；Windows 下形如 //./COMx，使用 J-Link 时为空
{{startmode}}调试请求类型，取值为 launch 或 attach（来自 launch.json 的 request）
{{debugKeyLine}}KFLINK 调试鉴权行；未配置鉴权密文时为空
{{range}}当前芯片的 range 值
{{port}}GDB Server 端口，默认 3333，对应 startSettings.port
{{openocdid}}每次启动 OpenOCD 时生成的唯一 ID

使用说明​

  • 占位符在每次启动 OpenOCD 时重新渲染；插件渲染的是临时副本，不会修改 .vscode/chipon_openocd.cfg 源文件。
  • 双花括号 {{ }} 为插件保留语法，请勿用于其他用途；插件无法识别的占位符会被渲染为空字符串，可能导致 OpenOCD 报错。
  • 修改配置文件后，重新启动调试或烧录即可生效。
  • 删除 .vscode/chipon_openocd.cfg 后，插件会自动回退到内置模板。
  • 通过 OpenOCD 烧录时，{{activePath}}、{{startmode}}、{{debugKeyLine}} 渲染为空，请避免在这些流程中依赖上述变量。

示例​

生成文件的核心内容如下（占位符保留原样）：

.vscode/chipon_openocd.cfg
adapter driver kflink

kflink backend vcp
kflink vcp port {{activePath}}

kflink mode A
kflink startmode {{startmode}}

{{debugKeyLine}}

transport select dpi

set _CHIPNAME kf32

dpi newtap $_CHIPNAME cpu

target create $_CHIPNAME.cpu kf32_{{range}} -chain-position $_CHIPNAME.cpu

gdb breakpoint_override hard

启动调试会话​

开发者可通过以下任一方式启动调试：

  1. PROJECTS 视图：展开项目根节点，点击右侧的 调试 (Debug) 图标（🐞），或右键选择 Show Debug。
  2. 运行与调试视图：按快捷键 Ctrl + Shift + D 打开 VSCode 原生调试侧边栏，选择目标配置后按 F5。

打开调试视图

启动调试

调试操作​

进入调试会话后，编辑器顶部将显示调试浮动工具栏，提供对目标微控制器的执行控制：

图标操作快捷键功能说明
Continue (继续运行)F5继续全速运行程序，直到命中下一个断点或发生异常
Step Over (单步跳过)F10执行当前行代码。遇到函数调用时执行完函数整体，停在下一行
Step Into (单步进入)F11执行当前行代码。遇到函数调用时步入该函数体首行
Step Out (单步跳出)Shift+F11执行完当前函数并跳出，返回上一层调用处
Reset (芯片复位)—点击调试浮动栏中的绿色复位图标，重置芯片并停在 startup 启动函数入口
Stop (停止调试)Shift+F5断开与调试器的连接，终止当前调试会话
反汇编模式下的单步执行

当当前处于反汇编视图（Disassembly View）时，Step Over 与 Step In 的单步步长将自动由“源代码行”切换为“单条汇编机器指令”。

各控制操作界面展示​

  • Continue 操作： Continue 操作

  • Step Over 操作： Step Over 操作

  • Step In 操作： Step In 操作

  • Reset 芯片复位操作： Reset 操作

调试断点​

硬件断点资源限制

KF32 芯片硬件断点单元具备数量限制：

  • 程序断点（普通/条件/触发/日志断点共用）：硬件支持最多 4 个
  • 数据观察点 (Watchpoint)：硬件支持最多 2 个

超过硬件限制时，多余断点可能无法成功触发或导致调试器报错。

1. 普通行断点 (Line Breakpoint)​

  • 设置：在源文件或反汇编视图的行号左侧单击，出现红色实心圆点。
  • 管理：右击断点可选择禁用/启用，也可在调试面板的 BREAKPOINTS 列表中统一勾选控制。

普通断点

2. 条件断点 (Conditional Breakpoint)​

  • 设置：在行号左侧单击右键，选择 Add Conditional Breakpoint...。
  • 求值规则：支持输入由 LLDB 动态求值的 C 语法布尔表达式，如 i == 10 或 ptr != 0 && *ptr == 0x5A。满足条件时才挂起程序。

条件断点

3. 触发断点 (Triggered Breakpoint)​

  • 概念：仅在指定的“父断点”被命中至少一次后，该断点才会被激活。
  • 设置：在行号左侧右键选择 Add Triggered Breakpoint...，并关联前置断点。

触发断点

选择触发断点条件

4. 日志断点 (Logpoint)​

  • 概念：命中断点时不暂停程序执行，而是将格式化信息打印至 Debug Console 调试控制台，常用于替代嵌入式代码中的临时 printf。
  • 设置：右键行号选择 Add Logpoint...，直接输入插值字符串（如 Counter val: {g_counter}）。

日志断点

5. 数据观察点 (Watchpoint)​

  • 概念：对特定变量或物理内存地址的读/写/读写操作进行实时监控，当目标地址被访问时自动挂起。
  • 设置：在 Variables 变量列表中右键变量选择 Break on Value Change，或在 BREAKPOINTS 面板点击 Add Data Breakpoint at Address 手动指定起始地址与检测长度。

设置 Watchpoint

调试专业视图​

VSCode 运行与调试界面提供了 8 类专业嵌入式视图：

1. Variables (变量视图)​

实时展示当前函数调用栈帧中的局部变量（Local）、静态变量（Static）、全局变量（Global）以及内核寄存器（Registers）。

  • 实时刷新：单步执行时变动数值将以高亮颜色标记；
  • 在线改值：双击数值可直接修改变量当前内存值；
  • 结构体展开：支持展开结构体、数组及指针成员。

变量视图

2. Watch (监视视图)​

允许开发者手动添加常驻监视表达式，即使变量离开了当前局部作用域，仍会持续跟踪其全局值或复杂运算式（如 g_sensor.data[0] * 3.3 / 4096）。

监控视图

3. Call Stack (函数调用堆栈视图)​

时间倒序展示当前中断或暂停发生时的函数调用链。点击各栈帧可回溯调用处源码上下文；右键某帧选择 Open Disassembly View 可展开该函数对应的机器反汇编。

Call Stack 视图

打开反汇编视图操作

4. Breakpoints (断点管理视图)​

统一检索和批量管理当前工作区中的所有断点，支持一键临时禁用全部断点（Deactivate Breakpoints）或按需移除。

断点视图

5. Memory (内存查看与编辑视图)​

以十六进制（HEX）和 ASCII 码双格式展现目标芯片内存的原始内容，支持排查缓冲区越界、指针错位及堆栈溢出。

  • 唤出方式：在变量视图右键选择 Show in Memory Inspector，或按快捷键通过命令面板执行 Show Memory Inspector；
  • 交互：输入物理地址或表达式（如 0x20000000 或 &my_buffer）即可精准定位；双击十六进制单元可直接覆写内存字节。

打开内存视图操作

内存视图

6. Peripheral Registers (外设寄存器视图)​

嵌入式开发专属视图，将微控制器内部特殊功能寄存器（SFR）的抽象地址直观还原为具体外设（如 GPIOA、USART1、CAN0）。

  • 位域拆解 (Bitfields)：将 32 位寄存器按位拆解为独立控制字段（如 ENABLE, MODE, PRESCALER），显示独立标志位状态；
  • 实时控制：在调试暂停时可直接勾选或修改位域值，实现不重新编译直接在线点灯、配置波特率或清除中断标志；
  • 过滤筛选：支持通过右上角过滤按钮筛选仅显示当前关注的外设模块。
刷新条件

外设寄存器视图仅在调试会话处于激活且微控制器处于 暂停 (Paused) 状态时方可读取并渲染数据。

外设寄存器视图

过滤外设寄存器

选择需要显示的外设寄存器

过滤外设寄存器后显示效果

7. Disassembly (反汇编视图)​

显示当前 CPU 实际执行的底层机器汇编指令，标有精确内存地址、相对函数入口偏移量及十六进制机器码，并支持汇编与 C 语言源码交替对照。

反汇编视图

8. OS View (FreeRTOS 实时内核监控)​

专用于监控基于 FreeRTOS 操作系统的嵌入式任务体系。插件在目标挂起时通过读取芯片内存中的 FreeRTOS 内核控制块，可视化呈现系统运行状态：

  • Task：任务列表、执行状态（Ready/Blocked/Running）、优先级与堆栈剩余水位线；
  • Timer：软件定时器列表与剩余计时周期；
  • Queue：消息队列使用率与阻塞等待任务；
  • Dump：内核系统级状态转储。
运行环境限制

OS View 仅支持运行了 FreeRTOS 内核的固件，且仅在调试暂停（Halt）状态下动态拉取并刷新内核数据。

OS 视图