bin2tap.py — SkoolKit 10.1 documentation

# bin2tap.py

## SYNOPSIS

`bin2tap.py` [options] FILE [OUTFILE]

## DESCRIPTION

`bin2tap.py` converts a binary (raw memory) file or a SNA, SZX or Z80 snapshot into a PZX or TAP file. FILE may be a regular file, or ‘-’ to read a binary file from standard input. If OUTFILE is not given, a TAP file is created.

## OPTIONS

–7ffd N

  Add 128K RAM banks to the tape file and write N to port 0x7ffd after they’ve loaded.

–banks N[,N…]

  Add only these 128K RAM banks to the tape file (default: 0,1,3,4,6,7).

-b, –begin BEGIN

  Begin conversion at this address. The default begin address is the origin address (ORG) for a binary file, or 16384 for a snapshot. BEGIN must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

-c, –clear N

  Use a `CLEAR N` command in the BASIC loader, and leave the stack pointer alone. This option overrides the `--stack` option. N must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

-e, –end END

  End conversion at this address. END must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

–loader ADDR

  Place the 128K RAM bank loader at this address (default: CLEAR address + 1). ADDR must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

-o, –org ORG

  Set the origin address for a binary file. The default origin address is 65536 minus the length of FILE. ORG must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

-p, –stack STACK

  Set the stack pointer. The default value is BEGIN. STACK must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

-s, –start START

  Set the start address to JP to. The default start address is BEGIN. START must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

-S, –screen FILE

  Add a loading screen to the tape file. FILE may be a snapshot or a 6912-byte SCR file.

`-V, --version`

  Show the SkoolKit version number and exit.

## STACK POINTER

The ROM tape loading routine at 1366 (0x0556) and the load routine used by `bin2tap.py` together require 14 bytes for stack operations, and so STACK must be at least 16384+14=16398 (0x400E). This means that if ORG is less than 16398, you should use the `--stack` option to set the stack pointer to something appropriate. If the data block overlaps any of the last four bytes of the stack, `bin2tap.py` will replace those bytes with the values required by the tape loading routine for correct operation upon returning. Stack operations will overwrite the bytes in the address range STACK-14 to STACK-1 inclusive, so those addresses should not be used to store essential code or data.

If the input file contains a program that returns to BASIC, you should use the `--clear` option to add a CLEAR command to the BASIC loader. This option leaves the stack pointer alone, enabling the program to return to BASIC without crashing. The lowest usable address with the `--clear` option on a bare 48K Spectrum is 23952 (0x5D90).

## 128K TAPES

To create a tape file that loads a 128K game, use the `--7ffd`, `--begin` and `--clear` options along with a 128K snapshot or a 128K binary file as input, where:

- `--7ffd` specifies the value to write to port 0x7FFD after all the RAM banks have loaded and before starting the game

- `--begin` specifies the start address of the code/data below 49152 (0xC000) to include on the tape

- `--clear` specifies the address of the CLEAR command in the BASIC loader

By default, the 128K RAM bank loader (which is 39-45 bytes long, depending on the number of RAM banks to load) is placed one above the CLEAR address. Use the `--loader` option to place it at an alternative address. The lowest usable address with the `--clear` option on a bare 128K Spectrum is 23977 (0x5DA9) if a loading screen is used, or 23957 (0x5D95) otherwise.

By default, 128K RAM banks 0, 1, 3, 4, 6 and 7 are added to the tape file. If one or more of these RAM banks are not required, use the `--banks` option to specify a smaller set of RAM banks to add. If none of these RAM banks are required, use `,` (a single comma) as the argument to the `--banks` option. The contents of RAM banks 5 and 2 - from the `--begin` address and up to but not including the `--end` address (if given) - are included in the main code block on the tape.

## EXAMPLES

1. Convert `game.bin` into a TAP file named `game.tap`:

   `bin2tap.py game.bin`

2. Convert `game.bin` into a PZX file that starts execution at 32768 when loaded:

   `bin2tap.py -s 32768 game.bin game.pzx`