Skool file templates

A skool file template defines the basic structure of a skool file, but, unlike a skool file, contains directives on how to disassemble a program into Z80 instructions instead of the Z80 instructions themselves. The directives are similar to those that may appear in a control file.

The skool2sft.py command can generate a skool file template from an existing skool file; the sna2skool.py command can then generate a skool file from the template and an appropriate snapshot.

Skool file template format

A skool file template has the same layout as a skool file, except that the lines in ‘b’, ‘c’, ‘g’, ‘s’, ‘t’, ‘u’ and ‘w’ blocks that correspond to Z80 instructions look like this:

xX#####,n[;c[ comment]]

where:

  • x is one of the characters * bcgstuw (with the same meaning as in a skool file)
  • X is one of the characters BCSTW (with the same meaning as in a control file)
  • ##### is the address at which to start disassembling
  • n is the number of bytes to disassemble
  • c is the index of the column in which the comment marker (;) appears in the line (if it does appear)
  • comment, if present, is the instruction-level comment for the line on which the instruction occurs

If a comment for a single instruction spans two or more lines in a skool file, as in:

c24296 CALL 57935    ; This comment is too long to fit on a single line, so
                     ; we use two lines

then it will be rendered in the skool file template thus:

cC24296,3;21 This comment is too long to fit on a single line, so
 ;21 we use two lines

Sub-block syntax

The syntax for specifying B, S, T and W sub-blocks is analogous to the syntax used in control files. A brief summary of the syntax is given here.

Sequences of DEFB statements can be declared on a single line thus:

bB40960,8*2,5

which is equivalent to:

bB40960,8
 B40968,8
 B40976,5

The same syntax also applies for declaring sequences of DEFM, DEFS and DEFW statements.

DEFB and DEFM statements may contain both strings and bytes; for example:

b30000 DEFB 1,2,3,4,"Hello!"
 30010 DEFM 5,6
 30012 DEFM "B",7,8

Such statements are preserved in a skool file template thus:

bB30000,4:T6
 T30010,B2,1:B2

DEFB, DEFM, DEFS and DEFW statements may contain numeric values in various bases; for example:

b40000 DEFB %10101010,23,43,$5F
 40004 DEFB 56
 40005 DEFB %11110000
 40006 DEFB $2B,$80

These statements may be preserved in a skool file template thus:

bB40000,b1:d2:h1,d1,b1,h2

Skool file template comments

Any line that begins with a hash character (#) is ignored by sna2skool.py, and will not show up in the skool file.

Data definition entries

In the same way as skool2html.py uses data definition entries (‘d’ blocks) in a skool file to insert data into the memory snapshot it constructs, sna2skool.py uses data definition entries in a skool file template to replace data in the snapshot given on the command line. This feature can be used to make sure that a ‘volatile’ part of memory is set to a specific value before being disassembled.

For example, if address 32400 holds the number of lives, you could make sure that its contents are set to 0 so that it will disassemble to DEFB 0 (whatever the contents may be in the snapshot itself) thus:

d32400 DEFB 0

; Number of lives
bB32400,1

Note that in order to take effect, a ‘d’ block must appear before the block that it overrides.

Revision history

Version Changes
3.7 Added support for binary numbers; added support for specifying the base of numeric values in DEFB, DEFM, DEFS and DEFW statements; added the s and S directives and support for DEFS statements with non-zero byte values
3.1.4 Added support for DEFB and DEFM statements that contain both strings and bytes
2.4 New