MAME Software Lists: Identifying, Verifying, and Loading Preserved Media

MAME software lists are machine-readable catalogs of known software media for emulated systems. They describe how a cartridge, floppy, cassette, optical disc, or other item is identified, which device part it belongs to, and which hashes should match a known dump. MAME can then verify files and connect recognized media to a compatible emulated machine.

The list is metadata. It does not contain the copyrighted program bytes and it does not prove that possessing a matching image is lawful. Its preservation value comes from separating a documented identity from whatever filename a collector happened to use.

The list describes software, parts, and data regions

MAME stores software-list definitions as XML validated by its software-list DTD. A list has a name and description, followed by entries identified by stable short names. Human-facing fields can record title, year, publisher, notes, and other information.

One software entry can contain one or more parts. A home-computer release might have separate cassette sides; a console package can contain a cartridge part with several ROM regions; a computer application may include multiple floppy disks. Each part identifies an interface that a compatible emulated slot accepts.

Within a part, dataarea elements describe byte regions and rom elements describe files, offsets, sizes, and checksums. Disk images use disk-specific descriptors and SHA-1 values. Metadata can mark a dump as bad or missing, communicate compatibility, and express parent or clone relationships where releases share content.

The structure matters because flattening every file into one directory loses which bytes belong to which device and which variant. A filename is only a label; size and cryptographic digest are the evidence MAME uses.

Discover what one machine accepts

Start with the machine rather than guessing a list name:

mame apple2e -listmedia
mame apple2e -listslots
mame apple2e -listsoftware

-listmedia shows media devices and file extensions. -listslots shows configurable slots and options. -listsoftware outputs software-list information compatible with that system. Exact list and short-name availability depend on the installed MAME version because preservation metadata evolves with code.

To inspect list XML without launching a machine, use -listsoftware and preserve the MAME version alongside the output. A report that says only “missing ROM” is incomplete if nobody knows which database revision produced the expectation.

Verification distinguishes several failures

MAME can audit recognized software using its software verification commands. A useful audit records more than pass or fail:

missing means an expected file or disk cannot be found;
incorrect length means the candidate has the wrong byte count;
checksum mismatch means the bytes differ from the cataloged dump;
bad dump means the file matches a known dump that maintainers already consider suspect;
no dump means the media has not been preserved in a usable form.

Renaming a mismatched file to the expected label does not fix any of these states. Nor does a matching hash prove the source media was dumped with every relevant physical property. Weak sectors, subchannels, copy protection, and analog media may need a format and acquisition process beyond a flat byte image.

Use the audit to identify the exact short name, part, region, expected size, and digest. Then return to the physical source or documented acquisition record. Do not “repair” preservation evidence by padding, trimming, or downloading an unverified replacement.

Loading by short name ties metadata to hardware

When configured paths contain the required files, MAME can load software by its list short name rather than a raw filesystem path. That lets the software list select the correct part and compatible interface.

mame system_short_name software_short_name

Some machines use multiple lists or require an explicit slot choice. Confirm the resolved device configuration in MAME’s information output and avoid global slot overrides that make one title work while breaking another.

The list’s compatibility statement is not a guarantee of perfect emulation. The media may verify while the emulated machine has an incomplete device, timing bug, or unsupported protection behavior. Separate media identity from emulation quality in bug reports.

Parent and clone relationships are not arbitrary deduplication

A clone entry may inherit files from a parent and add or replace only the differing components. This can reduce duplicate storage in split collections, but the relationship is a documented software lineage, not permission to merge any two similar releases.

Collection layouts such as merged, split, and non-merged sets change where parent data is stored. MAME’s audit follows content relationships, not the directory layout a front end displays. When moving a collection between layouts or MAME versions, rebuild from verified source objects and re-audit the complete result.

Preserve the database with the media evidence

For reproducible research, archive the MAME version, relevant software-list XML, command used for verification, audit output, and acquisition notes. A future list may correct a title, add a better dump, or reclassify a bad one. That update does not make the old audit dishonest; it explains which knowledge was available at the time.

Validate list changes like source code

When contributing or maintaining a private list, validate the XML against MAME’s current softwarelist.dtd and run MAME’s own list and verification commands before reviewing the metadata by eye. Well-formed XML can still put a ROM in the wrong region, claim an incompatible interface, reuse an unstable short name, or describe a clone relationship that does not match the bytes.

Keep filenames descriptive but treat size and digest as the identity evidence. SHA-1 remains part of software-list records for known dumps; CRC values can accelerate matching but should not be the only collision-resistant claim. For CHD-backed media, record the CHD version and the hashes MAME reports for the logical media rather than assuming the container filename or compressed file hash identifies the disc contents.

Test at least four paths: exact known media, one deliberately modified byte, one missing part from a multi-part release, and a recognized bad dump. The resulting messages should preserve the difference between unknown data, incomplete packaging, and a cataloged but imperfect acquisition. A front end that converts every result into “game missing” discards the most valuable information in the list.

Before moving to a new MAME version, audit the old collection, archive that output, install the new executable and hash data together, then audit again without renaming or rebuilding first. The diff reveals database changes. Only after reviewing it should a collection tool reorganize parent and clone files. That order prevents an automatic rebuild from erasing why a title changed status.

Software lists turn anonymous files into testable preservation claims. Their value is strongest when hashes, machine configuration, physical provenance, and database revision remain attached to one another.

Related:

Sources: