rustynes_mappers/

mapper.rs

//! `Mapper` trait + supporting `MapperError` type.
//!
//! Concrete mappers live in their own modules (e.g. `nrom`). The trait
//! interface follows `docs/mappers.md` §Interfaces; the rationale for
//! mapper-resident IRQ logic is in `docs/mappers.md` §IRQ counter mechanisms.

use alloc::{string::String, vec::Vec};
use thiserror::Error;

use crate::cartridge::Mirroring;

/// Per-tile extended-attribute / extended-bank info supplied by mappers that
/// implement an extended attribute mode (currently MMC5 in `$5104` mode 01).
///
/// The PPU consults this at the nametable-byte fetch boundary of each BG
/// tile. When `Some`, the PPU:
///
/// - Replaces the standard 2-bit attribute-derived palette with [`Self::palette`].
/// - Routes the BG pattern fetch for that tile through [`Self::chr_bank`]
///   (a 12-bit physical 4 KiB bank index — see MMC5 `ExGrafix` mode docs).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ExAttribute {
    /// 2-bit palette select (replaces the AT-byte palette).
    pub palette: u8,
    /// 12-bit physical CHR bank for this tile (in 4 KiB units). Combined with
    /// the fine-Y / column offset by the mapper at fetch time.
    pub chr_bank: u16,
}

/// Per-tile override produced by a mapper that implements a vertical
/// split-screen mode (currently MMC5 via `$5200`-`$5202`).
///
/// MMC5's split allows a vertical band of the screen to render from an
/// independently scrolled "alt region" backed by ExRAM-as-nametable and a
/// dedicated 4 KiB CHR bank. The PPU consults
/// [`Mapper::bg_split_state`] once per 8-dot BG fetch group (at the NT-byte
/// fetch boundary). When `Some(...)` is returned, the PPU uses the supplied
/// nametable address, attribute address, and fine-Y in place of its own
/// loopy-v derivation for that tile, and the mapper internally latches the
/// CHR bank for the following BG pattern fetches.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BgSplitState {
    /// Synthesized nametable byte address in `$2000-$3EFF`, computed from
    /// the alt-region scroll and the current coarse-X.
    pub nt_addr: u16,
    /// Synthesized attribute byte address in the same nametable.
    pub at_addr: u16,
    /// Fine-Y (0..=7) within the alt-region's logical row.
    pub fine_y: u8,
    /// 4 KiB CHR bank index (from `$5202` for MMC5) for the alt region's
    /// BG pattern fetches.
    pub chr_bank: u8,
}

/// Read-only debug snapshot of mapper-internal state for the UI.
///
/// Mappers override [`Mapper::debug_info`] to surface their banking
/// registers and any IRQ-counter state. Fields are pre-formatted strings
/// so the UI doesn't have to know the protocol of each mapper.
#[derive(Debug, Default, Clone)]
pub struct MapperDebugInfo {
    /// Mapper id (e.g. `4` for MMC3).
    pub mapper_id: u16,
    /// Human-readable mapper name (e.g. `"MMC3 (Sharp)"`).
    pub name: String,
    /// Current mirroring layout name (`"Horizontal"`, `"Vertical"`,
    /// `"SingleScreen"`, `"FourScreen"`).
    pub mirroring: &'static str,
    /// PRG bank registers — one (label, value) entry per register the
    /// mapper exposes. Values are hex-formatted by the mapper.
    pub prg_banks: Vec<(String, String)>,
    /// CHR bank registers — same shape as `prg_banks`.
    pub chr_banks: Vec<(String, String)>,
    /// IRQ counter state — `(label, value)` pairs, e.g.
    /// `[("counter", "0x12"), ("reload", "0x80"), ("enabled", "true")]`.
    pub irq_state: Vec<(String, String)>,
    /// Free-form extra status (envelope shape, sub-mapper flags, ...).
    pub extra: Vec<(String, String)>,
    // v1.5.0 "Lens" Workstream I8 — cartridge-level metadata, populated by the
    // bus (it owns the `Cartridge`) when it builds the debug view, NOT by each
    // mapper. All default to empty / 0 / None so a mapper's own `debug_info()`
    // (which leaves these untouched) is unchanged, and the headless / no-pack
    // path is byte-identical (this is an output-only inspection struct).
    /// NES 2.0 submapper id (0 for iNES 1.0).
    pub submapper: u8,
    /// Accuracy-evidence tier name (`"Core"` / `"Curated"` / `"BestEffort"`),
    /// empty if the id isn't classified.
    pub tier: &'static str,
    /// PRG-ROM size in bytes.
    pub prg_rom_size: usize,
    /// CHR-ROM size in bytes (0 when the board uses CHR-RAM).
    pub chr_rom_size: usize,
    /// Requested PRG-RAM size in bytes.
    pub prg_ram_size: usize,
    /// Requested CHR-RAM size in bytes (0 when the board ships CHR-ROM).
    pub chr_ram_size: usize,
    /// True when PRG-RAM is battery-backed (save RAM / NVRAM present).
    pub has_battery: bool,
    /// The IRQ mechanism, when the board has one (e.g. `"PPU A12 (MMC3)"`,
    /// `"PPU scanline (MMC5)"`, `"CPU cycle (VRC/FME-7/N163)"`). Empty if the
    /// board has no IRQ source.
    pub irq_kind: &'static str,
    /// On-cart expansion-audio chip name, if any (e.g. `"VRC6"`).
    pub expansion_audio: Option<&'static str>,
}

/// APU frame-counter event mask fanned out to the mapper, used by on-cart
/// audio extensions (MMC5, FDS, …) whose internal envelopes / length counters
/// share the CPU's frame-counter clocks.
///
/// The bus calls [`Mapper::notify_frame_event`] once per CPU cycle, passing
/// the events the APU's frame counter fired on the same cycle. For mappers
/// without on-cart audio (or with audio that doesn't use envelopes / length
/// counters, like VRC6) the default no-op impl is used.
///
/// The struct shape matches `rustynes_apu::frame_counter::FrameEvents` 1:1; the
/// duplication is deliberate — `rustynes-mappers` does not depend on `rustynes-apu`,
/// and the bus is responsible for translating between the two types.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct MapperFrameEvents {
    /// Quarter-frame: clock envelopes.
    pub quarter: bool,
    /// Half-frame: clock length counters (and sweeps, for 2A03 — but MMC5
    /// pulses have no sweep unit).
    pub half: bool,
}

/// Errors produced by mapper save-state load.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum MapperError {
    /// Save-state blob is not the length this mapper's state has: shorter
    /// or longer. (Until v2.9.9 the message said "truncated" for a long blob
    /// too; NC-14. Until v3.0.0 the variant itself was named `Truncated`,
    /// which said the opposite of half its uses; T-API-EXTENSIBLE.)
    #[error("mapper save state has the wrong length: expected {expected} bytes, got {got}")]
    WrongLength {
        /// Expected byte count.
        expected: usize,
        /// Actual byte count.
        got: usize,
    },

    /// Save-state blob carries an unknown version tag.
    #[error("mapper save state has unsupported version {0}")]
    UnsupportedVersion(u8),

    /// Save-state blob would put the mapper into an inconsistent state.
    #[error("mapper save state invalid: {0}")]
    Invalid(String),
}

/// v2.8.0 Phase 4 — per-CPU-cycle mapper capability flags (see
/// [`Mapper::caps`]). Each flag corresponds to one of the four hooks the
/// bus would otherwise virtually dispatch every CPU cycle.
// Four INDEPENDENT capability bits, one per skippable hook — a bitflags
// type would obscure the 1:1 hook mapping for zero gain.
#[allow(clippy::struct_excessive_bools)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MapperCaps {
    /// The mapper overrides [`Mapper::notify_cpu_cycle`] (CPU-clocked IRQ
    /// counters: VRC4/6/7, FME-7, Namco 163, MMC3's A12 filter clock, …).
    pub cpu_cycle_hook: bool,
    /// The mapper overrides [`Mapper::mix_audio`] (on-cart expansion audio;
    /// only meaningful when the `mapper-audio` feature is compiled in).
    pub audio: bool,
    /// The mapper overrides [`Mapper::notify_frame_event`] (MMC5 audio's
    /// frame-counter-cadenced envelope/length clocks).
    pub frame_event_hook: bool,
    /// The mapper overrides [`Mapper::irq_pending`] (it can assert IRQs).
    pub irq_source: bool,
}

impl MapperCaps {
    /// Every hook dispatched — the safe default for unannotated mappers.
    pub const ALL: Self = Self {
        cpu_cycle_hook: true,
        audio: true,
        frame_event_hook: true,
        irq_source: true,
    };
    /// No hooks — discrete boards (NROM/UxROM/CNROM/AxROM/…) with no IRQ,
    /// no audio, and no per-cycle state.
    pub const NONE: Self = Self {
        cpu_cycle_hook: false,
        audio: false,
        frame_event_hook: false,
        irq_source: false,
    };
    /// CPU-cycle hook + IRQ source (the common IRQ-mapper shape).
    pub const CYCLE_IRQ: Self = Self {
        cpu_cycle_hook: true,
        audio: false,
        frame_event_hook: false,
        irq_source: true,
    };
}

/// Trait implemented by every cartridge mapper.
///
/// Visible read/write addresses follow `docs/architecture.md`
/// §Per-memory-access fanout. The PPU bus call covers the whole
/// `$0000-$3FFF` address space because nametable mirroring is mapper-controlled
/// (see `docs/mappers.md` §Mirroring).
///
/// IRQ-emitting mappers signal pending IRQs via [`Mapper::irq_pending`]; the
/// CPU bus polls this on the same cycle it polls APU/external IRQs.
///
/// All trait methods are `&mut self` because every mapper has at least some
/// internal state — open-bus latch, bank registers, IRQ counters, etc. —
/// even on an apparent read.
pub trait Mapper: Send {
    /// Read a byte from the CPU address space `$4020-$FFFF`.
    fn cpu_read(&mut self, addr: u16) -> u8;

    /// Write a byte to the CPU address space `$4020-$FFFF`.
    fn cpu_write(&mut self, addr: u16, value: u8);

    /// Returns `true` when `addr` is **not** wired to mapper-resident
    /// memory — i.e. when `cpu_read(addr)` returns junk and the bus
    /// should fall through to the open-bus latch instead of overwriting
    /// it. The CPU databus is left floating in this case, so the most
    /// recently driven byte stays visible to the next read.
    ///
    /// Default impl covers stock NROM-class boards: the entire
    /// `$4020-$5FFF` window is unmapped (no PRG-RAM, no mapper
    /// registers), and `$6000-$7FFF` is unmapped exactly when the board has
    /// no save RAM to put there ([`Self::sram`] is empty). `$8000-$FFFF` is
    /// PRG-ROM and always mapped. Mappers that DO map any subset of
    /// `$4020-$5FFF` (MMC5 audio + `ExRAM`, FME-7 IRQ control, VRC family
    /// register banks, etc.) must override this to return `false` for their
    /// mapped sub-ranges so the bus uses the real value; a board with ROM or
    /// readable registers at `$6000-$7FFF` but no save RAM must override it
    /// for that window.
    ///
    /// The `$6000-$7FFF` rule is v2.7.2 (core audit §5.5). Before it, every
    /// board without RAM there read a made-up `$00` instead of open bus; a
    /// sweep over every mapper number found 205 board variants doing so
    /// (`tests/prg_ram_window_open_bus.rs`). It leans on v2.7.1's contract that
    /// every board holding save RAM exposes it through `sram()`
    /// (`tests/battery_sram_exposed.rs`), and the same test fails any board
    /// the rule would float while it actually drives data there.
    ///
    /// This is the canonical hardware oracle for `AccuracyCoin`'s
    /// `CPU Behavior :: Open Bus` Test 1 (`LDA $5000` should read
    /// `$50`, not `$00`).
    fn cpu_read_unmapped(&self, addr: u16) -> bool {
        match addr {
            0x4020..=0x5FFF => true,
            0x6000..=0x7FFF => self.sram().is_empty(),
            _ => false,
        }
    }

    /// A CPU read the mapper declined ([`Self::cpu_read_unmapped`]) has just
    /// completed, and `value` is what floated on the bus.
    ///
    /// Only GTROM (mapper 111) uses it: its register latches on any CPU access
    /// to its window, so "reading from the register effectively writes the
    /// value of open bus" (`nesdev_wiki/output/GTROM.md`). Called only on the
    /// unmapped path, so PRG fetches never pay for it. Default: nothing.
    /// Added in v2.9.6.
    fn notify_floating_read(&mut self, _addr: u16, _value: u8) {}

    /// The CPU wrote `value` to the PPU register window (`$2000-$3FFF`), at
    /// the undecoded address `addr`.
    ///
    /// Only MMC5 (mapper 5) uses it: the chip is "known to listen to the same address
    /// as the PPU to find out when to enable the 8x16 sprite mode", decoding
    /// `$2000` and `$2001` fully, so a write to a mirror such as `$2008` is
    /// not seen (`nesdev_wiki/output/MMC5.md`). The address is passed
    /// undecoded for that reason. Called once per PPU register write, never
    /// per cycle. Default: nothing. Added in v2.9.9.
    fn notify_ppu_register_write(&mut self, _addr: u16, _value: u8) {}

    /// Whether PPU `$3000-$3EFF` is independent RAM on this cartridge rather
    /// than a mirror of `$2000-$2EFF`.
    ///
    /// When `true`, [`Self::nametable_fetch`] and [`Self::nametable_write`]
    /// receive `$3000-$3EFF` unfolded. Two boards need it: GTROM's "bonus RAM"
    /// (`GTROM.md`) and UNROM 512's four-screen board (`UNROM_512.md`), whose
    /// nametable RAM covers the whole `$2000-$3EFF` window. Only `$2007`
    /// accesses reach `$3xxx` (rendering fetches never do), and the PPU asks
    /// only for those, so rendering pays nothing. Default: `false`, the
    /// console's own mirroring. Added in v2.9.6.
    fn nametable_unfolded(&self) -> bool {
        false
    }

    /// Which data bits a mapped read in the register window (`$4020-$5FFF`)
    /// actually drives; the rest float and keep the bus's open-bus value.
    ///
    /// A register that drives only part of the byte is common on cheap ASICs:
    /// the Sachen SA-020A (mappers 150 / 243) returns its 3-bit registers on
    /// D2-D0 and leaves D7-D3 floating (`nesdev_wiki/INES_Mapper_150.xhtml`).
    /// Returning the undriven bits as 0 from [`Self::cpu_read`] would let the
    /// bus latch those zeros; this mask lets it keep what was floating there
    /// instead (core audit §4.5).
    ///
    /// Consulted only for `$4020-$5FFF`, so it costs nothing on the
    /// `$6000-$FFFF` fetches that dominate CPU time. Default: all 8 bits.
    fn cpu_read_driven_mask(&self, _addr: u16) -> u8 {
        0xFF
    }

    /// Read a byte from the PPU address space `$0000-$3FFF` (pattern table
    /// + nametable mirror window). Used as the BG-side / generic fetch path.
    fn ppu_read(&mut self, addr: u16) -> u8;

    /// Read a byte from the PPU pattern-table window (`$0000-$1FFF`) on
    /// behalf of a *sprite* tile fetch. MMC5 in 8x16 sprite mode uses a
    /// separate set of CHR bank registers (`$5120-$5127`) for sprite
    /// fetches; other mappers default to forwarding to [`Mapper::ppu_read`].
    fn ppu_read_sprite(&mut self, addr: u16) -> u8 {
        self.ppu_read(addr)
    }

    /// HD-pack tile identity: the ABSOLUTE post-banking offset into CHR-ROM for a
    /// pattern-space address `$0000-$1FFF` (`Some(offset)`), or `None` for CHR-RAM
    /// (content-hashed instead). `tile_index = offset / 16` is the key Mesen uses
    /// for CHR-ROM `<tile>` replacements. Default `None` so an unported mapper
    /// falls back to the content-hash path (no worse than before); the common
    /// CHR-ROM mappers override it by exposing their internal CHR mapping.
    fn chr_phys(&self, _addr: u16) -> Option<u32> {
        None
    }

    /// v3.1.0 (`T-SPRITE-LIMIT`) — whether [`Self::ppu_read`] and
    /// [`Self::ppu_read_sprite`] on `$0000-$1FFF` change nothing but return a
    /// byte. `true` (the default) lets the PPU's "disable sprite limit" option
    /// make extra, display-only pattern reads on this board.
    ///
    /// Override to `false` for any board whose CHR read has an effect: a latch
    /// that switches banks on a tile (MMC2, MMC4), an IRQ counter clocked by
    /// reads (the J.Y. ASIC), or address bits latched from the read (Bandai
    /// 96, Nanjing 163). `every_board_that_claims_pure_chr_reads_has_them`
    /// checks the claim against `save_state` for every mapper id, so a new
    /// impure board that keeps the default fails a test rather than letting
    /// the option change emulation.
    fn chr_reads_are_pure(&self) -> bool {
        true
    }

    /// v3.1.0 (`T-MMC3-NEC-OVERRIDE`, ACC-13) — force an MMC3's IRQ revision
    /// (`Some`), or return to the one its header selected (`None`). Returns
    /// whether this board is an MMC3 that applied it; every other board
    /// ignores it (the default). Lets an iNES 1.0 dump, which cannot name its
    /// MMC3 revision, run under the alternate (`Nec`) behaviour.
    fn set_mmc3_revision_override(&mut self, _revision: Option<crate::Mmc3Revision>) -> bool {
        false
    }

    /// Write a byte to the PPU address space `$0000-$3FFF`.
    fn ppu_write(&mut self, addr: u16, value: u8);

    /// Optionally synthesize a nametable byte for `addr` ($2000-$3EFF).
    ///
    /// When the mapper returns `Some(v)`, the PPU uses `v` directly and
    /// skips its CIRAM read. MMC5 uses this for "fill mode" (`$5105`
    /// per-1KiB selector value 0b11), where every nametable-byte fetch
    /// returns the fill tile (`$5106`) and every attribute-byte fetch
    /// returns a 2-bit attribute (`$5107`) replicated 4 ways.
    ///
    /// Default returns `None` (mapper does not synthesize; PPU reads CIRAM).
    fn nametable_fetch(&mut self, _addr: u16) -> Option<u8> {
        None
    }

    /// Optionally absorb a nametable write for `addr` ($2000-$3EFF) directly
    /// into mapper-resident storage.
    ///
    /// Returns `true` if the mapper consumed the write (PPU should NOT also
    /// write its CIRAM). MMC5 uses this for ExRAM-mapped nametables and for
    /// fill mode (where writes are silently dropped).
    ///
    /// Default returns `false` (PPU continues with the CIRAM write path).
    fn nametable_write(&mut self, _addr: u16, _value: u8) -> bool {
        false
    }

    /// Optionally provide per-tile extended attribute + CHR-bank override for
    /// the BG tile currently being fetched.
    ///
    /// `v` is the PPU's loopy-v register value at NT-byte fetch time
    /// (`fetch_nt`); the lower 12 bits encode the 32x30 tile coordinate.
    /// MMC5 in `$5104` mode 01 returns `Some` here. The PPU uses the
    /// returned palette to override the AT byte. The mapper itself caches
    /// the `chr_bank` internally so that the subsequent BG pattern fetches
    /// (`ppu_read` calls during the same 8-dot fetch group) consult it
    /// instead of the standard BG bank registers.
    ///
    /// Default returns `None` (no extended attribute mode active).
    fn peek_ex_attribute(&mut self, _v: u16) -> Option<ExAttribute> {
        None
    }

    /// Optionally redirect a BG fetch group into a vertical split-screen
    /// "alt region".
    ///
    /// Called by the PPU at the NT-byte fetch boundary of each 8-dot BG
    /// fetch group, once per tile column (32 times per visible scanline).
    /// `scanline_y` is the current visible-scanline index in 0..=239 (the
    /// pre-render line passes 0 here to keep the path branchless). `coarse_x`
    /// is the loopy-v coarse-X (0..=31) for the tile about to be fetched.
    ///
    /// Returning `Some(state)` instructs the PPU to use the supplied
    /// `nt_addr` / `at_addr` / `fine_y` instead of those derived from `v`,
    /// and instructs the mapper to internally latch the CHR bank for the
    /// pattern fetches that immediately follow.
    ///
    /// Default returns `None`.
    fn bg_split_state(&mut self, _scanline_y: u16, _coarse_x: u16) -> Option<BgSplitState> {
        None
    }

    /// Resolve a nametable address in `$2000-$3EFF` to a CIRAM offset in
    /// `0..0x800`. The PPU owns the 2 KiB CIRAM and uses this hook to apply
    /// per-mapper mirroring without giving the mapper direct access to the
    /// console-side VRAM.
    ///
    /// Default impl applies the mirroring reported by [`Mapper::current_mirroring`]
    /// via [`crate::Mirroring::physical_bank`]. Mappers with on-cart 4-screen
    /// VRAM (Gauntlet, Rad Racer II) can override this; the lockstep bus
    /// will trampoline the read/write back through the mapper for any offset
    /// outside `0..0x800` if needed (Phase 4).
    #[allow(clippy::cast_possible_truncation)]
    fn nametable_address(&self, addr: u16) -> u16 {
        const NAMETABLE_SIZE: u16 = 0x0400;
        let table = ((addr.wrapping_sub(0x2000)) / NAMETABLE_SIZE) & 0x03;
        let local = addr & (NAMETABLE_SIZE - 1);
        // `physical_bank` always returns 0 or 1; the truncation is a no-op.
        let physical = self.current_mirroring().physical_bank(table as u8) as u16;
        physical * NAMETABLE_SIZE + local
    }

    /// Notify of a PPU A12 line transition. Default no-op; MMC3 / MMC5
    /// override this for IRQ counter clocking.
    fn notify_a12(&mut self, _level: bool) {}

    /// Notify of a PPU A12 line transition with the current sub-dot of
    /// the host CPU cycle (0 / 1 = M2-low half; 2 = M2-high half).
    /// Default impl falls through to [`Self::notify_a12`] so existing
    /// mappers compile unchanged; MMC3 overrides this for the
    /// M2-phase-aware IRQ-output propagation delay required by
    /// `mmc3_test_2/4-scanline_timing` sub-test #3 (C1 step B4 successor).
    fn notify_a12_at_sub_dot(&mut self, level: bool, _sub_dot: u8) {
        self.notify_a12(level);
    }

    /// Notify of a CPU cycle. Default no-op; VRC2/4/6, FME-7, Namco 163
    /// override this for IRQ counter clocking.
    fn notify_cpu_cycle(&mut self) {}

    /// The console's RESET button (a soft reset, not a power cycle).
    ///
    /// A cartridge sees reset only on the boards that wire the CIC's reset
    /// line, or /RESET itself, into their logic, so the default does nothing
    /// and almost every board keeps its registers across a reset, exactly as
    /// on a console. The boards that clear something are documented per page:
    /// mapper 37's outer latch (`INES_Mapper_037.md`), mapper 45's outer
    /// registers, NES-EVENT's PRG lock (mapper 105), the 76-in-1 BMC's two
    /// registers (mapper 226, since v2.9.8), and Action 52's register
    /// (mapper 228). Added in v2.9.6; a power cycle rebuilds the mapper
    /// instead and never calls this.
    fn reset(&mut self) {}

    /// Notify the mapper of the APU frame-counter events fired on the
    /// current CPU cycle (quarter-frame envelope clock, half-frame length
    /// clock). Only on-cart audio extensions that re-use the 2A03 frame
    /// counter cadence need to handle this (MMC5 audio's two pulse
    /// channels). Default no-op.
    fn notify_frame_event(&mut self, _events: MapperFrameEvents) {}

    /// Notify the mapper that the PPU is starting a new rendered scanline.
    ///
    /// Called by the PPU at the start of each visible scanline (and the
    /// pre-render line) before any tile fetches happen. MMC5 uses this to
    /// drive its scanline IRQ counter (which clocks at PPU cycle 4 of each
    /// rendered line — different from MMC3's A12-edge-driven counter).
    ///
    /// Default is a no-op; only mappers with scanline-counter IRQs override.
    fn notify_scanline_start(&mut self) {}

    /// Notify the mapper that the PPU has entered vertical blank.
    ///
    /// MMC5 uses this to clear its "in-frame" flag (bit 6 of `$5204`).
    /// Default no-op.
    fn notify_vblank(&mut self) {}

    /// v2.0.0 beta.5 (Vs. `DualSystem`): provision the board's shared 2 KiB
    /// work RAM at `$6000-$7FFF` (mirrored across the 8 KiB window — MAME
    /// `vsnes.cpp`: `map(0x6000, 0x67ff).mirror(0x1800).ram()`). Only the
    /// Vs. System board (mapper 99) implements this — the `DualSystem`
    /// cabinets carry a 2 KiB RAM shared between the two consoles, absent
    /// on `UniSystem` carts (whose `$6000` window stays open bus,
    /// byte-identically). Called by the `VsDualSystem` wrapper at
    /// construction on both consoles: each console holds its own COPY, and
    /// the wrapper converges the copies by draining the write log (below)
    /// after every stepped instruction — MAME's fully-shared
    /// `.share("nvram")` model at soft-lockstep granularity. Default no-op.
    fn enable_vs_dual_wram(&mut self) {}

    /// v2.0.0 beta.5 (Vs. `DualSystem`): mark this mapper instance as the
    /// cabinet's SUB console — it banks the second 32 KiB PRG half and the
    /// upper CHR pages (the two CPUs run DIFFERENT programs; MAME
    /// `balonfgt` loads distinct `sub`-region ROMs, Mesen2 uses
    /// `prgOuter = IsVsMainConsole() ? 0 : 4`). Applied by the
    /// `VsDualSystem` wrapper at construction, like the bus's sub
    /// identity. Default no-op.
    fn set_vs_dual_sub(&mut self) {}

    /// v2.0.0 beta.5 (Vs. `DualSystem`): drain this console's shared-WRAM
    /// write log — every `(offset, value)` the CPU wrote to the window
    /// since the last drain, in order — by APPENDING into `dst` (never
    /// clearing it first). The wrapper replays them into the partner's
    /// copy ([`Self::apply_vs_dual_wram_write`]), which is what makes the
    /// RAM behave as ONE simultaneously-shared memory (MAME's model;
    /// nesdev also documents a `$4016`-bit-1 access mux, but MAME — where
    /// the four `DualSystem` games verifiably run — shares the RAM
    /// unconditionally, and Balloon Fight's boot handshake requires the
    /// partner to see writes made while the mux would deny it access).
    ///
    /// Implementations MUST drain their internal log via `Vec::drain`
    /// (or equivalent) rather than replacing it, so the log's own
    /// allocated capacity is retained across calls — `pump_comms` calls
    /// this after EVERY stepped instruction on a `DualSystem` cart, so a
    /// reallocating drain here is a real hot-path allocation, not a
    /// theoretical one. Default: no-op (boards without the dual WRAM).
    fn drain_vs_dual_wram_writes(&mut self, dst: &mut Vec<(u16, u8)>) {
        let _ = dst;
    }

    /// Convenience wrapper around [`Self::drain_vs_dual_wram_writes`] for
    /// callers that don't already hold a reusable buffer (diagnostics,
    /// tests) — NOT used by the hot `pump_comms` path, which owns and
    /// reuses its own scratch buffer instead.
    fn take_vs_dual_wram_writes(&mut self) -> Vec<(u16, u8)> {
        let mut writes = Vec::new();
        self.drain_vs_dual_wram_writes(&mut writes);
        writes
    }

    /// v2.0.0 beta.5 (Vs. `DualSystem`): replay one partner-console write
    /// into this console's copy of the shared WRAM (see
    /// [`Self::take_vs_dual_wram_writes`]). Does NOT re-log the write (no
    /// echo loop). Default no-op.
    fn apply_vs_dual_wram_write(&mut self, offset: u16, value: u8) {
        let _ = (offset, value);
    }

    /// v2.0.0 beta.5 (Vs. `DualSystem`): take the console's shared-WRAM copy
    /// (used by the wrapper's snapshot-restore normalization — the two
    /// copies are re-converged from one buffer after a restore). Returns
    /// `None` on boards without the dual WRAM. Default `None`.
    fn take_vs_dual_wram(&mut self) -> Option<alloc::boxed::Box<[u8]>> {
        None
    }

    /// v2.0.0 beta.5 (Vs. `DualSystem`): install a shared-WRAM copy (the
    /// other half of the restore normalization). Default no-op.
    // The `Box` is the interface contract (ownership of the one buffer
    // moves between the two consoles' mappers without copying) — the
    // default impl merely drops it, which trips `boxed_local` spuriously.
    #[allow(clippy::boxed_local)]
    fn set_vs_dual_wram(&mut self, wram: alloc::boxed::Box<[u8]>) {
        let _ = wram;
    }

    /// Returns `true` if the mapper is currently asserting an IRQ.
    fn irq_pending(&self) -> bool {
        false
    }

    /// Acknowledge a pending IRQ. Default no-op; mappers that latch IRQ state
    /// override this.
    fn irq_acknowledge(&mut self) {}

    /// Return one signed audio sample for mappers with on-cart audio
    /// (VRC6/7, MMC5, Sunsoft 5B, Namco 163, FDS). Default returns silence.
    ///
    /// **`i32`, widened from `i16` in v2.2.3 (A1).** The bus scales this by
    /// `/ 65536.0` into roughly the same `[-0.5, 0.5]` range as the APU mixer's
    /// own output, so the old `i16` return capped a chip's representable level
    /// at `32767 / 65536 ≈ 0.5`. That was fine for every board except the
    /// Sunsoft 5B, whose logarithmic DAC needs ~3.6x the 2A03 pulse at full
    /// volume — and three simultaneous full-volume tones (Gimmick!, Hebereke)
    /// several times more. The 5B's absolute level was therefore a documented,
    /// deliberately un-calibrated gap purely because the return type could not
    /// hold it. Widening the type is what unblocks it; see
    /// `docs/accuracy-ledger.md` §Expansion-audio levels and `SUNSOFT5B_MIX_SCALE`.
    ///
    /// Boards other than the 5B return exactly the values they always did —
    /// the widening is representational only and changes no mixed output.
    fn mix_audio(&mut self) -> i32 {
        0
    }

    /// v2.8.0 Phase 4 — the mapper's per-CPU-cycle capability flags.
    ///
    /// The bus fans four virtual calls out to the mapper EVERY CPU cycle
    /// (~30 k/frame each): [`Self::notify_cpu_cycle`], [`Self::mix_audio`],
    /// [`Self::notify_frame_event`], and [`Self::irq_pending`]. For most
    /// boards all four are the default no-ops, so the bus caches these
    /// flags at construction and skips the dispatch entirely.
    ///
    /// The contract is mechanical: a flag may be `false` ONLY when the
    /// mapper does not override the corresponding default method (skipping
    /// a default no-op is provably byte-identical). The default returns
    /// [`MapperCaps::ALL`], so an unannotated mapper keeps every dispatch —
    /// always correct, just slower.
    fn caps(&self) -> MapperCaps {
        MapperCaps::ALL
    }

    /// Returns the mapper's current effective mirroring layout.
    ///
    /// Most mappers report the static mirroring set in the cartridge header;
    /// mappers with runtime mirroring control (MMC1, MMC3, `AxROM`, ...) report
    /// the live state.
    fn current_mirroring(&self) -> Mirroring;

    /// Whether this mapper's nametable mirroring is **hardwired by the
    /// cartridge** (solder pads / the iNES header bit) rather than controlled
    /// by the mapper's own registers at runtime.
    ///
    /// This gates whether an *external* mirroring correction (e.g. a per-game
    /// database entry, applied via `Nes::set_mirroring_override`) may
    /// be honored. A static override is only meaningful for a hardwired board
    /// whose header bit can be *wrong*; forcing a static mirroring onto a mapper
    /// that switches mirroring itself (MMC1/3/5, `AxROM`, VRC, Sunsoft FME-7,
    /// Namco 163, …) **corrupts** its rendering — e.g. `AxROM`'s mid-frame
    /// single-screen A↔B flip that draws Wizards & Warriors' status bar, whose
    /// GoodNES-derived game-DB row lists a spurious `Horizontal` that, when
    /// force-applied, blanks the bottom of the screen and hangs the game.
    ///
    /// Default: `false` (assume the mapper controls its own mirroring). This is
    /// the **safe** default — a mapper that omits an annotation merely declines
    /// a rarely-needed, cosmetic header correction; it can never break a working
    /// game. Only the classic fixed-mirroring discrete boards (`NROM`, `UxROM`,
    /// `CNROM`, `GxROM`, …) override this to `true`.
    fn has_hardwired_mirroring(&self) -> bool {
        false
    }

    // --- Optional Famicom Disk System (FDS) disk interface ---
    //
    // Only the FDS device (`fds::Fds`) overrides these; every other mapper uses
    // the default no-op / empty impls. The bus and `Nes` surface them so a
    // frontend can drive side-swap and persist a modified disk without
    // downcasting the `Box<dyn Mapper>`.

    /// Number of disk sides in the inserted image (0 for non-FDS mappers).
    fn disk_side_count(&self) -> usize {
        0
    }

    /// The currently inserted disk side index, or `None` when ejected (or for
    /// non-FDS mappers).
    fn inserted_disk_side(&self) -> Option<usize> {
        None
    }

    /// Insert disk side `i` (`Some`) or eject the disk (`None`). No-op for
    /// non-FDS mappers; an out-of-range index is ignored by the FDS device.
    fn set_disk_side(&mut self, _side: Option<usize>) {}

    /// Returns a reference to the mapper's internal SRAM/PRG-RAM.
    /// By default, returns an empty slice if unsupported.
    fn sram(&self) -> &[u8] {
        &[]
    }

    /// Returns a mutable reference to the mapper's internal SRAM/PRG-RAM.
    /// By default, returns an empty mutable slice if unsupported.
    fn sram_mut(&mut self) -> &mut [u8] {
        &mut []
    }

    /// The cartridge's non-volatile data: what a battery save persists and a
    /// power cycle keeps. For almost every board that is its battery-backed
    /// RAM, [`Self::sram`], and the default says so.
    ///
    /// Self-flashable boards differ (v2.9.6). GTROM and a flashable UNROM 512
    /// save by rewriting their own PRG flash, so their save is the flash image,
    /// and they have no RAM at `$6000` at all. Keeping the two apart is the
    /// point. `sram()` goes on meaning "the RAM in the `$6000` window", which
    /// the open-bus rule, the libretro memory map and `RetroAchievements` all
    /// rely on. Only the save paths read this.
    fn save_data(&self) -> &[u8] {
        self.sram()
    }

    /// Mutable [`Self::save_data`], for loading a save.
    fn save_data_mut(&mut self) -> &mut [u8] {
        self.sram_mut()
    }

    /// Return the save data to the state of a cartridge that has never been
    /// saved to. That is zeroed RAM by default. On a flash board it is the PRG
    /// image as loaded, since a zero-filled flash would be a ROM with no
    /// program in it. A power-on movie calls this (`power_on_for_movie`).
    fn clear_save_data(&mut self) {
        self.save_data_mut().fill(0);
    }

    /// Start recording the diagnostic FDS read-stream trace (off by default;
    /// observation-only). No-op for non-FDS mappers. See [`crate::FdsTraceRec`].
    fn enable_fds_trace(&mut self) {}

    /// Drain the accumulated FDS read-stream trace records (empty for non-FDS
    /// mappers / when tracing was never enabled).
    fn take_fds_trace(&mut self) -> Vec<crate::FdsTraceRec> {
        Vec::new()
    }

    /// Re-serialize the (possibly-modified) disk image to its byte layout for
    /// host persistence. Returns an empty vector for non-FDS mappers.
    fn disk_image_bytes(&self) -> Vec<u8> {
        Vec::new()
    }

    /// Whether the disk image has unsaved writes. Always `false` for non-FDS
    /// mappers.
    fn disk_is_dirty(&self) -> bool {
        false
    }

    /// Clear the disk dirty flag (a host calls this after persisting). No-op
    /// for non-FDS mappers.
    fn clear_disk_dirty(&mut self) {}

    /// Mark the inserted disk read-only (`true`) or writable (`false`). No-op
    /// for non-FDS mappers.
    fn set_disk_write_protected(&mut self, _protected: bool) {}

    // --- Optional NSF music-player interface ---
    //
    // Only the NSF player (`nsf::NsfMapper`) overrides these; every other mapper
    // uses the default 0 / no-op impls. The bus and `Nes` surface them so a
    // frontend can drive track selection without downcasting the boxed mapper.

    /// Number of selectable songs (0 for a non-NSF mapper).
    fn nsf_song_count(&self) -> u8 {
        0
    }

    /// The currently-selected 0-based song (0 for a non-NSF mapper).
    fn nsf_current_song(&self) -> u8 {
        0
    }

    /// Select a 0-based song. Returns `true` if this is an NSF mapper (so the
    /// caller knows to re-run the reset that re-vectors into the driver's
    /// `init`). Default no-op returning `false`.
    fn nsf_set_song(&mut self, _song: u8) -> bool {
        false
    }

    /// Encode the mapper's mutable state into a tagged save-state blob.
    fn save_state(&self) -> Vec<u8>;

    /// Decode a previously [`Mapper::save_state`] blob back into the mapper.
    ///
    /// # Errors
    ///
    /// Returns [`MapperError`] when the blob is truncated, has the wrong
    /// version tag, or otherwise fails internal consistency checks.
    fn load_state(&mut self, data: &[u8]) -> Result<(), MapperError>;

    /// Surface read-only debug info for the UI. Override per mapper to
    /// expose bank registers, IRQ counters, etc. Default returns a
    /// minimal entry naming the mapper id.
    fn debug_info(&self) -> MapperDebugInfo {
        // The bus fills the cartridge-level metadata fields (submapper, tier,
        // sizes, battery, irq_kind, expansion_audio) — see
        // `Bus::mapper_debug_info` — so they default here (v1.5.0 I8).
        MapperDebugInfo {
            mapper_id: 0,
            name: "(unknown)".into(),
            mirroring: mirroring_name(self.current_mirroring()),
            prg_banks: Vec::new(),
            chr_banks: Vec::new(),
            irq_state: Vec::new(),
            extra: Vec::new(),
            ..Default::default()
        }
    }
}

/// Helper for mapper `debug_info` overrides.
#[must_use]
pub const fn mirroring_name(m: Mirroring) -> &'static str {
    match m {
        Mirroring::Horizontal => "Horizontal",
        Mirroring::Vertical => "Vertical",
        Mirroring::SingleScreenA => "SingleScreen (A)",
        Mirroring::SingleScreenB => "SingleScreen (B)",
        Mirroring::FourScreen => "FourScreen",
        Mirroring::MapperControlled => "MapperControlled",
    }
}

#[cfg(test)]
mod caps_tests {
    use super::MapperCaps;
    use crate::{Mapper, parse};
    use alloc::{boxed::Box, vec, vec::Vec};

    /// Build a minimal iNES image for `mapper_id` (32 KiB PRG + 8 KiB CHR —
    /// 32 KiB satisfies every family probed below, incl. `AxROM`'s
    /// 32-KiB-multiple requirement).
    fn synth_rom(mapper_id: u8) -> Vec<u8> {
        let mut rom = vec![
            b'N',
            b'E',
            b'S',
            0x1A,
            2, // 32 KiB PRG
            1, // 8 KiB CHR
            (mapper_id << 4),
            (mapper_id & 0xF0),
        ];
        rom.resize(16, 0);
        rom.resize(16 + 32 * 1024 + 8 * 1024, 0);
        rom
    }

    fn caps_of(mapper_id: u8) -> MapperCaps {
        let (_cart, mapper): (_, Box<dyn Mapper>) =
            parse(&synth_rom(mapper_id)).expect("synth rom parses");
        mapper.caps()
    }

    /// v3.1.0 (`T-SPRITE-LIMIT`): every board that reports
    /// `chr_reads_are_pure` really has pure CHR reads. The PPU's "disable
    /// sprite limit" option makes extra pattern reads exactly where this is
    /// `true`, so a wrong `true` would let a display option change emulation.
    ///
    /// For every mapper id the parser builds from a synthetic ROM (iNES ids
    /// 0-255 and NES 2.0 ids 256-4095), read all of CHR through both entry
    /// points and require `save_state` to be unchanged. The five boards that
    /// report `false` were found by a scan of every `ppu_read` body for writes
    /// to `self` (v3.1.0); this test is what keeps a sixth from keeping the
    /// default. It cannot see state a board leaves out of `save_state`, which
    /// would already be a save-state defect of its own.
    #[test]
    fn every_board_that_claims_pure_chr_reads_has_them() {
        fn nes2_rom(id: u16) -> Vec<u8> {
            let [lo, hi] = id.to_le_bytes();
            let mut rom = synth_rom(lo);
            rom[7] = (rom[7] & 0xF0) | 0x08; // NES 2.0 identifier
            rom[8] = hi & 0x0F; // mapper bits 8-11
            rom
        }
        let mut checked = 0usize;
        let mut impure = Vec::new();
        for id in 0u16..4096 {
            let rom = u8::try_from(id).map_or_else(|_| nes2_rom(id), synth_rom);
            let Ok((_cart, mut mapper)) = parse(&rom) else {
                continue;
            };
            if !mapper.chr_reads_are_pure() {
                impure.push(id);
                continue;
            }
            let before = mapper.save_state();
            for addr in 0..0x2000u16 {
                let _ = mapper.ppu_read(addr);
                let _ = mapper.ppu_read_sprite(addr);
            }
            assert_eq!(
                before,
                mapper.save_state(),
                "mapper {id} reports pure CHR reads, but reading CHR changed its state"
            );
            checked += 1;
        }
        assert!(checked > 150, "only {checked} boards were checked");
        assert_eq!(
            impure,
            vec![9, 10, 35, 90, 96, 163, 209, 211],
            "the impure set moved"
        );
    }

    /// v2.8.0 Phase 4 — the capability-flag contract for the key families.
    /// A flag may be `false` ONLY when the mapper does not override the
    /// corresponding default no-op; these spot checks pin the mechanical
    /// derivation for the highest-population boards.
    #[test]
    fn caps_match_overridden_hooks_for_key_mappers() {
        // NROM / UxROM / CNROM / AxROM / GxROM: no hooks at all.
        for id in [0u8, 2, 3, 7, 66] {
            assert_eq!(caps_of(id), MapperCaps::NONE, "mapper {id}");
        }
        // MMC1: overrides ONLY notify_cpu_cycle (write throttle) — no IRQ.
        let m1 = caps_of(1);
        assert!(m1.cpu_cycle_hook && !m1.irq_source && !m1.audio && !m1.frame_event_hook);
        // MMC3: cycle hook (A12 filter clock) + IRQ source.
        assert_eq!(caps_of(4), MapperCaps::CYCLE_IRQ);
        // MMC5: cycle + IRQ + frame-event hook (+ audio when compiled in).
        let m5 = caps_of(5);
        assert!(m5.cpu_cycle_hook && m5.irq_source && m5.frame_event_hook);
        assert_eq!(m5.audio, cfg!(feature = "mapper-audio"));
        // VRC6a: cycle + IRQ + audio-when-compiled.
        let m24 = caps_of(24);
        assert!(m24.cpu_cycle_hook && m24.irq_source && !m24.frame_event_hook);
        assert_eq!(m24.audio, cfg!(feature = "mapper-audio"));
    }

    fn hardwired_of(mapper_id: u8) -> bool {
        let (_cart, mapper): (_, Box<dyn Mapper>) =
            parse(&synth_rom(mapper_id)).expect("synth rom parses");
        mapper.has_hardwired_mirroring()
    }

    /// Regression guard for the Wizards & Warriors freeze (game-DB `Horizontal`
    /// force-applied onto `AxROM`'s mapper-controlled single-screen split): a
    /// mapper that controls its OWN mirroring MUST report
    /// `has_hardwired_mirroring() == false` so the frontend declines an external
    /// mirroring override; a fixed-mirroring discrete board MUST report `true`.
    #[test]
    fn hardwired_mirroring_gate_matches_board_type() {
        // Fixed solder-pad mirroring — an external correction is valid.
        for id in [0u8, 2, 3, 66] {
            assert!(hardwired_of(id), "mapper {id} must be hardwired-mirroring");
        }
        // Mapper-controlled mirroring — an external override would corrupt them.
        // 7 = AxROM (the W&W bug), 1 = MMC1, 4 = MMC3, 5 = MMC5, 9 = MMC2.
        for id in [7u8, 1, 4, 5, 9] {
            assert!(
                !hardwired_of(id),
                "mapper {id} controls its own mirroring — must NOT be hardwired"
            );
        }
    }
}