Debug Protocol Reference Sheet ​

The WARDuino debugger is operated through debug messages that can be sent over various channels. Messages are resolved in order, and the debug message queue is checked before any instruction is executed in the virtual machine.

Overview ​

The table below gives the full list of debug messages that can be sent to a remote WARDuino debugger. Debug messages start with a unique code identifying the instruction, followed by an optional payload. Messages are always ended by a newline.

The following debug messages can be sent by the remote debugger at anytime when a specific event occurs.

Simple Dump Formats ​

The WARDuino debugger provides a variety of debug messages for inspecting different aspects of the VM's state. These debug messages return dumps of information in JSON format.

The VM's state includes both Wasm state (e.g., variables, memory pages) and debugger-specific state (e.g., breakpoints).

Custom Dump Formats ​

Custom dump formats can be generated with the inspect (09) debug message. This is useful for minimizing data transfer sizes, by only requesting specific parts of the VM's state.

The following table lists the different components of the VM's state that can be requested separately:

The payload of an inspect debug message starts with the number of requested components, followed immediately by the IDs of those components in no particular order.

Example ​

Requesting the program counter and global variables can be done with the following debug message:

0900020104\n

This debug message consists of the following parts:

• 09: the inspect debug operation code which tells the debugger what kind of debug message it received.
• 0002: the number of states that the tool client wants to request. This number is a hexadecimal number encoded as Big Endian 16.
• 0104: the IDs of the requested components.
  • 01: ID for the program counter.
  • 04: ID for the global variables.
• The newline \n that marks the end of the debug message.

The response will be "DUMP!" followed by the JSON containing the requested state, starting on the next line:

DUMP!
{"pc":7174,
 "globals":[
    {"idx":0,"type":"i32","value":0},
    {"idx":1,"type":"i32","value":1}
    ]
 }

Stepping Behaviour ​

There are different methods for stepping through Wasm code:

• step into. Step over a single Wasm instruction and respond with STEP!.
• step over. Step over any direct of indirect call and respond with the current address AT [address]!, otherwise step over a single instruction and respond with STEP!.

Breakpoints ​

Breakpoints are identified by the address of their Wasm instruction. The addresses are LEB128 encoded when passed as arguments to debug messages; add breakpoint (06) and remove breakpoint (07).

The address included in the breakpoint-hit notification, is not LEB128 encoded, but returned as a positive decimal integer.

Whenever a breakpoint is encountered the execution is paused, even when currently stepping over a call with the step over (05) debug message.

Additional Information ​

The Halt (02) debug message stops the virtual machine, while the Reset (13) debug message reloads the current program.

Out-of-place Debugging ​

WARDuino also supports out-of-place debugging through the EDWARD debugger. A similar overview of the debug messages for EDWARD can be found in this reference sheet.