rustynes_mappers/

m001_mmc1.rs

//! MMC1 (iNES mapper 1) implementation.
//!
//! See `docs/mappers.md` §Mapper coverage matrix and §MMC1; see
//! `ref-docs/research-report.md` §MMC1 for the source material.
//!
//! MMC1 is a serial mapper: writes to `$8000-$FFFF` are accumulated in a 5-bit
//! shift register over five consecutive CPU writes. The fifth write commits
//! the assembled value to one of four internal registers selected by bits
//! 14-13 of the destination address (`$8000-$9FFF` -> control, `$A000-$BFFF`
//! -> CHR0, `$C000-$DFFF` -> CHR1, `$E000-$FFFF` -> PRG). A write whose data
//! has bit 7 set resets the shift register and ORs the control register
//! with `$0C` (forcing PRG mode 3 = "fix last bank @ $C000").
//!
//! Consecutive-write bug: on real hardware the serial port ignores the DATA
//! bit of a write that lands on the CPU cycle immediately after another
//! serial-port write, whether that earlier write was accepted or itself
//! ignored (nesdev: it "ignores every write after the first"). A write with
//! bit 7 set is never ignored: the reset takes effect on any cycle. A
//! read-modify-write instruction's two back-to-back writes are the case that
//! matters: Bill & Ted's Excellent Adventure relies on the second data write
//! being dropped, and Shinsenden on a reset in that second write landing. We
//! track the cycle counter via [`Mapper::notify_cpu_cycle`]. Until v2.8.2 the
//! reset was filtered too (RTL audit R-3.5a, which found the `MiSTer` core right
//! and this implementation wrong).
//!
//! The default revision when the cartridge header lacks an NES 2.0 submapper
//! byte is **Sharp** (project policy: Star Trek: 25th Anniversary requires
//! the Sharp variant). NES 2.0 submapper 5 selects SEROM/SHROM/SH1ROM (no
//! PRG-RAM), but at the level of MMC1 register semantics those are
//! observationally equivalent.

use crate::cartridge::Mirroring;
use crate::mapper::{Mapper, MapperCaps, MapperError};
use alloc::{boxed::Box, vec::Vec};
use alloc::{format, vec};

const PRG_BANK_16K: usize = 0x4000;
const CHR_BANK_4K: usize = 0x1000;
const CHR_BANK_8K: usize = 0x2000;
const PRG_RAM_DEFAULT: usize = 0x2000;
const NAMETABLE_SIZE: usize = 0x0400;
const NAMETABLE_SIZE_U16: u16 = 0x0400;

/// v2 appends one byte: the latched PPU A12 of the last CHR fetch, which picks
/// the CHR register that drives SUROM / SOROM / SXROM's outer lines in 4 KiB
/// CHR mode. Since v2.9.8 (ADR 0042) a v1 blob is refused; it used to load
/// with that latch cleared.
const SAVE_STATE_VERSION: u8 = 2;
/// Size of one outer PRG-ROM half on SUROM / SXROM.
const PRG_OUTER_256K: usize = 0x4_0000;
/// One PRG-RAM bank.
const PRG_RAM_BANK_8K: usize = 0x2000;

/// MMC1 mapper.
pub struct Mmc1 {
    prg_rom: Box<[u8]>,
    chr: Box<[u8]>,
    prg_ram: Box<[u8]>,
    /// Internal nametable VRAM (2 KiB) — owned by the console, but we keep it
    /// here for now to mirror the NROM stop-gap until the PPU integration in
    /// Sprint 2-1 moves CIRAM into the PPU.
    vram: Box<[u8]>,
    chr_is_ram: bool,

    // MMC1 internal registers (5 bits each).
    control: u8, // mirror, prg-mode, chr-mode
    chr0: u8,    // CHR bank 0 ($A000-$BFFF write target)
    chr1: u8,    // CHR bank 1 ($C000-$DFFF write target)
    prg: u8,     // PRG bank ($E000-$FFFF write target)

    // 5-write protocol shift register + count.
    shift: u8,
    shift_count: u8,

    // Cycle of the most recent serial-port write, accepted or ignored (for the
    // consecutive-write bug; since v2.8.2 an ignored write counts too, per
    // "ignores every write after the first"). `u64::MAX` means "no prior
    // write to inhibit on".
    last_write_cycle: u64,
    cpu_cycle: u64,

    /// The PPU A12 level, as the PPU last reported it through `notify_a12`.
    /// In 4 KiB CHR mode it selects which CHR register drives the outer PRG /
    /// PRG-RAM lines on SUROM / SOROM / SXROM (see [`Self::outer_reg`]).
    /// Latched from the A12 notification, not from `ppu_read`: a debugger
    /// peek of CHR (`Bus::debug_peek_ppu`) goes through `ppu_read` and must
    /// not change CPU-side banking (PR #550 review).
    chr_a12_high: bool,
}

impl Mmc1 {
    /// Construct a new MMC1 mapper.
    ///
    /// `prg_rom` must be a multiple of 16 KiB (typical sizes: 32 KiB up to
    /// 512 KiB for SXROM). CHR-RAM is selected when `chr_rom` is empty;
    /// otherwise CHR-ROM length must be a non-zero multiple of 4 KiB.
    /// `prg_ram_bytes` of 0 selects the default 8 KiB.
    ///
    /// # Errors
    ///
    /// Returns [`MapperError::Invalid`] when sizes don't match.
    pub fn new(
        prg_rom: Box<[u8]>,
        chr_rom: Box<[u8]>,
        initial_mirroring: Mirroring,
        prg_ram_bytes: usize,
    ) -> Result<Self, MapperError> {
        if prg_rom.is_empty() || !prg_rom.len().is_multiple_of(PRG_BANK_16K) {
            return Err(MapperError::Invalid(format!(
                "MMC1 PRG-ROM size {} is not a non-zero multiple of 16 KiB",
                prg_rom.len()
            )));
        }
        let chr_is_ram = chr_rom.is_empty();
        let chr: Box<[u8]> = if chr_is_ram {
            vec![0u8; CHR_BANK_8K].into_boxed_slice()
        } else if chr_rom.len().is_multiple_of(CHR_BANK_4K) {
            chr_rom
        } else {
            return Err(MapperError::Invalid(format!(
                "MMC1 CHR-ROM size {} is not a multiple of 4 KiB",
                chr_rom.len()
            )));
        };

        let prg_ram_size = if prg_ram_bytes == 0 {
            PRG_RAM_DEFAULT
        } else {
            prg_ram_bytes
        };

        // Initial control: PRG mode 3 (fix last bank at $C000-$FFFF), CHR
        // mode 0 (8 KiB), single-screen-A. Per MMC1 power-on per nesdev wiki:
        // "Common sense suggests $0C as a likely starting value because it
        // forces $C000-$FFFF to be the last 16 KiB of PRG and the
        // initial mirroring is undefined; software should set it itself."
        // We start with mirroring derived from the iNES header byte (rather
        // than letting the mapper pick), matching most test ROMs that don't
        // set the control register before issuing reads.
        let initial_control = match initial_mirroring {
            Mirroring::SingleScreenA => 0x0C,
            Mirroring::SingleScreenB => 0x0D,
            Mirroring::Horizontal => 0x0F,
            // Vertical / FourScreen / MapperControlled: default to vertical
            // layout (a sensible neutral pick for headers that don't strictly
            // belong to MMC1 like four-screen).
            _ => 0x0E,
        };

        Ok(Self {
            prg_rom,
            chr,
            prg_ram: vec![0u8; prg_ram_size].into_boxed_slice(),
            vram: vec![0u8; 2 * NAMETABLE_SIZE].into_boxed_slice(),
            chr_is_ram,
            control: initial_control,
            chr0: 0,
            chr1: 0,
            prg: 0,
            shift: 0x10, // bit 4 set marks "5 writes still needed"
            shift_count: 0,
            last_write_cycle: u64::MAX,
            cpu_cycle: 0,
            chr_a12_high: false,
        })
    }

    /// The four internal registers, `(control, chr0, chr1, prg)`, for boards
    /// that embed an MMC1 and resolve banking themselves (mapper 105,
    /// NES-EVENT, v2.9.6). Read-only: the serial port stays the only writer.
    pub(crate) const fn registers(&self) -> (u8, u8, u8, u8) {
        (self.control, self.chr0, self.chr1, self.prg)
    }

    /// Bits collected by the serial port so far (0-4). A write that finds 4
    /// here and leaves 0 without the reset bit committed a register; that is
    /// how mapper 105 sees a write to `$A000` even when its value is unchanged.
    pub(crate) const fn shift_count(&self) -> u8 {
        self.shift_count
    }

    /// Map a PPU address in `$2000-$3EFF` to a 2 KiB-VRAM offset using the
    /// current mirroring mode (control bits 1-0).
    fn nametable_offset(&self, addr: u16) -> usize {
        let table = (((addr - 0x2000) / NAMETABLE_SIZE_U16) & 0x03) as u8;
        let local = (addr as usize) & (NAMETABLE_SIZE - 1);
        let physical = self.current_mirroring().physical_bank(table);
        physical * NAMETABLE_SIZE + local
    }

    /// Does the board repurpose the CHR register's upper bits?
    ///
    /// SOROM, SUROM and SXROM "address only 8 KiB of CHR-ROM/-RAM" and route
    /// the spare CHR lines to PRG A18 and PRG-RAM A13/A14
    /// (`nesdev_wiki/MMC1.xhtml`). A board with more CHR uses those bits as
    /// real CHR address lines, so nothing here applies to it.
    fn chr_lines_repurposed(&self) -> bool {
        self.chr.len() <= CHR_BANK_8K
    }

    /// The CHR register currently driving the outer lines: CHR bank 0 in 8 KiB
    /// CHR mode; in 4 KiB mode, whichever register the last CHR fetch selected.
    /// The wiki warns that mismatched registers make PRG "bankswitched ... as
    /// the PPU renders", which is exactly this behaviour.
    const fn outer_reg(&self) -> u8 {
        if self.control & 0x10 != 0 && self.chr_a12_high {
            self.chr1
        } else {
            self.chr0
        }
    }

    /// Base offset of the 256 KiB PRG-ROM half selected by `P` (bit 4), or 0.
    fn prg_outer_base(&self) -> usize {
        if self.chr_lines_repurposed() && self.prg_rom.len() > PRG_OUTER_256K {
            usize::from((self.outer_reg() >> 4) & 1) * PRG_OUTER_256K
        } else {
            0
        }
    }

    /// Byte offset of the selected 8 KiB PRG-RAM bank: SXROM (32 KiB) uses
    /// bits 3-2, SOROM (16 KiB) bit 3 only ("only implements the upper S").
    fn prg_ram_bank_base(&self) -> usize {
        if !self.chr_lines_repurposed() {
            return 0;
        }
        let reg = usize::from(self.outer_reg());
        match self.prg_ram.len() {
            0x8000 => ((reg >> 2) & 0x03) * PRG_RAM_BANK_8K,
            0x4000 => ((reg >> 3) & 0x01) * PRG_RAM_BANK_8K,
            _ => 0,
        }
    }

    /// Number of 16 KiB PRG banks the cartridge holds.
    const fn prg_bank_count(&self) -> usize {
        self.prg_rom.len() / PRG_BANK_16K
    }

    /// Resolve a CPU read at `$8000-$FFFF` into a PRG-ROM byte.
    fn map_prg(&self, addr: u16) -> u8 {
        let prg_mode = (self.control >> 2) & 0x03;
        // The PRG register's 4 low bits address 16 x 16 KiB = 256 KiB; its bit
        // 4 is the PRG-RAM disable, never a bank bit. SUROM / SXROM reach
        // 512 KiB through the CHR register's `P` bit instead, which picks the
        // 256 KiB half for the WHOLE window, fixed bank included (core audit
        // §5.4; this used to claim all five PRG bits and read only four).
        let outer = self.prg_outer_base();
        // Never zero: `outer` is non-zero only on a ROM larger than 256 KiB, and
        // the floor keeps mode 3's `bank_count - 1` and the modulo below safe
        // even if that invariant is ever broken.
        let bank_count = self
            .prg_bank_count()
            .saturating_sub(outer / PRG_BANK_16K)
            .clamp(1, PRG_OUTER_256K / PRG_BANK_16K);
        let prg_bank = self.prg & 0x0F;

        let (bank_low, bank_high): (usize, usize) = match prg_mode {
            0 | 1 => {
                // 32 KiB switch: bank-low = prg & 0xE, bank-high = bank-low + 1
                let bl = (prg_bank & 0x0E) as usize;
                (bl, bl + 1)
            }
            2 => {
                // First bank fixed to bank 0; second selectable
                (0, prg_bank as usize)
            }
            _ => {
                // Mode 3: first selectable; second fixed to last
                (prg_bank as usize, bank_count - 1)
            }
        };
        let bank_low = bank_low % bank_count;
        let bank_high = bank_high % bank_count;

        let offset_in_bank = (addr - 0x8000) as usize & (PRG_BANK_16K - 1);
        let bank = if (addr & 0x4000) == 0 {
            bank_low
        } else {
            bank_high
        };
        self.prg_rom[outer + bank * PRG_BANK_16K + offset_in_bank]
    }

    /// Resolve a PPU read at `$0000-$1FFF` into a CHR byte.
    fn map_chr(&self, addr: u16) -> usize {
        let chr_mode_8k = (self.control & 0x10) == 0;
        if chr_mode_8k {
            // 8 KiB CHR bank: CHR0 selects, low bit forced to 0.
            let bank_count = (self.chr.len() / CHR_BANK_8K).max(1);
            let bank = ((self.chr0 as usize) >> 1) % bank_count;
            bank * CHR_BANK_8K + (addr as usize & (CHR_BANK_8K - 1))
        } else {
            // 4 KiB banks
            let bank_count = (self.chr.len() / CHR_BANK_4K).max(1);
            let bank = if addr < 0x1000 {
                self.chr0 as usize
            } else {
                self.chr1 as usize
            };
            let bank = bank % bank_count;
            bank * CHR_BANK_4K + (addr as usize & (CHR_BANK_4K - 1))
        }
    }

    /// Is the `$6000-$7FFF` PRG-RAM window currently disabled?
    ///
    /// A2 (v2.2.3). MMC1 has **two** software write-protect layers and `RustyNES`
    /// previously modelled neither, reading and writing `prg_ram`
    /// unconditionally:
    ///
    /// * **`$E000` bit 4** — the PRG-RAM disable common to every MMC1 board.
    ///   Set = RAM deselected (`/CE` deasserted).
    /// * **SNROM's second layer** — on a board whose CHR is 8 KiB of RAM, the
    ///   CHR bank register doubles as a PRG-RAM enable: `$A000` bit 4 is wired
    ///   to the RAM's second enable. Only meaningful when `chr_is_ram`, which
    ///   is how SNROM is distinguished from the CHR-ROM boards (SJROM etc.)
    ///   that route those bits to real CHR banking instead.
    ///
    /// Holy Mapperel distinguishes the two: `M1_P128K_C32K` (SJROM, CHR-ROM)
    /// reported `1000` — the `$E000` layer alone — while `M1_P128K_CR8K`
    /// (SNROM, CHR-RAM) reported `5000`, both layers
    /// (`MAPTEST_WRAMEN2 $40 | MAPTEST_WRAMEN $10`).
    ///
    /// The second layer is SNROM's alone. On SUROM / SXROM (> 256 KiB PRG) the
    /// same CHR bit 4 is PRG A18, and on SOROM / SXROM (> 8 KiB PRG-RAM) the
    /// board wires the S bits instead, so neither is a RAM enable there.
    fn prg_ram_disabled(&self) -> bool {
        if self.prg & 0x10 != 0 {
            return true;
        }
        let snrom = self.chr_is_ram
            && self.prg_rom.len() <= PRG_OUTER_256K
            && self.prg_ram.len() <= PRG_RAM_BANK_8K;
        snrom && (self.outer_reg() & 0x10) != 0
    }

    /// Index into `prg_ram` for a `$6000-$7FFF` access, after banking.
    fn prg_ram_index(&self, addr: u16) -> usize {
        (self.prg_ram_bank_base() + usize::from(addr - 0x6000)) % self.prg_ram.len().max(1)
    }

    /// Apply a completed 5-bit write to the appropriate internal register.
    const fn commit(&mut self, addr: u16, value: u8) {
        match addr & 0xE000 {
            0x8000 => self.control = value,
            0xA000 => self.chr0 = value,
            0xC000 => self.chr1 = value,
            // 0xE000
            _ => self.prg = value,
        }
    }
}

impl Mapper for Mmc1 {
    fn sram(&self) -> &[u8] {
        &self.prg_ram
    }
    fn sram_mut(&mut self) -> &mut [u8] {
        &mut self.prg_ram
    }
    // v2.8.0 Phase 4 — MMC1 overrides ONLY notify_cpu_cycle (the
    // consecutive-write throttle); it has no IRQ and no audio.
    fn caps(&self) -> MapperCaps {
        MapperCaps {
            cpu_cycle_hook: true,
            audio: false,
            frame_event_hook: false,
            irq_source: false,
        }
    }

    /// A2: a disabled PRG-RAM window is not driven, so the databus floats.
    ///
    /// Same contract as the FME-7 fix: report the window unmapped and let the
    /// bus preserve its open-bus latch, rather than inventing a byte here.
    fn cpu_read_unmapped(&self, addr: u16) -> bool {
        if matches!(addr, 0x6000..=0x7FFF) {
            return self.prg_ram.is_empty() || self.prg_ram_disabled();
        }
        addr < 0x6000
    }

    fn cpu_read(&mut self, addr: u16) -> u8 {
        match addr {
            0x6000..=0x7FFF => {
                if self.prg_ram.is_empty() {
                    0
                } else {
                    self.prg_ram[self.prg_ram_index(addr)]
                }
            }
            0x8000..=0xFFFF => self.map_prg(addr),
            _ => 0,
        }
    }

    fn cpu_write(&mut self, addr: u16, value: u8) {
        match addr {
            0x6000..=0x7FFF => {
                // A2: a disabled window is write-protected (both layers).
                if self.prg_ram_disabled() {
                    return;
                }
                if !self.prg_ram.is_empty() {
                    let idx = self.prg_ram_index(addr);
                    self.prg_ram[idx] = value;
                }
            }
            0x8000..=0xFFFF => {
                // Consecutive-cycle writes (nesdev MMC1): the serial port
                // "ignores every write after the first", but "this restriction
                // only applies to the data being written on bit 0; the bit 7
                // reset is never ignored". So the filter is checked AFTER the
                // reset, and every serial-port write -- ignored ones included
                // -- counts as the last write. Until v2.8.2 the reset was
                // filtered too, which *Shinsenden* (a reset on an `RRA abs,X`'s
                // second write) needs not to be; the MiSTer RTL was right and
                // this was wrong (RTL audit R-3.5a, inverted).
                let consecutive = self.last_write_cycle != u64::MAX
                    && self.cpu_cycle == self.last_write_cycle.wrapping_add(1);
                self.last_write_cycle = self.cpu_cycle;

                if value & 0x80 != 0 {
                    // Reset: clear shift; OR control with $0C (force PRG mode 3).
                    self.shift = 0x10;
                    self.shift_count = 0;
                    self.control |= 0x0C;
                    return;
                }
                if consecutive {
                    return;
                }
                // Shift bit 0 of value into bit 4 of shift, sliding right.
                // After 5 writes, bit 0 of (original) shift is the LSB of
                // the latched value; equivalently: low 5 bits, LSB first.
                let new_lsb = value & 0x01;
                self.shift = (self.shift >> 1) | (new_lsb << 4);
                self.shift_count += 1;
                if self.shift_count == 5 {
                    let latched = self.shift & 0x1F;
                    self.commit(addr, latched);
                    self.shift = 0x10;
                    self.shift_count = 0;
                }
            }
            _ => {}
        }
    }

    fn chr_phys(&self, addr: u16) -> Option<u32> {
        if self.chr_is_ram {
            None
        } else {
            u32::try_from(self.map_chr(addr & 0x1FFF)).ok()
        }
    }

    // The only writer of `chr_a12_high`. The PPU reports every A12 transition
    // here (not gated on capabilities), including the ones its `$2007`
    // accesses make, which is the line the MMC1 actually watches.
    fn notify_a12(&mut self, level: bool) {
        self.chr_a12_high = level;
    }

    fn ppu_read(&mut self, addr: u16) -> u8 {
        let addr = addr & 0x3FFF;
        match addr {
            0x0000..=0x1FFF => {
                let off = self.map_chr(addr);
                self.chr[off]
            }
            0x2000..=0x3EFF => {
                let off = self.nametable_offset(addr);
                self.vram[off]
            }
            _ => 0,
        }
    }

    fn ppu_write(&mut self, addr: u16, value: u8) {
        let addr = addr & 0x3FFF;
        match addr {
            0x0000..=0x1FFF => {
                if self.chr_is_ram {
                    let off = self.map_chr(addr);
                    self.chr[off] = value;
                }
            }
            0x2000..=0x3EFF => {
                let off = self.nametable_offset(addr);
                self.vram[off] = value;
            }
            _ => {}
        }
    }

    fn notify_cpu_cycle(&mut self) {
        self.cpu_cycle = self.cpu_cycle.wrapping_add(1);
    }

    fn current_mirroring(&self) -> Mirroring {
        match self.control & 0x03 {
            0 => Mirroring::SingleScreenA,
            1 => Mirroring::SingleScreenB,
            2 => Mirroring::Vertical,
            _ => Mirroring::Horizontal,
        }
    }

    fn debug_info(&self) -> crate::mapper::MapperDebugInfo {
        let mut info = crate::mapper::MapperDebugInfo {
            mapper_id: 1,
            name: "MMC1".into(),
            mirroring: crate::mapper::mirroring_name(self.current_mirroring()),
            ..Default::default()
        };
        info.prg_banks
            .push(("PRG".into(), format!("{:#04x}", self.prg)));
        info.chr_banks
            .push(("CHR0".into(), format!("{:#04x}", self.chr0)));
        info.chr_banks
            .push(("CHR1".into(), format!("{:#04x}", self.chr1)));
        info.extra
            .push(("control".into(), format!("{:#04x}", self.control)));
        info.extra.push((
            "shift".into(),
            format!("{:#04x} (count {})", self.shift, self.shift_count),
        ));
        info
    }

    fn save_state(&self) -> Vec<u8> {
        // Tagged blob: [version, control, chr0, chr1, prg, shift, count,
        //   prg_ram..., vram..., chr_if_ram..., chr_a12_high (v2)]
        let mut out = Vec::with_capacity(
            8 + self.prg_ram.len()
                + self.vram.len()
                + if self.chr_is_ram { self.chr.len() } else { 0 },
        );
        out.push(SAVE_STATE_VERSION);
        out.push(self.control);
        out.push(self.chr0);
        out.push(self.chr1);
        out.push(self.prg);
        out.push(self.shift);
        out.push(self.shift_count);
        out.extend_from_slice(&self.prg_ram);
        out.extend_from_slice(&self.vram);
        if self.chr_is_ram {
            out.extend_from_slice(&self.chr);
        }
        out.push(u8::from(self.chr_a12_high));
        out
    }

    fn load_state(&mut self, data: &[u8]) -> Result<(), MapperError> {
        let need_chr = if self.chr_is_ram { self.chr.len() } else { 0 };
        let version = *data.first().ok_or(MapperError::WrongLength {
            expected: 1,
            got: 0,
        })?;
        if version != SAVE_STATE_VERSION {
            return Err(MapperError::UnsupportedVersion(version));
        }
        let expected = 7 + self.prg_ram.len() + self.vram.len() + need_chr + 1;
        if data.len() != expected {
            return Err(MapperError::WrongLength {
                expected,
                got: data.len(),
            });
        }
        // The serial port holds at most four bits between commits (the fifth
        // write commits and resets), in a 5-bit register. A restored count
        // above 4 would wrap or overflow at the next write (NC-12, v2.9.9).
        if data[6] > 4 || data[5] > 0x1F {
            return Err(MapperError::Invalid(format!(
                "MMC1 serial port out of range: shift {:#04x}, count {}",
                data[5], data[6]
            )));
        }
        self.control = data[1];
        self.chr0 = data[2];
        self.chr1 = data[3];
        self.prg = data[4];
        self.shift = data[5];
        self.shift_count = data[6];
        let mut cursor = 7;
        self.prg_ram
            .copy_from_slice(&data[cursor..cursor + self.prg_ram.len()]);
        cursor += self.prg_ram.len();
        self.vram
            .copy_from_slice(&data[cursor..cursor + self.vram.len()]);
        cursor += self.vram.len();
        if self.chr_is_ram {
            self.chr
                .copy_from_slice(&data[cursor..cursor + self.chr.len()]);
            cursor += self.chr.len();
        }
        self.chr_a12_high = data[cursor] != 0;
        Ok(())
    }
}

#[cfg(test)]
#[allow(clippy::cast_possible_truncation)]
mod tests {
    use super::*;

    fn synth_prg(banks: usize) -> Box<[u8]> {
        // Each bank starts with a marker byte equal to the bank index, then
        // address-low rolls. Lets us check which bank an address resolves to.
        let mut v = vec![0u8; banks * PRG_BANK_16K];
        for b in 0..banks {
            for o in 0..PRG_BANK_16K {
                v[b * PRG_BANK_16K + o] = if o == 0 { b as u8 } else { (o & 0xFF) as u8 };
            }
        }
        v.into_boxed_slice()
    }

    fn synth_chr(banks_4k: usize) -> Box<[u8]> {
        let mut v = vec![0u8; banks_4k * CHR_BANK_4K];
        for b in 0..banks_4k {
            for o in 0..CHR_BANK_4K {
                v[b * CHR_BANK_4K + o] = if o == 0 { b as u8 } else { (o ^ 0x55) as u8 };
            }
        }
        v.into_boxed_slice()
    }

    /// Issue the 5 bit-writes that latch `value` into the register bank
    /// selected by the high two address bits.
    fn write5(m: &mut Mmc1, addr: u16, value: u8) {
        for i in 0..5 {
            let bit = (value >> i) & 1;
            // Drive notify_cpu_cycle far enough between each write so the
            // consecutive-write bug never fires in tests.
            for _ in 0..3 {
                m.notify_cpu_cycle();
            }
            m.cpu_write(addr, bit);
        }
    }

    /// nesdev MMC1, "Consecutive-cycle writes": the serial port ignores a
    /// write on the cycle after another, but "this restriction only applies to
    /// the data being written on bit 0; the bit 7 reset is never ignored".
    /// *Shinsenden* sets bit 7 on a read-modify-write's SECOND write (`RRA
    /// abs,X`) "and will crash ... if this reset is ignored". Before v2.8.2 the
    /// oracle filtered the reset too; the `MiSTer` RTL never did (RTL audit
    /// R-3.5a had the two the wrong way round).
    #[test]
    fn a_reset_on_the_cycle_after_a_write_is_never_ignored() {
        let mut m = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        write5(&mut m, 0x8000, 0b0_1000); // PRG mode 2: $C000 switchable
        write5(&mut m, 0xE000, 1);
        assert_eq!(m.cpu_read(0xC000), 1, "mode 2 set up");
        for _ in 0..3 {
            m.notify_cpu_cycle();
        }
        m.cpu_write(0x8000, 0x7F); // RMW's first write: data, accepted
        m.notify_cpu_cycle();
        m.cpu_write(0x8000, 0x80); // the next cycle: the reset
        assert_eq!(
            m.cpu_read(0xC000),
            3,
            "the reset ORs $0C into Control, so the last bank is fixed at $C000"
        );
        // The shift register was cleared too: a fresh 5-write sequence latches.
        write5(&mut m, 0xE000, 2);
        assert_eq!(m.cpu_read(0x8000), 2);
    }

    /// The other half of the same rule, as *Bill & Ted's Excellent Adventure*
    /// needs it: `INC` on a `$FF` byte writes `$FF` (a reset) and then `$00`
    /// on the next cycle, and that `$00` data write must be ignored.
    #[test]
    fn a_data_write_on_the_cycle_after_a_reset_is_ignored() {
        let mut m = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        for _ in 0..3 {
            m.notify_cpu_cycle();
        }
        m.cpu_write(0x8000, 0xFF);
        m.notify_cpu_cycle();
        m.cpu_write(0x8000, 0x00); // ignored: would misalign the next sequence
        write5(&mut m, 0xE000, 2);
        assert_eq!(m.cpu_read(0x8000), 2, "the ignored write left no stray bit");
    }

    #[test]
    fn mmc1_default_is_prg_mode_3_last_bank_at_c000() {
        // Build a 4-bank PRG (64 KiB). Default control sets PRG mode 3:
        // bank 0 selectable @ $8000, last bank fixed @ $C000.
        let mut m = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        // $C000 should map to bank 3 (last); marker byte = 3.
        assert_eq!(m.cpu_read(0xC000), 3);
        // $8000 starts at bank 0 (prg register defaults to 0).
        assert_eq!(m.cpu_read(0x8000), 0);
    }

    #[test]
    fn mmc1_prg_register_switches_first_bank_in_mode_3() {
        let mut m = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        // Set PRG bank 2.
        write5(&mut m, 0xE000, 2);
        assert_eq!(m.cpu_read(0x8000), 2);
        assert_eq!(m.cpu_read(0xC000), 3); // last bank still fixed
    }

    #[test]
    fn mmc1_prg_mode_2_fixes_first_bank_at_8000() {
        let mut m = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        // Control: prg-mode = 2 (bits 3-2 = 10), chr-mode = 0, mirror = horiz (3).
        write5(&mut m, 0x8000, 0b0_1011);
        // PRG register selects bank for $C000. Set to 1.
        write5(&mut m, 0xE000, 1);
        assert_eq!(m.cpu_read(0x8000), 0); // fixed bank 0
        assert_eq!(m.cpu_read(0xC000), 1); // selectable
    }

    #[test]
    fn mmc1_prg_mode_0_or_1_switches_32k() {
        let mut m = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        // Control: prg-mode = 0 (bits 3-2 = 00), chr-mode = 0, mirror = horiz.
        write5(&mut m, 0x8000, 0b0_0011);
        // PRG register = 2 -> 32 KiB switch picks (bank 2, bank 3).
        write5(&mut m, 0xE000, 2);
        assert_eq!(m.cpu_read(0x8000), 2);
        assert_eq!(m.cpu_read(0xC000), 3);
    }

    #[test]
    fn mmc1_chr_mode_4k_switches_independent_banks() {
        let mut m = Mmc1::new(synth_prg(2), synth_chr(4), Mirroring::Vertical, 0).unwrap();
        // Control: chr-mode = 1 (bit 4 set), prg-mode = 3, mirror = horiz.
        write5(&mut m, 0x8000, 0b1_1111);
        // CHR0 = bank 1, CHR1 = bank 2.
        write5(&mut m, 0xA000, 1);
        write5(&mut m, 0xC000, 2);
        assert_eq!(m.ppu_read(0x0000), 1);
        assert_eq!(m.ppu_read(0x1000), 2);
    }

    #[test]
    fn mmc1_chr_mode_8k_uses_chr0_only() {
        let mut m = Mmc1::new(synth_prg(2), synth_chr(4), Mirroring::Vertical, 0).unwrap();
        // chr-mode = 0 (bit 4 clear), prg-mode = 3, mirror = horiz.
        write5(&mut m, 0x8000, 0b0_1111);
        // CHR0 = 2 -> 8 KiB bank starts at CHR4K-bank (2 >> 1) * 8 KiB = bank index 1.
        write5(&mut m, 0xA000, 2);
        assert_eq!(m.ppu_read(0x0000), 2); // 4K-bank index 2 -> first byte
        assert_eq!(m.ppu_read(0x1000), 3); // next 4K-bank
    }

    #[test]
    fn mmc1_reset_bit_forces_prg_mode_3() {
        let mut m = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        // Set prg-mode = 0 first.
        write5(&mut m, 0x8000, 0b0_0011);
        // Now write reset bit.
        m.cpu_write(0x8000, 0x80);
        // Control should have been ORed with $0C. With our prior control of
        // 0b0_0011 (= 0x03), after | 0x0C = 0x0F (mode 3, mirror horiz).
        // Last bank should be fixed at $C000.
        assert_eq!(m.cpu_read(0xC000), 3);
    }

    #[test]
    fn mmc1_consecutive_write_bug_drops_second_write() {
        let mut m = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        // Write bit 0 of shift. Then on the very next cycle, write bit 1 —
        // hardware drops it.
        m.notify_cpu_cycle();
        m.cpu_write(0xE000, 1); // accepted; shift = 0x10 -> 0x18 (bit 4 from new_lsb)
        m.notify_cpu_cycle();
        m.cpu_write(0xE000, 1); // dropped (cycle = last_write+1)
        // Continue with 4 more accepted writes.
        for _ in 0..4 {
            for _ in 0..3 {
                m.notify_cpu_cycle();
            }
            m.cpu_write(0xE000, 0);
        }
        // We accepted bits: 1, 0, 0, 0, 0 -> latched value = 0b00001 = 1.
        // PRG register = 1, mode 3 default, so $8000 -> bank 1.
        assert_eq!(m.cpu_read(0x8000), 1);
    }

    #[test]
    fn mmc1_mirroring_switches() {
        let mut m = Mmc1::new(synth_prg(2), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        // single-screen-A
        write5(&mut m, 0x8000, 0b0_1100);
        m.ppu_write(0x2000, 0xAA);
        assert_eq!(m.ppu_read(0x2400), 0xAA);
        assert_eq!(m.ppu_read(0x2800), 0xAA);
        assert_eq!(m.ppu_read(0x2C00), 0xAA);
        // single-screen-B
        write5(&mut m, 0x8000, 0b0_1101);
        m.ppu_write(0x2000, 0xBB); // writes physical bank 1
        // All four nametables now alias to bank 1.
        assert_eq!(m.ppu_read(0x2400), 0xBB);
        // vertical
        write5(&mut m, 0x8000, 0b0_1110);
        m.ppu_write(0x2000, 0x11); // bank 0
        m.ppu_write(0x2400, 0x22); // bank 1
        assert_eq!(m.ppu_read(0x2800), 0x11); // mirror of $2000
        assert_eq!(m.ppu_read(0x2C00), 0x22); // mirror of $2400
        // horizontal
        write5(&mut m, 0x8000, 0b0_1111);
        m.ppu_write(0x2000, 0x33); // bank 0
        m.ppu_write(0x2800, 0x44); // bank 1
        assert_eq!(m.ppu_read(0x2400), 0x33); // mirror of $2000
        assert_eq!(m.ppu_read(0x2C00), 0x44); // mirror of $2800
    }

    #[test]
    fn mmc1_save_state_round_trip() {
        let mut m = Mmc1::new(synth_prg(2), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        write5(&mut m, 0xE000, 1);
        m.cpu_write(0x6010, 0xCC);
        m.ppu_write(0x2000, 0xDD);
        let blob = m.save_state();
        let mut m2 = Mmc1::new(synth_prg(2), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        m2.load_state(&blob).unwrap();
        assert_eq!(m2.cpu_read(0x6010), 0xCC);
        assert_eq!(m2.ppu_read(0x2000), 0xDD);
        // PRG register should have round-tripped.
        assert_eq!(m2.cpu_read(0x8000), 1);
    }

    // ---------------------------------------------------------------
    // A2 (v2.2.3): the two PRG-RAM write-protect layers.
    // ---------------------------------------------------------------

    /// `$E000` bit 4 is the disable common to every MMC1 board. Write-protect
    /// AND read-float, on a CHR-ROM board where the SNROM layer is inert.
    #[test]
    fn mmc1_e000_bit4_write_protects_and_floats_prg_ram() {
        let mut m = Mmc1::new(synth_prg(8), synth_chr(8), Mirroring::Vertical, 0).unwrap();
        // Enabled by default: a write sticks and the window is mapped.
        m.cpu_write(0x6000, 0xA5);
        assert_eq!(m.cpu_read(0x6000), 0xA5);
        assert!(
            !m.cpu_read_unmapped(0x6000),
            "enabled window must be mapped"
        );

        // $E000 bit 4 set -> RAM deselected.
        write5(&mut m, 0xE000, 0x10);
        assert!(m.cpu_read_unmapped(0x6000), "disabled window must float");
        m.cpu_write(0x6000, 0x5A); // must be discarded

        // Re-enable: the pre-disable byte survives, proving the write above
        // was dropped rather than merely hidden by the float.
        write5(&mut m, 0xE000, 0x00);
        assert!(!m.cpu_read_unmapped(0x6000));
        assert_eq!(
            m.cpu_read(0x6000),
            0xA5,
            "write while disabled must not land"
        );
    }

    /// SNROM's second layer: on a CHR-**RAM** board the CHR register's bit 4 is
    /// wired to the RAM's other enable, so it disables PRG-RAM independently of
    /// `$E000`. This is what separated Holy Mapperel's `5000` (SNROM) from
    /// `1000` (SJROM).
    #[test]
    fn mmc1_snrom_chr_bit4_is_a_second_prg_ram_enable() {
        // Empty CHR => chr_is_ram, i.e. an SNROM-class board.
        let mut m = Mmc1::new(synth_prg(8), Box::new([]), Mirroring::Vertical, 0).unwrap();
        m.cpu_write(0x6000, 0x3C);
        assert_eq!(m.cpu_read(0x6000), 0x3C);

        // $E000 stays ENABLED; only the CHR-register layer disables.
        write5(&mut m, 0xA000, 0x10);
        assert!(
            m.cpu_read_unmapped(0x6000),
            "SNROM: $A000 bit 4 alone must disable PRG-RAM"
        );
        m.cpu_write(0x6000, 0x99); // discarded

        write5(&mut m, 0xA000, 0x00);
        assert_eq!(m.cpu_read(0x6000), 0x3C);
    }

    /// The same CHR-register bit must NOT touch PRG-RAM on a CHR-ROM board —
    /// there it is a real CHR bank select. This is the regression that would
    /// break every SJROM/SUROM title if the layer were applied unconditionally.
    #[test]
    fn mmc1_chr_rom_board_ignores_the_snrom_layer() {
        let mut m = Mmc1::new(synth_prg(8), synth_chr(8), Mirroring::Vertical, 0).unwrap();
        m.cpu_write(0x6000, 0x77);
        write5(&mut m, 0xA000, 0x10); // a CHR bank select, not a RAM enable
        assert!(
            !m.cpu_read_unmapped(0x6000),
            "CHR-ROM board: $A000 bit 4 is CHR banking, must not gate PRG-RAM"
        );
        assert_eq!(m.cpu_read(0x6000), 0x77);
    }

    // ---- v2.7.2: SUROM / SOROM / SXROM (core audit §5.4) -----------------
    //
    // Written from nesdev_wiki/MMC1.xhtml §"SOROM, SUROM and SXROM": on boards
    // that address only 8 KiB of CHR, the CHR bank register reads `PSSxC`.
    // P (bit 4) selects the 256 KiB PRG-ROM half and "applies to all the PRG
    // area, including the normally fixed bank"; SS (bits 3-2) select the 8 KiB
    // PRG-RAM bank (SOROM wires only the upper S, SXROM both: bit 3 = A14,
    // bit 2 = A13).

    #[test]
    fn surom_bit_4_selects_the_upper_256k_half_including_the_fixed_bank() {
        // 512 KiB PRG (32 x 16 KiB), CHR-RAM: SUROM.
        let mut m = Mmc1::new(synth_prg(32), Box::new([]), Mirroring::Vertical, 0).unwrap();
        // Power-on: PRG mode 3, outer half 0 -> the fixed bank is bank 15.
        assert_eq!(
            m.cpu_read(0xC000),
            15,
            "fixed bank = last of the LOWER half"
        );
        write5(&mut m, 0xA000, 0x10); // P = 1
        assert_eq!(m.cpu_read(0xC000), 31, "fixed bank follows the outer half");
        write5(&mut m, 0xE000, 2);
        assert_eq!(
            m.cpu_read(0x8000),
            18,
            "switchable bank 2 of the upper half"
        );
        write5(&mut m, 0xA000, 0x00);
        assert_eq!(m.cpu_read(0x8000), 2);
    }

    #[test]
    fn surom_bit_4_is_not_snrom_prg_ram_disable() {
        // On SNROM (<= 256 KiB, CHR-RAM) CHR bit 4 disables PRG-RAM; on SUROM
        // the same line is PRG A18, so selecting the upper half must leave the
        // RAM enabled.
        let mut m = Mmc1::new(synth_prg(32), Box::new([]), Mirroring::Vertical, 0).unwrap();
        write5(&mut m, 0xA000, 0x10);
        m.cpu_write(0x6000, 0x5A);
        assert_eq!(m.cpu_read(0x6000), 0x5A);
    }

    #[test]
    fn sxrom_bits_3_and_2_bank_32k_of_prg_ram() {
        let mut m = Mmc1::new(synth_prg(32), Box::new([]), Mirroring::Vertical, 0x8000).unwrap();
        for bank in 0..4u8 {
            write5(&mut m, 0xA000, bank << 2);
            m.cpu_write(0x6000, 0xA0 | bank);
        }
        for bank in 0..4u8 {
            write5(&mut m, 0xA000, bank << 2);
            assert_eq!(
                m.cpu_read(0x6000),
                0xA0 | bank,
                "bank {bank} kept its own byte"
            );
            assert_eq!(
                m.sram()[usize::from(bank) * 0x2000],
                0xA0 | bank,
                "sram() is the whole 32 KiB, in bank order"
            );
        }
    }

    #[test]
    fn sorom_banks_16k_of_prg_ram_with_bit_3_only() {
        // 256 KiB PRG, CHR-RAM, 16 KiB PRG-RAM: SOROM. Bit 2 is unconnected.
        let mut m = Mmc1::new(synth_prg(16), Box::new([]), Mirroring::Vertical, 0x4000).unwrap();
        write5(&mut m, 0xA000, 0x00);
        m.cpu_write(0x6000, 0x11);
        write5(&mut m, 0xA000, 0x08);
        m.cpu_write(0x6000, 0x22);
        write5(&mut m, 0xA000, 0x04); // bit 2 alone: still bank 0
        assert_eq!(m.cpu_read(0x6000), 0x11);
        write5(&mut m, 0xA000, 0x0C);
        assert_eq!(m.cpu_read(0x6000), 0x22);
    }

    #[test]
    fn in_4k_chr_mode_the_outer_bits_follow_the_register_the_ppu_last_used() {
        // "In 4KB CHR bank mode ... P and S bits in both CHR bank registers
        // must be set to the same values, or the PRG-ROM and/or RAM will be
        // bankswitched as the PPU renders" -- so the live register is the one
        // selected by the last CHR fetch's A12.
        let mut m = Mmc1::new(synth_prg(32), Box::new([]), Mirroring::Vertical, 0).unwrap();
        write5(&mut m, 0x8000, 0b1_1110); // CHR 4 KiB mode, PRG mode 3
        write5(&mut m, 0xA000, 0x00);
        write5(&mut m, 0xC000, 0x10);
        m.notify_a12(true); // PPU A12 high -> CHR bank 1 drives
        assert_eq!(m.cpu_read(0xC000), 31);
        m.notify_a12(false); // A12 low -> CHR bank 0
        assert_eq!(m.cpu_read(0xC000), 15);
    }

    #[test]
    fn a_chr_peek_does_not_change_cpu_banking() {
        // `Bus::debug_peek_ppu` documents a side-effect-free sample and routes
        // CHR through `ppu_read`/`ppu_write`. Only the PPU's A12 notification
        // may move the live register (PR #550 review).
        let mut m = Mmc1::new(synth_prg(32), Box::new([]), Mirroring::Vertical, 0).unwrap();
        write5(&mut m, 0x8000, 0b1_1110);
        write5(&mut m, 0xA000, 0x00);
        write5(&mut m, 0xC000, 0x10);
        let _ = m.ppu_read(0x1000);
        m.ppu_write(0x1000, 0);
        assert_eq!(m.cpu_read(0xC000), 15, "still CHR bank 0's half");
        assert!(!m.chr_a12_high);
    }

    #[test]
    fn chr_rom_boards_keep_bits_4_to_2_as_chr_banking() {
        // SKROM-style: 128 KiB CHR-ROM means the CHR register's upper bits are
        // real CHR address lines, never PRG / PRG-RAM selects.
        let mut m = Mmc1::new(synth_prg(16), synth_chr(32), Mirroring::Vertical, 0).unwrap();
        write5(&mut m, 0xA000, 0x1C);
        assert_eq!(
            m.cpu_read(0xC000),
            15,
            "no outer PRG bank on a CHR-ROM board"
        );
        m.cpu_write(0x6000, 0x33);
        write5(&mut m, 0xA000, 0x00);
        assert_eq!(
            m.cpu_read(0x6000),
            0x33,
            "no PRG-RAM banking on a CHR-ROM board"
        );
    }

    #[test]
    fn a_pre_v2_7_2_save_state_is_refused() {
        // v1 blobs lack the trailing CHR-A12 latch byte. They loaded with the
        // latch cleared until v2.9.8, which reads the current layout only
        // (ADR 0042).
        let mut m = Mmc1::new(synth_prg(32), Box::new([]), Mirroring::Vertical, 0).unwrap();
        m.notify_a12(true);
        let mut blob = m.save_state();
        assert_eq!(blob[0], 2);
        assert_eq!(*blob.last().unwrap(), 1, "the latch is saved");
        let mut fresh = Mmc1::new(synth_prg(32), Box::new([]), Mirroring::Vertical, 0).unwrap();
        fresh.load_state(&blob).expect("a v2 blob loads");
        assert!(fresh.chr_a12_high, "the latch is restored");
        blob.pop();
        blob[0] = 1;
        assert!(matches!(
            m.load_state(&blob),
            Err(MapperError::UnsupportedVersion(1))
        ));
        assert!(m.load_state(&[9]).is_err(), "an unknown version is refused");
    }

    /// NC-12 (v2.9.9 re-audit): a restored serial count above 4, or a shift
    /// register with bits above 4, is refused rather than wrapping (release)
    /// or overflowing (debug) at the next serial write.
    #[test]
    fn an_out_of_range_serial_port_is_refused_on_restore() {
        let m = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        let good = m.save_state();
        let mut probe = Mmc1::new(synth_prg(4), synth_chr(2), Mirroring::Vertical, 0).unwrap();
        assert!(probe.load_state(&good).is_ok());
        for (idx, value) in [(6usize, 5u8), (6, 0xFF), (5, 0x20), (5, 0xFF)] {
            let mut bad = good.clone();
            bad[idx] = value;
            assert!(
                matches!(probe.load_state(&bad), Err(MapperError::Invalid(_))),
                "byte {idx} = {value:#04x} must be refused"
            );
        }
        let mut edge = good;
        edge[6] = 4;
        edge[5] = 0x1F;
        assert!(
            probe.load_state(&edge).is_ok(),
            "count 4, shift $1F is a real state"
        );
    }
}