trace.py¶
SYNOPSIS¶
trace.py
[options] FILE [OUTFILE]
DESCRIPTION¶
trace.py
simulates the execution of machine code in a 48K or 128K binary
(raw memory) file or a SNA, SZX or Z80 snapshot. If FILE is ‘48’ or ‘128’, 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 inskoolkit.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’.
- -r, –reg name=value
Set the value of a register before execution begins. Do
--reg help
for more information, or see the section onREGISTERS
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 instructionpc
- 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¶
Execute and show instructions in the routine at 32768-32798 in
game.z80
:
trace.py -v -s 32768 -S 32798 game.z80
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