sna2skool.py — SkoolKit 10.1 documentation

# sna2skool.py

## 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`