insns

Tool tools/triage/insns.py (program, Triage). List every instruction of a kind in a program: every port read or write, every interrupt, every timer read, every division, every far call.

Run it with ./gameframe run insns ARGS or python3 tools/triage/insns.py. Source on GitHub.

Its own help

This is the help text in the tool itself, as ./gameframe tool insns prints it.

List every instruction of a kind in a program: every port read or write, every interrupt,
every timer read, every division, every far call. Then break on each one, or read them all.

Usage: insns.py BINARY PATTERN [PATTERN ...] [--functions functions.tsv] [--json]
       insns.py RAW PATTERN ... --raw --bits 16|32|64 --base ADDR

  PATTERN     a regular expression matched against "mnemonic operands", as capstone writes
              them: '^in ', '^out ', '^int 0x21', '^rdtsc', '^f?div', 'cs:', '^lcall'
  --functions a Ghidra export's functions.tsv, to name the function each instruction is in
  BINARY      a Windows PE (its code sections, virtual addresses) or a DOS MZ program (its
              load image, addresses as Ghidra's 1000:offset); --raw for any other code

Some questions are answered by a short list. A game that reads the joystick does it with
`in al, dx` at port 0x201; one that programs the timer writes port 0x40 and 0x43; one that
talks to a Sound Blaster writes ports 0x220 to 0x22F; one that asks the BIOS for the time
calls interrupt 0x1A; one that measures the CPU uses rdtsc. A game's floating point is a
handful of fdiv and fsqrt instructions. List them, set a breakpoint on each, and the one
that stops when the thing happens is the one to trace. Groups that matter:

  '^(in|out|ins|outs)'      hardware ports: the docs/observe/inputs.md tables name them
  '^int '                   BIOS and DOS services; the AH value set just before says which
  '^(rdtsc|cpuid)'          CPU timing and identification (also anti-debugging checks)
  '^(f|)i?div'              divisions, where rounding matters to a port

The disassembly is a linear sweep of the code sections, so data inside code can show as stray
instructions: check each hit in Ghidra. Needs capstone (.venv).

Named by

Skills: re-trace.