mirror of
https://github.com/spicyjpeg/573in1.git
synced 2025-02-02 12:37:19 +01:00
86 lines
3.9 KiB
Markdown
86 lines
3.9 KiB
Markdown
|
|
# 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.
|