Skip to main content
Glama
xw1998

Mdkdebug

by xw1998
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

等待断点命中（带超时）

wait_breakpoint
Read-onlyIdempotent

Wait until the target hits a breakpoint or watchpoint within a timeout, then return verified hit address, hit count, wait, and source location to confirm that a function executed.

Instructions

带超时地等待目标停在断点上：轮询目标状态，一旦停止就读取 PC（含收敛判定与「是否真的停住」复查），回落到源码位置，返回 hit / hit_address / hit_count / waited_ms。用来确证「App 是否真的调用到内核某函数」，不必再靠读 PC 猜、也不必手工循环 get_status。symbol 传符号名（如 svcrt_ptable_lookup，自动解析为地址）；address 传 0x 地址；两者都不传时用工程 .uvoptx 里的持久化断点作候选（use_project_breakpoints 控制）。命中后返回里直接带 file/line/callstack，并累计该地址命中次数（breakpoint_stats 可查全部）。只认「本次等待期间新发生的停止」：若调用时目标已停着（典型——刚被 run_timeout 停在某行再调本工具），那次停止不计为命中，会返回 hit=false、stop_is_new=false、ran_during_wait=false 且 note 说明「目标在等待期间未曾运行」，避免把「进来时已停」误报成「等到了断点命中」。故正确用法是先 run（或 reset 后 run）再调本工具；调用时先给一个很短的宽限窗口确认目标是真想跑（run 是异步命令，响应会滞后），若窗口内没见运行且 PC 相对调用时没有移动，才判为旧停止。注意：命中判定为「目标已停止 且 PC 等于候选地址」（自动兼容 Thumb 位），并额外支持数据观察点命中——数据断点触发时 PC 不等于观察地址，判定链路按证据强度递减：① 等待前后各读一次 Keil 断点表的 CNT，某条 CNT 增加即为命中项；② 读 DFSR(0xE000ED30)：等待开始前先清零（DFSR 为 W1C），命中后若 DWTTRAP(bit2) 置位即判为观察点命中，并用 DWT_COMPn 定位命中的是哪个观察点——这是硬件证据；真机实测（UVSOCK@4823 + STM32F401）本版 Keil 的 BL CNT 是断点计数条件设置值、不随命中递增，此时由 ② 接手；③ ①② 都取不到时才退化为「目标已停止 + PC 不在任何代码候选 + 存在观察点」推断为观察点命中。返回 hit_kind（code/watch）、hit_confidence（verified=有 PC/CNT/DFSR 实际证据，inferred=纯推断）、hit_entry（source 字段：pc/cnt/dfsr/inferred）、dfsr / dfsr_note（DFSR 原始值与解读）与 cnt_note（说明判定依据强度）；候选来源除 symbol/address/.uvoptx 外，还包含本服务 set_watchpoint 设的数据观察点，以及在无其他候选时取 Keil 真实断点表（list_breakpoints.real）中的执行断点；若本该命中却一直不停，先用 list_breakpoints / list_uvoptx_breakpoints 确认断点存在且启用（App 侧重定位后运行时地址与符号地址不同，应传实际运行地址）。需已进入调试。另附 reset_loop 字段（批次67）：同一断点在 3 秒内命中 ≥3 次时，判定「这是不是复位循环在重跑启动」——suspected=true 表示有复位证据（命中在 Reset_Handler / SP 等于向量表里的 initial SP / CYCCNT 回退），false 表示没到阈值，null 表示反复命中了但主机侧分不清复位循环与正常热循环（这时要人工核对启动时序，别硬猜）。判据来自镜像基址处的向量表（anchor 字段给出 image_base / initial_sp / reset_handler 及合法性校验）。与 repeat_warning 不是一回事：repeat_warning 说的是「同一 PC 连续出现，疑似 halt 残留值，别当反复复位看」，两者前提与结论都不同，不可互相顶替。 【参数】必填: 无；可选: symbol, address, timeout_s, poll_ms, use_project_breakpoints, project, reloc_delta 【调用示例】{} 【参数别名】symbol ← addr/expression/func/function/keyword/location/name/pattern/pc/query/target/var/variable；timeout_s（秒） ← duration/duration_ms/duration_s/max/max_ms/max_s/seconds/timeout/timeout_ms/wait/wait_ms/wait_s；poll_ms（毫秒） ← interval/interval_ms/interval_s/poll/poll_interval_ms/poll_s；带 _s/_ms 的别名按后缀换算（_s=秒、_ms=毫秒）。规范名以上方【参数】行为准；未列出的参数名会被拒绝，不会静默忽略

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
symbolNo
addressNo
poll_msNo
projectNo
timeout_sNo
reloc_deltaNo
use_project_breakpointsNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.8

TDQS

A4/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses detailed behavioral traits, such as clearing DFSR (a write operation) and accumulating hit counts, which directly contradict the annotations readOnlyHint=true and idempotentHint=true. Since it explicitly describes non-read-only side effects, this is a clear annotation contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely long and dense, covering many edge cases and technical details. While it is well-organized and front-loaded with the main purpose, it is not concise; several paragraphs could be trimmed or moved to auxiliary documentation without losing essential guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description is remarkably complete: it covers preconditions (must be in debug), stale-stop handling, hit detection algorithms, data watchpoint support, confidence levels, reset-loop detection, fallback tools, and return value semantics. An agent would be well-equipped to invoke this tool correctly without further clarification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description compensates by thoroughly explaining each parameter: symbol vs address vs project breakpoints, timeout_s, poll_ms, use_project_breakpoints, project, and reloc_delta. It also provides alias mappings and unit conversions, far exceeding the sparse schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states exactly what the tool does: wait with a timeout for the target to stop at a breakpoint, poll status, read PC with convergence checks, and return hit/hit_address/hit_count/waited_ms. It explicitly distinguishes itself from manually reading PC or looping get_status, making its purpose clear and distinct from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: it is for confirming an App actually reached a kernel function, and recommends using run (or reset+run) before calling. It also warns that a pre-existing stop will not count, and suggests checking list_breakpoints if the breakpoint never hits, clearly directing the agent to alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools