SNA2SKOOL.PY(1)

NAME
sna2skool.py - convert a binary file or a snapshot into a skool file

SYNOPSIS

sna2skool.py [options] FILE

DESCRIPTION

sna2skool.py converts a binary (raw memory) file or a SNA, SZX or Z80 snapshot into a skool file. The skool file is written to standard output. When FILE is '-', sna2skool.py reads from standard input.

OPTIONS

-c, --ctl PATH
    Specify a control file to use, or a directory from which to read control files. By default, any files whose names start with the input snapshot name (minus the .bin, .sna, .szx or .z80 suffix, if any) and end with .ctl are used, if present. If PATH is '-', standard input is used. If PATH is '0', no control file is used. This option may be used multiple times.

-C, --comments
    Generate instruction comments.

-d, --defb SIZE
    Disassemble as DEFB statements of this size (instead of as code).

-e, --end ADDR
    Stop disassembling at this address; the default end address is 65536. ADDR must be a decimal number, or a hexadecimal number prefixed by '0x'.

-H, --hex
    Write hexadecimal addresses and operands in the disassembly.

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

-l, --lower
    Write the disassembly in lower case.

-o, --org ADDR
    Specify the origin address of a binary (.bin) file; the default origin address is 65536 minus the length of the file. ADDR must be a decimal number, or a hexadecimal number prefixed by '0x'.

-p, --page PAGE
    Specify the page (0-7) of a 128K snapshot to map to 49152-65535.

-r, --handle-rst
    Handle RST instruction arguments.

--show-config
    Show configuration parameter values.

-s, --start ADDR
    Start disassembling at this address; the default start address is 16384 for a snapshot, or the origin address for a raw memory file. ADDR must be a decimal number, or a hexadecimal number prefixed by '0x'.

-V, --version
    Show the SkoolKit version number and exit.

-w, --line-width WIDTH
    Set the maximum line width of the skool file (79 by default).

CONFIGURATION

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

Base
    Write addresses and instruction operands in hexadecimal (16) or decimal (10, the default).

Case
    Write the disassembly in lower case (1) or upper case (2, the default).

Comments
    Generate instruction comments (1), or don't (0, the default).

CommentWidthMin
    Minimum width of the instruction comment field in the skool file (default: 10).

DefbSize
    Maximum number of bytes in a DEFB statement (default: 8).

DefmSize
    Maximum number of characters in a DEFM statement (default: 65).

DefwSize
    Maximum number of words in a DEFW statement (default: 1).

EntryPointRef
    Template used to format the comment for an entry point with exactly one referrer (default: This entry point is used by the routine at {ref}.).

EntryPointRefs
    Template used to format the comment for an entry point with two or more referrers (default: This entry point is used by the routines at {refs} and {ref}.).

HandleRST
    Handle RST instruction arguments (1), or don't (0, the default).

InstructionWidth
    Minimum width of the instruction field in the skool file (default: 13).

LineWidth
    Maximum line width of the skool file (default: 79).

ListRefs
    When to add a comment that lists routine or entry point referrers: never (0), if no other comment is defined at the entry point (1, the default), or always (2).

Opcodes
    Comma-separated list of values specifying additional opcode sequences to disassemble (see below).

Ref Template used to format the comment for a routine with exactly one referrer (default: Used by the routine at {ref}.).

RefFormat
    Template used to format referrers in the {ref} and {refs} fields of the Ref and Refs templates (default: #R{address}). The replacement field address is the address of the referrer formatted as a decimal or hexadecimal number in accordance with the Base and Case configuration parameters.

Refs
    Template used to format the comment for a routine with two or more referrers (default: Used by the routines at {refs} and {ref}.).

Semicolons
    Block types (b, c, g, i, s, t, u, w) in which comment semicolons are written for instructions that have no comment (default: c).

Text
    Show ASCII text in the comment fields (1), or don't (0, the default).

Timings
    Show instruction timings in the comment fields (1), or don't (0, the default).

Title-b
    Template used to format the title for an untitled 'b' block (default: Data block at {address}).

Title-c
    Template used to format the title for an untitled 'c' block (default: Routine at {address}).

Title-g
    Template used to format the title for an untitled 'g' block (default: Game status buffer entry at {address}).

Title-i
    Template used to format the title for an untitled 'i' block (default: Ignored).

Title-s
    Template used to format the title for an untitled 's' block (default: Unused).

Title-t
    Template used to format the title for an untitled 't' block (default: Message at {address}).

Title-u
    Template used to format the title for an untitled 'u' block (default: Unused).

Title-w
    Template used to format the title for an untitled 'w' block (default: Data block at {address}).

Wrap
    Disassemble an instruction that wraps around the 64K boundary (1), or don't (0, the default).

    The Opcodes list is empty by default, but may contain any of the following values:
    ED63 - LD (nn),HL (4-byte variant)
    ED6B - LD HL,(nn) (4-byte variant)
    ED70 - IN F,(C)
    ED71 - OUT (C),0
    IM - IM 0/1/2 variants (ED followed by 4E/66/6E/76/7E)
    NEG - NEG variants (ED followed by 4C/54/5C/64/6C/74/7C)
    RETN - RETN variants (ED followed by 55/5D/65/6D/75/7D)
    XYCB - undocumented instructions with DDCB or FDCB opcode prefixes
    ALL - all of the above

    Configuration parameters must appear in a [sna2skool] section. For example, to make sna2skool.py generate hexadecimal skool files with a line width of 120 characters by default (without having to use the -H and -w options on the command line), add the following section to skoolkit.ini:

        [sna2skool]
        Base=16
        LineWidth=120

    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.  Convert game.z80 into a skool file named game.skool:
    sna2skool.py game.z80 > game.skool

2.  Convert game.sna into a skool file, beginning the disassembly at 24576:
    sna2skool.py -s 24576 game.sna > game.skool

3.  Convert game.z80 into a skool file, using the control file blocks.ctl to identify code and data blocks:
    sna2skool.py -c blocks.ctl game.z80 > game.skool

AUTHOR
Richard Dymond

COPYRIGHT
2026, Richard Dymond