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 helpfor more information, or see the section onREGISTERSbelow. 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=valueFor example:
--reg hl=32768--reg b=0x1fTo set the value of an alternate (shadow) register, use the ‘^’ prefix:
--reg ^hl=10072Recognised 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, spEXAMPLES¶
Execute and show instructions in the routine at 32768-32798 in
game.z80:
trace.py -v -s 32768 -S 32798 game.z80Show 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