rom-weaverA ROM & Patch toolkit

References

This file collects patch/container/compression references used by rom-weaver.

It is intentionally a living document. Some patch families do not have stable formal specs; in those cases, canonical behavior is documented through widely used implementations.

Patch format specifications

Patch reference implementations

Upstream and external

In-repository (rom-weaver) implementations

Container and compression specifications

Quick mapping for rom-weaver patch families

rom-weaver format Primary reference(s)
IPS, IPS32, EBP IPS spec, Flips IPS delta creator, RomPatcher.js IPS implementation
BPS byuu BPS spec, Flips/MultiPatch, RomPatcher.js BPS implementation
UPS RomPatcher.js UPS implementation
VCDIFF, xdelta RFC 3284, xdelta3, open-vcdiff, RomPatcher.js VCDIFF implementation
GDIFF rom-weaver handler implementation (no single canonical spec linked yet)
APS, APSGBA RomPatcher.js APS/APSGBA implementations
RUP RomPatcher.js RUP implementation
PPF RomPatcher.js PPF implementation, MultiPatch/ApplyPPF
PAT / FFP rom-weaver handler implementation (public spec is scarce)
BDF/BSDIFF40 BSDIFF paper, RomPatcher.js BDF implementation
BSP rom-weaver BSP implementation
MOD / PMSR RomPatcher.js PMSR implementation
DLDI Chishm DLDI page, rom-weaver DLDI implementation
DPS rom-weaver DPS implementation
SOLID rom-weaver SOLID implementation
DCP (Dreamcast) UniversalDreamcastPatcher (format oracle), DiscUtilsGD/buildgdi (GD-ROM layout), ECMA-130 (EDC/ECC), RFC 3284 (per-file deltas)

BPS comparison: MultiPatch and Flips

Comparison target: MultiPatch b047dd325f5d37fd3cc920433080e27af779cf47, whose flips submodule is Alcaro/Flips 5a3d2012b8ea53ae777c24b8ac4edb9a6bdb9761. MultiPatch's BPS adapter calls Flips ApplyPatch, CreatePatch(... ty_bps_linear), and CreatePatch(... ty_bps).

Area MultiPatch / Flips rom-weaver
Format grammar Uses the standard BPS1 header, source/target sizes, metadata length, four action kinds (SourceRead, TargetRead, SourceCopy, TargetCopy), and CRC32 footer. Parses and writes the same BPS grammar in crates/rom-weaver-patches/src/bps.rs.
Apply execution Flips reads the input patch and ROM into memory, applies to an output buffer, then MultiPatch writes the result. Uses an in-memory fast path for small files, a streaming sequential path for large files, and a parallel source/literal write path when a patch has no TargetCopy. TargetCopy stays sequential because it depends on previously produced output.
Checksum policy Flips validates patch/input/output CRCs, but MultiPatch passes verifyinput = NO; a wrong-input BPS can still produce an output with a warning. Defaults to strict patch, input, and output CRC validation. The shared checksum-validation override can skip CRC checks, but input and output sizes are still enforced.
Metadata / manifests Flips can carry BPS metadata and its app wrapper has manifest plumbing. Reads and skips metadata during parse/apply, reports sizes/checksums/action count, and currently creates zero-length metadata.
Patch creation modes MultiPatch exposes both Flips linear BPS and delta BPS. Flips delta creation uses suffix sorting over target/source data, target-window growth near the current output offset, and cost thresholds before emitting copy actions. Exposes one copy-aware BPS create path. It mirrors the Flips target-window growth and copy-cost threshold shapes, emits source reads/copies, target reads/copies, and repeated-byte TargetCopy, but does not expose a separate linear mode.
Header handling Flips has legacy SMC/SFC 512-byte header removal unless exact handling is requested. MultiPatch inherits that behavior through Flips. Treats input and output files as exact byte streams; no implicit SMC/SFC header removal.
Limits Flips is bounded by host size_t/off_t and allocation success; delta creation can use more memory for reverse indexes in some modes. BPS create is intentionally in-memory and copy-aware only under the repo memory limits, including the current suffix-index budget and 32-bit suffix-array range.

Use MultiPatch/Flips as a behavioral oracle for applying BPS patches and for creation heuristics, not as a byte-for-byte creation oracle. Different valid creators can emit different action streams for the same source/target pair.

PPF comparison: MultiPatch and ApplyPPF

Comparison target: MultiPatch master, whose PPF path wraps Icarus/Paradox ApplyPPF3.c and MakePPF3.c.

Area MultiPatch / ApplyPPF rom-weaver
Apply mode GUI apply calls applyPPF, which always uses APPLY mode. PPF3 undo data is skipped unless the separate command-line undo mode is used. Normal apply always writes forward patch bytes. PPF3 undo data is parsed and reported, but not auto-applied.
Validation PPF2 validates original size and the block at 0x9320; PPF3 validates 0x9320 for BIN and 0x80A0 for GI when blockcheck is enabled. Uses the same validation offsets under strict checksum validation; the shared ignore mode can skip blockcheck bytes.
File IDs Supports PPF2/PPF3 file_id.diz trailers when the footer magic/length marker is present. Skips PPF2 and PPF3 trailers during file parsing, including the 2-byte PPF3 trailer and padded 4-byte variant.
Create Creates PPF3 with BIN image type, blockcheck enabled by default, no undo by default, and optional CLI switches for undo, validation, image type, description, and file ID. Creates PPF3 forward patches with BIN-style blockcheck when the source is large enough; no explicit undo/file-id/image-type options yet.

Notes

  • If you add a new patch format, append at least one spec link (if available) and one implementation link.
  • For formats without a reliable formal spec, capture behavior with cross-implementation tests and cite those implementation sources here.