SCRYDOSBox-XReferenceWritedebugAlso in MAME

DOSBox-XWrite

debug

Send one command to the debugger and read what it printed, for what no other tool does.

debug(command)

Try it

On Bricks, the game this repository builds, at any stop.
Ask

Show me the FPU registers.

Call
debug(command="FPU")
Reply 4 of 5 fields
{
  "summary": "debug 'FPU': 460 chars",
  "command": "FPU",
  "output": "status: B=0 C3-C0=0000 ES=0 SF=0 PE=0 UE=0 OE=0 ZE=0 DE=0 IE ... (261 characters)",
  "clipped": false
}

output holds what the debugger's FPU command printed, shown here cut short: the whole reply below has it all. No other tool reads the FPU's registers.

The whole reply
JSON
{
  "summary": "debug 'FPU': 460 chars",
  "status": "ok",
  "command": "FPU",
  "output": "status: B=0 C3-C0=0000 ES=0 SF=0 PE=0 UE=0 OE=0 ZE=0 DE=0 IE=0 TOP=0\n st(0): empty use80=0 val=0 (0x0000000000000000)\n st(1): empty use80=0 val=0 (0x0000000000000000)\n st(2): empty use80=0 val=0 (0x0000000000000000)\n st(3): empty use80=0 va ... (460 characters)",
  "clipped": false
}

Arguments

command string, required
One debugger command, as you would type it at the debugger's command line.

What comes back

output
What the debugger printed. Past 4000 characters it is cut: clipped is true and output_path names a file with all output_chars of it.
note
Set when the debugger did not take the command: it does not know it, or refused it for the reason output shows.
All 5 reply fields
  • clipped (boolean)
  • command (string)
  • output (string)
  • output_chars (integer)
  • output_path (string)

What it refuses

Why it works this way

A command that lets the program run is refused before it is sent. It would leave the debugger without the session knowing, and status and last_stop would go on naming the stop before it. A line break would carry a second command past that check.

A command that writes to the machine, such as SM or LOADSTATE, marks the session: every later reply carries altered in its session block.

The contract your client receives
Text
One raw `command` to the debugger; the last resort. For a value use `registers`,
`read_memory` or `memdump`; for the log `log`.

Reply: `command`, `output`, `clipped`, `note` (when the debugger did not take the command);
past 4000 characters the text goes to a file (`output_chars`, `output_path`).

Refused `bad_argument`: a command that lets the guest run (`RUN`, `VRT`, `RUNWATCH`, `INT`,
`STEPIN`, the `LOG` family) and a control character.
Tools