trace.py

SYNOPSIS

trace.py [options] FILE

DESCRIPTION

trace.py simulates the execution of machine code in a 48K binary (raw memory) file or a SNA, SZX or Z80 snapshot. If FILE is ‘.’, no snapshot is loaded, and the RAM is left blank (all zeroes).

OPTIONS

--audio

Show a list of the delays (in T-states) between changes in the state of the ZX Spectrum speaker made by the code that was executed.

–depth N

Simplify audio delays to this depth (default: 2). When this option is given, any sequence of delays up to length N that repeats is shown in a simplified form. For example, if N is 3, the run of delay values [1, 2, 3, 1, 2, 3] is reduced to [1, 2, 3]*2.

-D, --decimal

Show decimal values in verbose (-v, -vv) mode.

–dump FILE

Dump a Z80 snapshot to this file after execution.

–max-operations MAX

Maximum number of instructions to execute. Overrides the STOP address (if given).

–max-tstates MAX

Maximum number of (simulated) T-states to run for. Overrides the STOP address (if given).

-o, –org ORG

Specify the origin address of a binary (raw memory) file. The default origin address is 65536 minus the length of the file. ORG must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

-p, –poke a[-b[-c]],[^+]v

POKE N,v for N in {a, a+c, a+2c…, b}. Prefix ‘v’ with ‘^’ to perform an XOR operation, or ‘+’ to perform an ADD operation. This option may be used multiple times. ‘a’, ‘b’, ‘c’ and ‘v’ must each be a decimal number, or a hexadecimal number prefixed by ‘0x’.

-r, –reg name=value

Set the value of a register before execution begins. Do --reg help for more information, or see the section on REGISTERS below. This option may be used multiple times.

–rom FILE

Patch in a ROM at address 0 from this file. By default the 48K ZX Spectrum ROM is used.

-s, –start ADDR

Start execution at this address. ADDR must be a decimal number, or a hexadecimal number prefixed by ‘0x’. If this option is omitted, execution starts either at the address given by the value of the program counter (for a SNA, SZX or Z80 snapshot), or at the origin address of the raw memory file.

-S, –stop ADDR

Stop execution at this address. ADDR must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

--stats

Show statistics after execution.

-v, --verbose

Show executed instructions. Repeat this option (-vv) to show register values too.

-V, --version

Show SkoolKit version number and exit.

REGISTERS

The --reg option sets the value of a register before execution begins.


--reg name=value

For example:


--reg hl=32768
--reg b=0x1f

To set the value of an alternate (shadow) register, use the ‘^’ prefix:


--reg ^hl=10072

Recognised register names are:


^a, ^b, ^bc, ^c, ^d, ^de, ^e, ^f, ^h, ^hl, ^l,
a, b, bc, c, d, de, e, f, h, hl, l,
i, ix, iy, pc, r, sp

EXAMPLES

  1. Execute and show instructions in the routine at 32768-32798 in game.z80:


trace.py -v -s 32768 -S 32798 game.z80
  1. Show delays between changes in the state of the ZX Spectrum speaker produced by the sound effect routine at 49152-49193 in game.z80:


trace.py --audio -s 49152 -S 49193 game.z80