probe-web / @probe-web/client / index / Debugger

Class: Debugger

Defined in: debugger.ts:353

Run control and inspection for one core: pause, continue, step, reset, breakpoints, stack traces, scopes and variables, registers and memory, plus RTT and semihosting output while debugging. Get one from Session.debugger.

Calls are serialised, so they can be issued from anywhere without interleaving. Frame ids and variable references belong to one stop: once the core resumes (Debugger.epoch changes) they are rejected with kind: 'stale-reference'.

Events (all CustomEvents; call Debugger.start to have them fire on their own):

• stopped — the core halted; detail is a StoppedDetail.
• continued — the core is running again.
• state — any change of RunState; detail is the new state.
• locked-up — the core locked up.
• breakpoints — the breakpoint list changed; detail is every Breakpoint.
• output — RTT or semihosting text; detail is a DebugOutput.
• rtt-bytes — data from a binary RTT channel; detail is an RttBytes.
• error — the status poller failed; detail is the error.

Example

const dbg = session.debugger();
dbg.addEventListener('stopped', async () => {
  const [frame] = await dbg.stackTrace();
  const scopes = await dbg.scopes(frame.id);
  const locals = scopes.find((s) => s.name === 'Variables');
  if (locals) console.log(frame.functionName, await dbg.variables(locals.reference));
});
dbg.start();
await dbg.loadDebugInfo(elfBytes, 'app.elf');
await dbg.setSourceBreakpoints('src/main.rs', [{ line: 42 }]);
await dbg.resetAndHalt();
await dbg.continue();
// later
await dbg.step('over');
dbg.dispose();

Extends

• EventTarget

Constructors

Constructor

new Debugger(session, options?): Debugger;

Defined in: debugger.ts:387

Apps normally use Session.debugger; tests can pass a fake session here.

Parameters

Parameter	Type
session	DebugSessionLike
options	DebuggerOptions

Returns

Debugger

Overrides

EventTarget.constructor

Properties

Property	Modifier	Type	Default value	Description	Defined in
session	readonly	DebugSessionLike	undefined	The session this debugger drives.	debugger.ts:355
coreIndex	readonly	number	undefined	Index of the core it controls.	debugger.ts:357
core	readonly	DebugCoreLike	undefined	That core.	debugger.ts:359
epoch	public	number	0	Increments whenever the core resumes; results tied to a stop carry it.	debugger.ts:369
state	public	RunState	'unknown'	The core's state as last seen (by the poller, or by the debugger's own calls).	debugger.ts:382
lastStop	public	StoppedDetail | null	null	The current stop, or null while the core is not halted.	debugger.ts:384

Accessors

canDisassemble

Get Signature

get canDisassemble(): boolean;

Defined in: debugger.ts:1023

Whether this connection can disassemble. probe-rs serve can; the WebUSB worker cannot (probe-rs uses capstone, which is C code). Views should show that instead of an error.

Returns

boolean

Methods

refresh()

refresh(): Promise<RunState>;

Defined in: debugger.ts:448

Current status, read now (not from the poller).

Returns

Promise<RunState>

---

start()

start(): void;

Defined in: debugger.ts:469

Start polling core/status (idempotent). Stops on dispose().

Returns

void

---

dispose()

dispose(): void;

Defined in: debugger.ts:490

Stop the poller. The debugger does not detach or resume the core.

Returns

void

---

registerTable()

registerTable(): Promise<RegisterInfo[]>;

Defined in: debugger.ts:521

Register names, ids and widths for this core.

Returns

Promise<RegisterInfo[]>

---

pause()

pause(): Promise<StoppedDetail>;

Defined in: debugger.ts:528

Halt; emits stopped with reason Request.

Returns

Promise<StoppedDetail>

---

continue()

continue(): Promise<void>;

Defined in: debugger.ts:537

Resume. Clears the server's per-core debug state first, so no stale frame or variable ids survive.

Returns

Promise<void>

---

step()

step(mode): Promise<{
  pc: bigint;
  warning: string | null;
}>;

Defined in: debugger.ts:551

Step (instruction needs no debug info; the others need loadDebugInfo). Emits stopped with reason Step. Resolves with the new program counter and, when the step did not go exactly as asked (e.g. step out timed out before reaching the caller), a warning to show the user.

Parameters

Parameter	Type
mode	SteppingMode

Returns

Promise<{ pc: bigint; warning: string | null; }>

---

reset()

reset(): Promise<void>;

Defined in: debugger.ts:664

Reset and keep running. Breakpoints are armed again (see resetAndHalt).

Returns

Promise<void>

---

resetAndHalt()

resetAndHalt(): Promise<StoppedDetail>;

Defined in: debugger.ts:690

Reset and halt at the reset vector; emits stopped. Breakpoints are armed again afterwards: a reset clears the hardware comparators on some targets (MCX family, ESP32-S3).

Returns

Promise<StoppedDetail>

---

enableVectorCatch()

enableVectorCatch(condition): Promise<void>;

Defined in: debugger.ts:709

Halt the core when it takes this exception (e.g. HardFault, CoreReset).

Parameters

Parameter	Type
condition	WireVectorCatchCondition

Returns

Promise<void>

---

loadDebugInfo()

loadDebugInfo(elf, name?): Promise<void>;

Defined in: debugger.ts:717

Upload an ELF (content-hash cached on the server) and load its DWARF. Needed for statement stepping, source breakpoints, stack traces with names, and every variables query.

Parameters

Parameter	Type	Default value
elf	Uint8Array	undefined
name	string	'firmware.elf'

Returns

Promise<void>

---

loadSvd()

loadSvd(svd, name?): Promise<void>;

Defined in: debugger.ts:730

Load a CMSIS-SVD file; its peripherals appear as the Peripherals scope.

Parameters

Parameter	Type	Default value
svd	Uint8Array	undefined
name	string	'device.svd'

Returns

Promise<void>

---

clearSvd()

clearSvd(): Promise<void>;

Defined in: debugger.ts:735

Unload the SVD, removing the Peripherals scope.

Returns

Promise<void>

---

stackTrace()

stackTrace(limit?): Promise<Frame[]>;

Defined in: debugger.ts:775

Stack frames of the current stop (taken once per stop, then cached). The core must be halted.

Parameters

Parameter	Type	Default value
limit	number	200

Returns

Promise<Frame[]>

---

scopes()

scopes(frameId): Promise<Scope[]>;

Defined in: debugger.ts:792

Scopes of a frame: Static, Peripherals (with an SVD), Registers, Variables.

Parameters

Parameter	Type
frameId	number

Returns

Promise<Scope[]>

---

variables()

variables(reference, filter?): Promise<Variable[]>;

Defined in: debugger.ts:807

Children of a scope or variable. filter: indexed or named to page large aggregates.

Parameters

Parameter	Type
reference	number
filter?	"indexed" | "named"

Returns

Promise<Variable[]>

---

evaluate()

evaluate(expression, frameId?): Promise<Evaluation>;

Defined in: debugger.ts:831

Look up a register, a variable in the frame, or a static by name (probe-rs has no expression parser).

Parameters

Parameter	Type
expression	string
frameId?	number

Returns

Promise<Evaluation>

---

setVariable()

setVariable(variable, value): Promise<Evaluation>;

Defined in: debugger.ts:844

Write a variable's value (parsed by probe-rs for the variable's type). Registers: use writeRegister.

Parameters

Parameter	Type
variable	Pick<Variable, "name" | "parent">
value	string

Returns

Promise<Evaluation>

---

breakpoints()

breakpoints(): Breakpoint[];

Defined in: debugger.ts:867

Every breakpoint, source then instruction.

Returns

Breakpoint[]

---

setSourceBreakpoints()

setSourceBreakpoints(path, specs): Promise<Breakpoint[]>;

Defined in: debugger.ts:936

Replace the breakpoints in one source file (as DAP setBreakpoints does). path may be the absolute build path or a relative suffix such as src/main.rs. Needs debug info.

Parameters

Parameter	Type
path	string
specs	{ line: number; column?: number; }[]

Returns

Promise<Breakpoint[]>

---

setInstructionBreakpoints()

setInstructionBreakpoints(addresses): Promise<Breakpoint[]>;

Defined in: debugger.ts:949

Replace all instruction (address) breakpoints.

Parameters

Parameter	Type
addresses	(number | bigint)[]

Returns

Promise<Breakpoint[]>

---

clearBreakpoints()

clearBreakpoints(): Promise<void>;

Defined in: debugger.ts:974

Remove every breakpoint from the target.

Returns

Promise<void>

---

reapplyBreakpoints()

reapplyBreakpoints(): Promise<Breakpoint[]>;

Defined in: debugger.ts:989

Set every breakpoint again: after loading a new ELF (source lines may map elsewhere) or on targets that lose comparators on reset (MCX family, ESP32-S3); reset/resetAndHalt call it.

Returns

Promise<Breakpoint[]>

---

resolveSourceLocations()

resolveSourceLocations(addresses): Promise<(SourceLocation | null)[]>;

Defined in: debugger.ts:1011

Source locations for addresses (null where there is no line information).

Parameters

Parameter	Type
addresses	(number | bigint)[]

Returns

Promise<(SourceLocation | null)[]>

---

disassemble()

disassemble(
   address, 
   count, 
   instructionOffset?, 
   byteOffset?
): Promise<Instruction[]>;

Defined in: debugger.ts:1032

Disassemble count instructions starting at address shifted by instructionOffset instructions (negative looks backwards, as DAP disassemble does). Needs probe-rs serve: over WebUSB it rejects with kind: 'unsupported' (see Debugger.canDisassemble).

Parameters

Parameter	Type	Default value
address	number | bigint	undefined
count	number	undefined
instructionOffset	number	0
byteOffset	number	0

Returns

Promise<Instruction[]>

---

enableRtt()

enableRtt(options?): Promise<void>;

Defined in: debugger.ts:1057

Show the firmware's RTT output while debugging: creates an RTT client (with an exact scan region when elf links _SEGGER_RTT) and polls its up channels whenever the poller runs (start()); output arrives as output events. Semihosting output is reported the same way without calling this.

Parameters

Parameter	Type
options	{ elf?: Uint8Array<ArrayBufferLike>; channels?: RttChannelConfigInput[]; }
options.elf?	Uint8Array<ArrayBufferLike>
options.channels?	RttChannelConfigInput[]

Returns

Promise<void>

---

pollRtt()

pollRtt(): Promise<void>;

Defined in: debugger.ts:1068

Read RTT once now (the poller does this while the core runs).

Returns

Promise<void>

---

readRegisters()

readRegisters(): Promise<RegisterValue[]>;

Defined in: debugger.ts:1118

Read every register in the table; registers the core does not have are left out.

Returns

Promise<RegisterValue[]>

---

writeRegister()

writeRegister(register, value): Promise<void>;

Defined in: debugger.ts:1133

Write a register by name (case-insensitive) or id. The core must be halted.

Parameters

Parameter	Type
register	string | number
value	bigint

Returns

Promise<void>

---

readMemory()

readMemory(address, count): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: debugger.ts:1145

Read up to count bytes; a shorter result means the rest is unreadable.

Parameters

Parameter	Type
address	number | bigint
count	number

Returns

Promise<Uint8Array<ArrayBufferLike>>

---

writeMemory()

writeMemory(address, data): Promise<void>;

Defined in: debugger.ts:1150

Write bytes starting at address.

Parameters

Parameter	Type
address	number | bigint
data	Uint8Array

Returns

Promise<void>