浏览器脚本 DAP API
入口为 Web 工作台「脚本」(当前固定在浏览器执行)。DAP 由页面注入;板上 QuickJS、Node.js SDK 没有这个全局对象。以下内容从当前前端帮助同步生成。
请求与响应单包最大 64 字节,便捷内存接口会拆分。目标控制接口用于 Cortex-M,不是通用 RISC-V 调试接口。
入门:连接目标与运行模式
仅用于“浏览器”运行模式,DAP 对象由页面自动提供,无需 import。每次通信都使用 await;地址、频率和数据均为数字。频率单位 Hz,等待时间单位 ms。initSWD() 初始化接口并请求调试域供电,不暂停或复位 CPU;attach() 默认暂停 CPU。脚本正常结束、异常或点击停止时,运行器会关闭自己的 DAP 会话。
await DAP.initSWD({frequency: 1000000})
const cpuid = await DAP.read32(0xE000ED00)
console.log('CPUID = 0x' + cpuid.toString(16))内存与外设寄存器读写
read32(address, ap=0) 返回无符号 32 位整数,地址须 4 字节对齐。write32(address,value,ap=0) 写入一整个 32 位字。readMemory(address,length,ap=0) 返回 Uint8Array;writeMemory(address,data,ap=0) 接受字节数组,返回写入字节数,按地址递增。AP 默认 0。内存读取不会自动暂停 CPU,但目标必须允许运行时调试访问;外设读取可能有清除标志等副作用。以下写入示例针对 STM32F103 的 GPIOC,目标需已启用 GPIOC 时钟并配置 PC13 为输出。
const bytes = await DAP.readMemory(0x20000000, 16)
console.log(Array.from(bytes).map(v => v.toString(16).padStart(2, '0')).join(' '))
// STM32F103: BSRR, PC13=0 then PC13=1
await DAP.write32(0x40011010, 0x20000000)
await sleep(500)
await DAP.write32(0x40011010, 0x00002000)
// RAM byte write example (only use a scratch area owned by your application):
// await DAP.writeMemory(0x20000000, [0x78, 0x56, 0x34, 0x12])Cortex-M:连接、暂停、复位与寄存器
attach({protocol:"swd",frequency:1000000,halt:true}) 连接并识别目标,返回 cpuid、halted、dhcsr 及 SWD 的 dpidr 或 JTAG 的 idcode。不想暂停请传 halt:false。halt() 暂停,run() 继续,reset() 软件复位后运行,reset({halt:true}) 复位后暂停。reg(15) 读取 PC,reg(13) 读取 SP,regs() 返回通用寄存器对象;必须先暂停才能读取这些 CPU 寄存器。它们不适用于 RISC-V。halt/run/reset/reg/regs 的 options 支持 timeout(ms)、ap;不会自动保存与恢复目标应用状态。
const target = await DAP.attach({halt: false})
console.log(target)
await DAP.halt({timeout: 1000})
try {
console.log('PC:', await DAP.reg(15))
console.log(await DAP.regs())
} finally {
await DAP.run()
}
// await DAP.reset()
// await DAP.reset({halt: true})JTAG:IR 长度、链与使用边界
initJTAG({frequency,irLengths}) 初始化 JTAG,不自动枚举链。irLengths 按实际器件链填写;通用 initJTAG 默认 [5],ARM JTAG-DP 通常用 [4]。jtagIdcode(index) 返回指定索引的 32 位 IDCODE。jtagSequence() 可自定义 TMS/TDI 和采样 TDO;即使 capture:true 也需提供 TDI 数据。Cortex-M 高级访问用 attach({protocol:"jtag",irLengths:[4]}),目前访问链中 DAP 索引 0。RISC-V 可使用原始 JTAG 时序,但不能使用 Cortex-M 的 halt/reg 等接口。
await DAP.initJTAG({frequency: 1000000, irLengths: [5]})
console.log('IDCODE:', (await DAP.jtagIdcode(0)).toString(16))
// ARM Cortex-M JTAG (separate session):
// await DAP.attach({protocol:'jtag', irLengths:[4], halt:false})
// console.log(await DAP.read32(0xE000ED00))底层 DP/AP 与 CMSIS-DAP 命令
transfer(items,{dapIndex:0}) 批量访问 DP/AP,每项为 {port:"DP"或"AP",address,read:true} 或 {port,address,value}。返回 {count,status,ack,data,raw},data 只含读取结果;部分完成会抛异常,详情在 error.response。readDP/writeDP 使用 DP 寄存器地址,readAP/writeAP 可指定 {ap,bank}。command(op,payload) 的 payload 不含命令号,返回含命令号的完整 Uint8Array。原始包请求/响应均上限 64 字节;大块数据使用内存接口自动拆包。queueCommands 只在浏览器排队,executeCommands 使用 0x7F。手工 SELECT/TAR/CSW 会影响后续目标访问。
const raw = await DAP.command(0x00, [0x02]) // DAP_Info: product
console.log(Array.from(raw))
// After initSWD():
const result = await DAP.transfer([
{port:'DP', address:0, read:true}
])
console.log(result.count, result.ack, result.data)共享读取、会话释放与错误处理
readTargetMemory(address,length,{protocol:"current"}) 读取 RTT Viewer 已连接的目标;协议可选 swd/jtag/rvswd/current。一次最多 65536 字节,按 256 字节块调度,跨块不是原子快照。readTarget32 返回 32 位值。无共享目标时默认不自动连接;仅 {protocol:"swd",fallback:true} 可尝试独立短 SWD 会话。不同接口返回 interface_mismatch;目标变化、等待超时或其他调试器占用会抛异常。原始会话按 Connect→读写→Disconnect 保持事务完整,不能随意插入 GDB/USB 的访问。debugger_busy/queue_timeout 可含 owner。不要自动重试未知结果的写入或复位;可用 disconnect() 提前释放,脚本结束也会自动释放。
try {
const bytes = await DAP.readTargetMemory(0x20000000, 16, {
protocol: 'swd', fallback: true
})
console.log(Array.from(bytes))
} catch (error) {
console.error(error.message, error.owner || '')
if (error.response) console.error(error.response)
}方法签名速查
DAP.info(id=2)
DAP.hostStatus(type, status)
DAP.connect(port=1)
DAP.disconnect()
DAP.transferConfigure(idle=0, waitRetry=100, matchRetry=0)
DAP.transfer([{port:"DP", read:true, address:0}], {dapIndex:0})
DAP.transferBlock({port:"AP", read:true, address:12, count:1, data:[], dapIndex:0})
DAP.transferAbort(dapIndex=0)
DAP.writeAbort(value=0x1e, dapIndex=0)
DAP.delay(us)
DAP.resetTarget()
DAP.swjPins(output, select, waitUs=0)
DAP.swjClock(hz)
DAP.swjSequence(data, bitCount)
DAP.swdConfigure({turnaround:1, dataPhase:false})
DAP.swdSequence([{clocks:3, capture:true}])
DAP.jtagSequence([{clocks:8, tms:0, capture:true, data:[0]}])
DAP.jtagConfigure([irBits])
DAP.jtagIdcode(index=0)
DAP.swoTransport(mode=1)
DAP.swoMode(mode=1)
DAP.swoBaudrate(hz)
DAP.swoControl(enabled=true)
DAP.swoStatus()
DAP.swoData(maxBytes=60)
DAP.swoExtendedStatus(flags=7)
DAP.uartTransport(mode=2)
DAP.uartConfigure(control, baudrate)
DAP.uartTransfer(data=[], maxReceive=0)
DAP.uartControl(control)
DAP.uartStatus()
DAP.queueCommands([[op, ...payload], ...])
DAP.executeCommands([[op, ...payload], ...])
DAP.command(op, payload=[])
DAP.initSWD({frequency:1000000, powerTimeout:1000})
DAP.initJTAG({frequency:1000000, irLengths:[5]})
DAP.readDP(address)
DAP.writeDP(address, value)
DAP.readAP(address, {ap:0, bank:0})
DAP.writeAP(address, value, {ap:0, bank:0})
DAP.attach({protocol:"swd", frequency:1000000, halt:true, timeout:1000, ap:0})
DAP.halt({timeout:1000, ap:0})
DAP.reset({halt:false, timeout:1000, ap:0})
DAP.run({timeout:1000, ap:0})
DAP.reg(selector, {timeout:1000, ap:0})
DAP.regs({timeout:1000, ap:0})
DAP.readTarget32(address, {protocol:"current"})
DAP.readTargetMemory(address, length, {protocol:"current", fallback:false})
DAP.read32(address, ap=0)
DAP.write32(address, value, ap=0)
DAP.readMemory(address, length, ap=0)
DAP.writeMemory(address, data, ap=0)