SCRYDOSBox-XReferenceReaddisassembleAlso in MAME
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
brick_hit.Show me the first instructions of the routine that runs when a brick is hit.
disassemble(ref="brick_hit", length=12){
"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
{
"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:OFFaddress. - 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,sequentialorunknown. - flow_source
- What classified the lines:
capstone, the decoder. - code_bits
- 16 or 32, the width the code was decoded in.
code_bits_fromsays 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,symbolanddelta. - seg_off
- The address
refresolved 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
- A
lengththat runs past the end of a 16-bit segment, where the cpu wraps; the refusal names the most bytes that fit (bad_argument). - The null selector, or one with no descriptor, in protected mode (
bad_argument). - A symbol the loaded table lacks (
unknown_ref), or one it holds twice (ambiguous_ref). - Whatever
memdumprefuses: the bytes are read the same way.
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:
jcandjb,jncandjae,popadandpopal,callandlcallfor 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 throughFE 38, so the pane reads it ascallback. Here it is a byte no instruction starts with.
Related tools
The contract your client receives
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.