TRACE.PY(1)

NAME
trace.py - simulate code execution in a 48K or 128K memory snapshot

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/Z80 snapshot, WAV file or PNG file 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.

--ay
    Capture AY audio (when writing a WAV file).

--ay-mode MODE
    Set the AY stereo mode to ABC, ACB or MONO (the default).

--ay-res T
    Set the AY sampling resolution to this many T-states. The default value of 622 is equivalent to 5700Hz, which is usually good enough for capturing AY speech. A higher value such as 70908 (50Hz) is usually good enough for capturing AY music, and may also require less time to produce the WAV file.

--beeper
    Capture beeper audio (when used with --ay).

-c, --cmio
    Simulate memory and I/O contention delays and the MEMPTR register.

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

--map FILE
    Log addresses of executed instructions to a file.

-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} before execution begins. 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'.

--screen
    Display screen contents and respond to keypresses while running (requires pygame). The left shift key is mapped to CAPS SHIFT on the Spectrum keyboard, and the left Ctrl key is mapped to SYMBOL SHIFT.

--state name=value
    Set a hardware state attribute before execution begins. Do --state help for more information, or see the section on HARDWARE STATE below. This option may be used multiple times.

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

--volume VOL
    Set audio volume percentage (default: 100).

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, memptr, pc, r, sp

HARDWARE STATE

The --state option sets a hardware state attribute before execution begins.
--state name=value

Recognised attribute names and their default values are:
7ffd    - last OUT to port 0x7ffd (128K only)
ay[N]   - contents of AY register N (N=0-15; 128K only)
border  - border colour
fe      - last OUT to port 0xfe (SZX only)
fffd    - last OUT to port 0xfffd (128K only)
iff     - interrupt flip-flop: 0=disabled, 1=enabled
im      - interrupt mode
tstates - T-states elapsed since start of frame

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:

PNGScale
    The PNG image scale factor (default: 2).

Screen
    Display screen contents while running (1), or don't (0, the default).

ScreenFps
    Screen refresh rate in frames per second (default:50). If set to 0, trace.py runs at maximum speed.

ScreenScale
    Screen scale factor (default: 2).

TraceHeader
    The header to print when -v is used (default: None).

TraceHeader2
    The header to print when -vv is used (default: None).

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
    m[address] - the contents of a memory address
    pc - the address of the current instruction (program counter)
    r[X] - the 'X' register (see below)
    t - the current timestamp (in T-states)

    When using the m (memory) replacement field, address must be either a decimal number, or a hexadecimal number prefixed by '$' or '0x'.

    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 memptr

    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

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

AUTHOR
Richard Dymond

COPYRIGHT
2026, Richard Dymond