RCD v1 — ROM Creation Data Format

1. Overview

RCD is a plain UTF-8 text format describing how to reconstruct a ROM image from one or more source disk images (for Illusion City Turbo-R, 8 disks). It is human-readable, diff-friendly, and designed for deterministic rebuilds verified by SHA-256 hashes.

• Deterministic: final ROM SHA-256 optionally embedded & verified.
• Compact: large regions encoded via COPY and RLE.
• Extensible: future records can be added under new versions.

2. File layout

3. Record types

COPY

Copy bytes from a disk into the ROM.

COPY rom_off=0x000000 d=3 disk_off=0x001200 len=0x000080

• rom_off: ROM destination offset.
• d: disk id (1–8).
• disk_off: source disk offset.
• len: number of bytes to copy (must be > 0).

LITERAL

Insert explicit bytes (hex) into the ROM.

LITERAL rom_off=0x010000 data=4B4F4E414D49

• rom_off: ROM destination offset.
• data: even-length hex string (0..N bytes).

RLE

Fill a region with a repeated single byte (ideal for 0xFF/0x00 tails).

RLE rom_off=0x7F0000 byte=0xFF len=0x010000

• rom_off: ROM destination offset.
• byte: 0..255 (hex or decimal).
• len: number of bytes to write (> 0).

4. EBNF grammar

file            = wsp* "RCDv1" wsp* eol
                  ( wsp* rom_sha256 eol )?
                  ( wsp* disk_sha256 eol )*
                  ( wsp* eol )*
                  ( record_line )* ;

rom_sha256      = "ROM_SHA256" wsp+ hex64 ;
disk_sha256     = "DISK_SHA256" wsp+ disk_id wsp+ hex64 ;

record_line     = wsp* record wsp* eol ;
record          = copy_record | literal_record | rle_record ;

copy_record     = "COPY"    wsp+ kv_pair ( wsp+ kv_pair )* ;
literal_record  = "LITERAL" wsp+ kv_pair ( wsp+ kv_pair )* ;
rle_record      = "RLE"     wsp+ kv_pair ( wsp+ kv_pair )* ;

kv_pair         = key "=" value ;
key             = ident ;
value           = hexnum | decnum | hexbytes | hexbyte ;

(* COPY:    rom_off=<hex/dec> d=<dec> disk_off=<hex/dec> len=<hex/dec> *)
(* LITERAL: rom_off=<hex/dec> data=<HEXBYTES> *)
(* RLE:     rom_off=<hex/dec> byte=<hex/dec 0..255> len=<hex/dec> *)

ident           = alpha ( alpha | digit | "_" )* ;
disk_id         = decnum ;
hex64           = hexdig{64} ;
hexbytes        = hexdig hexdig ( hexdig hexdig )* ;
hexbyte         = hexnum ;  (* semantic range 0..255 *)
hexnum          = "0x" hexdig+ ;
decnum          = digit+ ;

alpha           = "A".."Z" | "a".."z" ;
digit           = "0".."9" ;
hexdig          = digit | "A".."F" | "a".."f" ;

wsp             = " " | "\t" ;
eol             = [# to end of line is a comment] newline ;
newline         = "\r\n" | "\n" | "\r" ;

Note: Comments start with # and run to end of line. Parsers should ignore unknown key=value pairs to ease forward compatibility (unless a future version says otherwise).

5. Semantics & constraints

• Header — RCDv1 must be first. ROM_SHA256 recommended. Zero or more DISK_SHA256 lines (disk ids 1..8).
• Application order — Apply records in file order; later bytes overwrite earlier ones.
• ROM size — Allocate to max end offset across all records; unwritten gaps initialize to 0x00 (implementation-defined but consistent).
• Ranges — All offsets/lengths are non-negative; d in 1..8; byte in 0..255; len > 0 (for COPY/RLE).
• Source bounds — COPY source ranges must lie within the referenced disk.
• Numbers — Accept decimal (123) or hex (0x7B).

6. Example

RCDv1
ROM_SHA256 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
DISK_SHA256 1 1111111111111111111111111111111111111111111111111111111111111111
DISK_SHA256 2 2222222222222222222222222222222222222222222222222222222222222222

COPY    rom_off=0x000000 d=1 disk_off=0x000000 len=0x010000
LITERAL rom_off=0x010000 data=4B4F4E414D49
RLE     rom_off=0x7F0000 byte=0xFF len=0x010000

7. Extensibility

• Versioning: bump the magic (e.g., RCDv2) for incompatible changes.
• New records: e.g., TRANSFORM with op=BYTESWAP16|XOR|DEINTL512 using either a disk source or inline data.
• Unknown keys: parsers should ignore them unless a spec version forbids it.

8. Validator checks (recommended)

• Magic present; hashes are 64 hex chars.
• Required keys per record type; no duplicate keys (or define “last wins” policy).
• Numeric ranges valid; COPY source fits within disk size.
• No impossible size (e.g., overflow of output buffer).
• Optional: warn on overlapping records (not an error if intentional).

© RCD v1. This document describes the format used by rcd_make.py and rcd_apply.py (RLE-aware). It is suitable for reimplementation in other languages and build tools.