trace.py

SYNOPSIS

trace.py [options] FILE [OUTFILE]

DESCRIPTION

trace.py simulates the execution of machine code in a 48K, 128K or +2 SNA, SZX or Z80 snapshot, or a binary (raw memory) file. If FILE is ‘48’, ‘128’ or ‘+2’, no snapshot is loaded, and the RAM is left blank (all zeroes). If ‘OUTFILE’ is given, an SZX or Z80 snapshot is written after execution has completed.

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.

-c, --cmio

Simulate memory contention and I/O contention delays.

–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.

-I, –ini param=value

Set the value of a configuration parameter (see CONFIGURATION), overriding any value found in skoolkit.ini. This option may be used multiple times.

-m, –max-operations MAX

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

-M, –max-tstates MAX

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

-n, --no-interrupts

Don’t execute interrupt routines.

-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 [p:]a[-b[-c]],[^+]v

POKE N,v in RAM bank p 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’.

--python

Use the pure Python Z80 simulator even if the C version is available.

-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.

--show-config

Show configuration parameter values.

-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

CONFIGURATION

trace.py will read configuration from a file named skoolkit.ini in the current working directory or in ~/.skoolkit, if present. The recognised configuration parameters are:

TraceLine:

The format of each instruction line when -v is used (default: ${pc:04X} {i}).

TraceLine2:

The format of each instruction line when -vv is used. Use --show-config to see the default value.

TraceLineDecimal:

The format of each instruction line when -Dv is used (default: {pc:05} {i}).

TraceLineDecimal2:

The format of each instruction line when -Dvv is used. Use --show-config to see the default value.

TraceOperand:

The prefix, byte format, and word format for the numeric operands of instructions, separated by commas (default: $,02X,04X); the byte and word formats are standard Python format specifiers for numeric values, and default to empty strings if not supplied.

TraceOperandDecimal:

As TraceOperand when -D is used (default: ,,).

The TraceLine* parameters are standard Python format strings that recognise the following replacement fields:


i - the current instruction
pc - the address of the current instruction (program counter)
r[X] - the ‘X’ register (see below)
t - the current timestamp (in T-states)

The register name X in r[X] must be one of the following:

a b c d e f h l bc de hl
^a ^b ^c ^d ^e ^f ^h ^l ^bc ^de ^hl
ix iy ixh iyh ixl iyl
i r sp

The names that begin with ^ denote the shadow registers.

Wherever \n appears in a TraceLine* parameter value, it is replaced by a newline character.

Configuration parameters must appear in a [trace] section. For example, to make trace.py write a timestamp for each instruction when -v is used, add the following section to skoolkit.ini:

[trace]
TraceLine={t:>10} ${pc:04X} {i}

Configuration parameters may also be set on the command line by using the --ini option. Parameter values set this way will override any found in skoolkit.ini.

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