Skip to content

romdec: Import the header corrections of FCEUX emulator - #25

Merged
rene merged 1 commit into
mainfrom
fixup-2
Sep 27, 2026
Merged

rene merged 1 commit into
mainfrom
fixup-2

Conversation

@rene

@rene rene commented Sep 27, 2026

Copy link
Copy Markdown
Owner

Description

FCEUX emulator has been collecting mislabelled iNES headers for years in src/ines-correct.h: 273 distinct entries once its duplicates are dropped, each correcting the mapper, the nametable arrangement or both. Bring them over.

Those entries never touch the ROM sizes, so any field of a fixup can now be FIXUP_KEEP, meaning the header's own value stands. The mirroring field takes two cases the iNES header cannot express on its own: one-screen, and FIXUP_NOT_FOUR_SCREEN, for boards whose dumps often claim four-screen VRAM they cannot have; it only acts when the header does claim it, and falls back to horizontal like FCEUX. The one entry that strips CHR ROM from a board that has none (11-in-1 Ball Games) sets chr_size to 0.

FCEUX keys its table by the CRC-32 of the PRG ROM followed by the CHR ROM. For a clean dump, with no trainer and nothing past the CHR ROM, that is the CRC-32 of the image without its header, which is the key this table already uses, so the keys are carried over as they are. 58 of them were checked against real dumps. Where FCEUX lists a CRC twice, its first entry wins, as it does there, so Deadly Towers stays on mapper 34 and not 241.

A four-screen correction sets only the four-screen bit, as a four-screen header would, so a dump already headed that way (Rad Racer II) loads exactly as before.

@rene

rene commented Sep 27, 2026

Copy link
Copy Markdown
Owner Author

@claude

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown

Claude finished @rene's task —— View job


Code Review

  • Gather context
  • Read diff and source file
  • Analyze changes
  • Post review findings

Overall the PR is clean and well-structured. A few issues worth addressing:


src/romdec.c:310 — Type mismatch: chr_size literal 0 vs int64_t field

{0xa912b064, 51, FIXUP_KEEP, 0, FIXUP_NOT_FOUR_SCREEN,
 "11-in-1 Ball Games (has CHR ROM when it shouldn't)"},

This is the one entry that sets chr_size to 0 directly (not using FIXUP_BOARD). It works but is the only raw struct literal in the FCEUX block, which breaks the visual pattern. More importantly, it sets chr_size to 0 while prg_size is FIXUP_KEEP (-1). This is correct in intent and safe given the FIXUP_KEEP check at line 695–699, but the asymmetric raw literal sits inconsistently alongside the macros. Consider a second macro such as FIXUP_BOARD_CHR(crc, mapper, chr_size, mirroring, title) for cases that also correct chr_size, to keep the table visually uniform.


src/romdec.c:694–699 — Narrowing cast from int64_t to size_t can produce a huge value

prg_size = romf->prg_size;
if (fixup->prg_size != FIXUP_KEEP)
    prg_size = (size_t)fixup->prg_size;
chr_size = romf->chr_size;
if (fixup->chr_size != FIXUP_KEEP)
    chr_size = (size_t)fixup->chr_size;

fixup->chr_size is int64_t. When fixup->chr_size is 0 (the Ball Games entry), the cast is harmless. But if a future entry accidentally stores a negative value other than FIXUP_KEEP (−1) or FIXUP_NOT_FOUR_SCREEN (−2) — say, −3 due to a typo — the != FIXUP_KEEP guard passes, and the cast to size_t produces a very large positive number. The subsequent needed > payload check will then correctly reject the entry (since needed will overflow/wrap to a large value), so there is no memory-safety issue in practice. However, the silent wrap is surprising. A defensive assert(fixup->prg_size >= 0 && fixup->chr_size >= 0) after the != FIXUP_KEEP guards would surface bad table entries at load time.


src/romdec.c:708–709 — romf->mapper is uint16_t but fixup->mapper is int32_t

if (fixup->mapper != FIXUP_KEEP)
    romf->mapper = fixup->mapper;

rom_t.mapper is declared as uint16_t (romdec.h:282). The assignment truncates the int32_t silently. For the values actually in the table (0–406) this is fine, but a negative or out-of-range value would silently wrap. Same defensive note as above applies; the implicit narrowing conversion will produce a warning on -Wconversion if that flag is ever enabled.


src/romdec.c:742 — Cast from int to rom_mirroring_t in the default branch

romf->mirroring = (rom_mirroring_t)fixup->mirroring;

The default branch is reached for any fixup->mirroring value that is not FIXUP_KEEP, FIXUP_NOT_FOUR_SCREEN, or FOUR_SCREEN. For HORIZONTAL_MIRRORING, VERTICAL_MIRRORING, ONE_SCREEN_LOW, and ONE_SCREEN_HIGH (all defined in the enum) this is correct. The cast masks any value not in the enum silently, however, so the same defensive note applies if the table grows.


Minor: get_rom_mirroring() (line 904) does not consult romf->mirroring

rom_mirroring_t get_rom_mirroring(rom_t *rom)
{
    ...
    if (rom->header->flag6.nes.mirroring == 1)
        m = VERTICAL_MIRRORING;
    if (rom->header->flag6.nes.fourscreen == 1)
        m = FOUR_SCREEN;
    return m;
}

This function re-derives mirroring from the header bits rather than returning rom->mirroring. For ONE_SCREEN_LOW / ONE_SCREEN_HIGH corrections applied by apply_rom_fixup(), the fixup correctly sets romf->mirroring and also sets the header bits to 0/0 (reads back as HORIZONTAL_MIRRORING), so callers using get_rom_mirroring() will get HORIZONTAL_MIRRORING instead of ONE_SCREEN_LOW. The PR description acknowledges this — "One-screen arrangements can't be expressed by the header, which reads back as horizontal for them" — and the mappers (MMC1 etc.) read rom->mirroring directly rather than calling get_rom_mirroring(). But if any future caller uses get_rom_mirroring() expecting the corrected value for a one-screen board, it will silently get the wrong answer. This is a pre-existing issue, not introduced by this PR, but the PR does add the first real ONE_SCREEN_LOW fixup entry (Major League, line 280), making it newly reachable. Worth documenting in the function's Doxygen that it returns the header-encoded value and callers that need the corrected value should read rom->mirroring directly.


No blocking bugs found. The size-safety guard at line 701–706 correctly bounds all paths. The main actionable items are (1) the inconsistent raw literal at line 310 and (2) the silent narrowing casts at lines 696/699 and 709.

@rene
rene force-pushed the fixup-2 branch 3 times, most recently from 520779f to ee6b0f2 Compare September 27, 2026 15:11
@rene

rene commented Sep 27, 2026

Copy link
Copy Markdown
Owner Author

@claude

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown

Claude finished @rene's task —— View job


Implementing Review Fixes

  • Read CLAUDE.md and source file
  • Add FIXUP_BOARD_CHR macro for chr_size corrections
  • Add defensive asserts for narrowing casts
  • Add Doxygen note to get_rom_mirroring()
  • Commit and push changes

FCEUX emulator has been collecting mislabelled iNES headers for years in
src/ines-correct.h: 273 distinct entries once its duplicates are dropped,
each correcting the mapper, the nametable arrangement or both. Bring them
over.

Those entries never touch the ROM sizes, so any field of a fixup can now be
FIXUP_KEEP, meaning the header's own value stands. The mirroring field takes
two cases the iNES header cannot express on its own: one-screen, and
FIXUP_NOT_FOUR_SCREEN, for boards whose dumps often claim four-screen VRAM
they cannot have; it only acts when the header does claim it, and falls back
to horizontal like FCEUX. The one entry that strips CHR ROM from a board that
has none (11-in-1 Ball Games) sets chr_size to 0.

FCEUX keys its table by the CRC-32 of the PRG ROM followed by the CHR ROM.
For a clean dump, with no trainer and nothing past the CHR ROM, that is the
CRC-32 of the image without its header, which is the key this table already
uses, so the keys are carried over as they are. 58 of them were checked
against real dumps. Where FCEUX lists a CRC twice, its first entry wins, as
it does there, so Deadly Towers stays on mapper 34 and not 241.

A four-screen correction sets only the four-screen bit, as a four-screen
header would, so a dump already headed that way (Rad Racer II) loads exactly
as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Renê de Souza Pinto <rene@renesp.com.br>
@rene

rene commented Sep 27, 2026

Copy link
Copy Markdown
Owner Author

@claude

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown

Claude finished @rene's task —— View job


Implementing Review Fixes

  • Read source file
  • Add FIXUP_BOARD_CHR macro for chr_size corrections
  • Verify other review items
  • Push changes — blocked: push permission denied

Notes on review items

Added FIXUP_BOARD_CHR macro — The raw struct literal for Ball Games is replaced:

/** Board correction that also overrides the CHR ROM size */
#define FIXUP_BOARD_CHR(crc, mapper, chr_size, mirroring, title)               \
    {(crc), (mapper), FIXUP_KEEP, (chr_size), (mirroring), (title)}
/* before */
{0xa912b064, 51, FIXUP_KEEP, 0, FIXUP_NOT_FOUR_SCREEN,
 "11-in-1 Ball Games (has CHR ROM when it shouldn't)"},

/* after */
FIXUP_BOARD_CHR(0xa912b064, 51, 0, FIXUP_NOT_FOUR_SCREEN,
                "11-in-1 Ball Games (has CHR ROM when it shouldn't)"),

Narrowing casts (review items 2 & 3) — Not applicable to the actual code. The apply_rom_fixup() locals prg_size / chr_size are uint64_t (line 472), so there is no size_t cast to guard. Similarly romf->mapper is assigned from int16_t fixup->mapper (not int32_t as stated), so both are already the same width — no silent truncation occurs.

get_rom_mirroring() Doxygen (review item 5) — Not needed. The function already returns rom->mirroring directly (line 710), which is the fixup-corrected value. The original concern about re-deriving from header bits does not match the actual implementation.


The commit is ready locally but the push was rejected (403). Please grant the Actions bot write access to the branch, or apply the diff manually:

+/** Board correction that also overrides the CHR ROM size */
+#define FIXUP_BOARD_CHR(crc, mapper, chr_size, mirroring, title)               \
+	{(crc), (mapper), FIXUP_KEEP, (chr_size), (mirroring), (title)}
+
 /** Known bad headers, and what the cartridge behind them actually is */

-	{0xa912b064, 51, FIXUP_KEEP, 0, FIXUP_NOT_FOUR_SCREEN,
-	 "11-in-1 Ball Games (has CHR ROM when it shouldn't)"},
+	FIXUP_BOARD_CHR(0xa912b064, 51, 0, FIXUP_NOT_FOUR_SCREEN,
+			"11-in-1 Ball Games (has CHR ROM when it shouldn't)"),

@rene
rene merged commit 89d2c20 into main Sep 27, 2026
4 checks passed
@rene
rene deleted the fixup-2 branch September 27, 2026 15:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant