SCRYDOSBox-XReferenceReaddisassembleAlso in MAME

DOSBox-XRead

disassemble

Disassemble the code at an address, one instruction a line, each marked as a call, a branch, a return or none of those.

disassemble(ref, length=16)

Try it

On Bricks, the game this repository builds, stopped on its play screen with its symbols loaded and a comment written on brick_hit.
Ask

Show me the first instructions of the routine that runs when a brick is hit.

Call
disassemble(ref="brick_hit", length=12)
Reply 4 of 11 fields
{
  "summary": "disassemble brick_hit: 4 lines at 08DF:000002C8, 16-bit",
  "code_bits": 16,
  "lines": [
    "08DF:000002C8 88DF                 mov bh, bl // AL = row, B ... (94 characters)",
    "08DF:000002CA 88C3                 mov bl, al",
    "08DF:000002CC E81FFF               call 0x1ee",
    "08DF:000002CF C6842C0600           mov byte ptr [si + 0x62c] ... (63 characters)"
  ],
  "flow": ["sequential", "sequential", "call", "sequential"]
}

Four 16-bit instructions from brick_hit; the first ends with the comment written on it. flow marks the third as a call and the others as sequential, plain instructions.

The whole reply
JSON
{
  "summary": "disassemble brick_hit: 4 lines at 08DF:000002C8, 16-bit",
  "status": "ok",
  "ref": "brick_hit",
  "seg_off": "08DF:000002C8",
  "length": 12,
  "code_bits": 16,
  "code_bits_from": "real mode",
  "lines": ["08DF:000002C8 88DF                 mov bh, bl // AL = row, BL = column of the brick that falls", "08DF:000002CA 88C3                 mov bl, al", "08DF:000002CC E81FFF               call 0x1ee", "08DF:000002CF C6842C0600           mov byte ptr [si + 0x62c], 0"],
  "flow": ["sequential", "sequential", "call", "sequential"],
  "flow_source": "capstone",
  "resolved": [
    {
      "line": 2,
      "operand": "0x1ee",
      "kind": "target",
      "seg_off": "08DF:000001EE",
      "addr": "0x00008fde",
      "symbol": "brick_index",
      "delta": 0
    }
  ]
}

Arguments

ref string, required
Where to start: a symbol or a SEG:OFF address.
length integer (>= 1, <= 1024), default 16
How many bytes to decode, 1 to 1024; left out, 16. The last instruction is completed even when it runs past them.

What comes back

lines
One x86 instruction a line: SSSS:OOOOOOOO, its bytes, its text. A line with a comment ends // <text>.
flow
One word per line: call, branch, return, sequential or unknown.
flow_source
What classified the lines: capstone, the decoder.
code_bits
16 or 32, the width the code was decoded in. code_bits_from says where that width was read.
resolved
Only with symbols loaded: each direct call or branch target and memory operand, with its address and nearest symbol. Rows carry line, operand, kind, register, seg_off, addr, symbol and delta.
seg_off
The address ref resolved to, as segment and offset.
All 9 reply fields
  • code_bits (integer)
  • code_bits_from (string)
  • flow (array)
  • flow_source (string)
  • length (integer)
  • lines (array)
  • ref (string)
  • resolved (array)
  • seg_off (string)

What it refuses

Why it works this way

The debugger has no disassembly command, so capstone decodes the bytes read from memory. A byte no instruction starts with is listed as .byte 0x.. and marked unknown.

The width is the segment's own, never the cpu mode's alone. Real mode is 16-bit; protected mode takes it from the stop for CS, from SELINFO for a segment another register holds, and from the descriptor tables otherwise.

More on why

In resolved, kind is target or memory. A memory operand is read through the segment register named in register, as it stands at this stop. Outside the loaded table's range, symbol and delta are unavailable.

Checked against the debugger's own disassembly

Each listing is checked line by line against the debugger's own code pane, and its bytes against what read_memory reads. The two agree on address, length, bytes, mnemonic and operands, and may differ in spelling alone:

  • One instruction under two names: jc and jb, jnc and jae, popad and popal, call and lcall for a far call.
  • A string instruction's implicit operands, which the pane leaves out, and a size word it leaves out where a register fixes the size.
  • A symbol the pane prints in place of an operand's number.
  • FE /7, which is no x86 instruction: DOSBox-X enters its own code through FE 38, so the pane reads it as callback. Here it is a byte no instruction starts with.
The contract your client receives
Text
Decode `length` bytes from `ref` (a symbol or `SEG:OFF`) as x86, one instruction a line. The
last is completed unless the segment ends first. A line a comment is placed on ends
` // <text>`.

Reply: `ref`, `seg_off`, `length`, `code_bits`, `code_bits_from`, `lines`, `flow` (per line:
`call`, `branch`, `return`, `sequential`, `unknown`), `flow_source`, and with symbols loaded
`resolved` (direct call/branch targets and memory operands: `line`, `operand`, `seg_off`,
`addr`, `symbol`, `delta`).

Refused: `length` out of range or past the end of a 16-bit segment; `memdump`'s refusals
apply.

Reference: REFERENCE.md, Reading and writing.
Tools