# File and data formats

## Security cartridge dump (.573 file)

Security cartridge dumps saved to IDE hard drives use a custom structured data
format, consisting of a raw dump of the cartridge's EEPROM preceded by a 44-byte
header. The data can be broken down as follows:

| Offset | Length  | Description                                               |
| -----: | ------: | :-------------------------------------------------------- |
|      0 |       2 | Magic number, must be `3d 57` (`0x573d` little endian)    |
|      2 |       1 | EEPROM chip type: 1 = X76F041, 2 = reserved, 3 = ZS01     |
|      3 |       1 | Dump flags, see below                                     |
|      4 |       8 | System identifier, zerofilled if none such                |
|     12 |       8 | Cartridge DS2401 identifier, zerofilled if none such      |
|     20 |       8 | Cartridge ZS01 identifier, zerofilled if none such        |
|     28 |       8 | Key used to unlock the cartridge, zerofilled if none such |
|     36 |       8 | EEPROM configuration registers, zerofilled if none such   |
|     44 | 112-512 | EEPROM contents (512 bytes for X76F041, 112 for ZS01)     |

The dump flags field is a single-byte bitfield containing the following flags:

| Bit | Description                                                        |
| --: | :----------------------------------------------------------------- |
|   0 | System has an identifier (i.e. a digital I/O board)                |
|   1 | Cartridge has a DS2401 chip                                        |
|   2 | EEPROM configuration registers present in the dump                 |
|   3 | System identifier present in the dump (requires bit 0)             |
|   4 | Cartridge DS2401 identifier present in the dump (requires bit 1)   |
|   5 | Cartridge ZS01 identifier present in the dump                      |
|   6 | Unprotected EEPROM data present in the dump                        |
|   7 | Protected EEPROM data and key present in the dump (requires bit 6) |

**NOTE**: bit 0 being set without bit 3 also being set means the tool was able
to detect the presence of a digital I/O board, but could not read its
identifier. The same goes for bits 1 and 4 respectively for cartridges with a
DS2401 chip.

## Security cartridge dump (QR code)

The format used by QR code dumps is essentially the same as `.573` files, but
with an additional layer of compression and a custom base-41 encoding on top of
the raw data. Scanning a QR code generated by the tool yields a string formatted
like this:

```
573::OGI8APY- [...] 8K2000::
```

In order to extract the dump data from such a string, a decoder must:

1. remove any framing (the `573::` prefix at the beginning of the string and the
   `::` suffix at the end);
2. decode the base-41 encoded string into an array of bytes (see below);
3. decompress the decoded binary data.

The base-41 encoding replaces each group of 2 bytes in the compressed data with
a group of 3 characters out of a custom 41-character set (the data is padded to
an even number of bytes in order for this to work). It can be undone using the
following pseudocode:

```py
CHARSET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ+-./:"

while not isEndOfData(input):
    a = findCharacterInString(CHARSET, readByte(input))
    b = findCharacterInString(CHARSET, readByte(input))
    c = findCharacterInString(CHARSET, readByte(input))

    value = a + (b * 41) + (c * 1681)
    writeByte(output, value >> 8)
    writeByte(output, value & 0xff)
```

The contents of the dump can then obtained by running the decoded data through
zlib's `decompress()` function or a zlib-compatible decompressor.

## Flash, PCMCIA card, RTC and BIOS dumps

All dumps of the internal flash, PCMCIA flash cards, RTC RAM and BIOS ROM are
stored in raw format without any framing or headers other than the ones present
in the data itself. In RTC RAM dumps the last 8 bytes (mapped to the M48T58
chip's clock registers) are omitted, thus the resulting dump is 8184 bytes long
rather than 8192.