Struct Fds 

pub struct Fds { /* private fields */ }

FDS RAM-adapter device, modelled as a Mapper.

Owns the PRG-RAM, CHR-RAM, BIOS, the inserted disk image, all register state, the timer-IRQ counter, and the disk-read head. Routed by the bus for every CPU access in $4020-$FFFF; $4020-$409F registers are surfaced via Mapper::cpu_read_unmapped returning false for that window.

Implementations

impl Fds

pub fn new(disk: FdsDisk, bios: &[u8]) -> Result<Self, RomError>

Construct an FDS device from a parsed disk image and an 8 KiB BIOS.

Errors

Returns RomError::InvalidConfig if the BIOS is not exactly 8 KiB.

pub fn medium_write_verify(&self) -> Result<(), FdsMediumError>

Walk the synthesized wire image of the currently inserted side and verify every block’s gap / start-mark framing and per-block CRC-16 round-trips — the synthetic FDS write-verify oracle (v2.2.0 “Capstone”).

This is deliberately BIOS-free: it validates the emulator’s own medium synthesis (gap runs, $80 start marks, CRC-16/KERMIT block CRCs) so the write path can be exercised and checked entirely in CI without any copyright FDS BIOS. The real-BIOS write path (which recomputes the CRC in its own RAM and streams it to $4024) is validated only from a local, gitignored dump — see docs/accuracy-ledger.md for the CI-verifiable vs local-only split.

Errors

Returns the first FdsMediumError encountered (missing start mark, CRC mismatch, truncated block, or a corrupted inter-block gap). Returns Ok(()) when no side is inserted (nothing to verify).

pub const fn set_analog_head_seek(&mut self, enabled: bool)

Enable or disable the continuous analog head-seek model (default off).

Opt-in accuracy feature: when disabled (the default) motor-restart rewinds use the flat HEAD_RESEEK_CYCLES window, so a non-writing .fds run is byte-identical to prior releases. When enabled, the re-seek window scales with head-travel distance (belt velocity). See Self::reseek_window_cycles.

pub const fn analog_head_seek(&self) -> bool

Whether the continuous analog head-seek model is currently enabled.

pub fn quirk(&self) -> FdsQuirk

The per-game timing quirk resolved from the disk CRC-32 at construction (quirk_for_crc). FdsQuirk::NONE for titles without a table entry.

pub fn enable_trace(&mut self)

Start recording the diagnostic FDS read-stream trace (see FdsTraceRec). Off by default; recording is pure observation and never affects emulation.

pub fn take_trace(&mut self) -> Vec<FdsTraceRec>

Drain the accumulated FDS trace records.

Trait Implementations

impl Mapper for Fds

fn sram(&self) -> &[u8]

Returns a reference to the mapper’s internal SRAM/PRG-RAM. By default, returns an empty slice if unsupported.

fn sram_mut(&mut self) -> &mut [u8]

Returns a mutable reference to the mapper’s internal SRAM/PRG-RAM. By default, returns an empty mutable slice if unsupported.

fn caps(&self) -> MapperCaps

v2.8.0 Phase 4 — the mapper’s per-CPU-cycle capability flags.

fn cpu_read(&mut self, addr: u16) -> u8

Read a byte from the CPU address space $4020-$FFFF.

fn cpu_write(&mut self, addr: u16, value: u8)

Write a byte to the CPU address space $4020-$FFFF.

fn cpu_read_unmapped(&self, addr: u16) -> bool

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.

fn ppu_read(&mut self, addr: u16) -> u8

Read a byte from the PPU address space $0000-$3FFF (pattern table

fn ppu_write(&mut self, addr: u16, value: u8)

Write a byte to the PPU address space $0000-$3FFF.

fn notify_cpu_cycle(&mut self)

Notify of a CPU cycle. Default no-op; VRC2/4/6, FME-7, Namco 163 override this for IRQ counter clocking.

fn irq_pending(&self) -> bool

Returns true if the mapper is currently asserting an IRQ.

fn irq_acknowledge(&mut self)

Acknowledge a pending IRQ. Default no-op; mappers that latch IRQ state override this.

fn mix_audio(&mut self) -> i32

Return one signed audio sample for mappers with on-cart audio (VRC6/7, MMC5, Sunsoft 5B, Namco 163, FDS). Default returns silence.

fn current_mirroring(&self) -> Mirroring

Returns the mapper’s current effective mirroring layout.

fn disk_side_count(&self) -> usize

Number of disk sides in the inserted image (0 for non-FDS mappers).

fn inserted_disk_side(&self) -> Option<usize>

The currently inserted disk side index, or None when ejected (or for non-FDS mappers).

fn set_disk_side(&mut self, side: Option<usize>)

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 enable_fds_trace(&mut self)

Start recording the diagnostic FDS read-stream trace (off by default; observation-only). No-op for non-FDS mappers. See crate::FdsTraceRec.

fn take_fds_trace(&mut self) -> Vec<FdsTraceRec>

Drain the accumulated FDS read-stream trace records (empty for non-FDS mappers / when tracing was never enabled).

fn disk_image_bytes(&self) -> Vec<u8>

Re-serialize the (possibly-modified) disk image to its byte layout for host persistence. Returns an empty vector for non-FDS mappers.

fn disk_is_dirty(&self) -> bool

Whether the disk image has unsaved writes. Always false for non-FDS mappers.

fn clear_disk_dirty(&mut self)

Clear the disk dirty flag (a host calls this after persisting). No-op for non-FDS mappers.

fn set_disk_write_protected(&mut self, protected: bool)

Mark the inserted disk read-only (true) or writable (false). No-op for non-FDS mappers.

fn save_state(&self) -> Vec<u8>

Encode the mapper’s mutable state into a tagged save-state blob.

fn load_state(&mut self, data: &[u8]) -> Result<(), MapperError>

Decode a previously Mapper::save_state blob back into the mapper.

fn debug_info(&self) -> MapperDebugInfo

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 notify_floating_read(&mut self, _addr: u16, _value: u8)

A CPU read the mapper declined (Self::cpu_read_unmapped) has just completed, and value is what floated on the bus.

fn notify_ppu_register_write(&mut self, _addr: u16, _value: u8)

The CPU wrote value to the PPU register window ($2000-$3FFF), at the undecoded address addr.

fn nametable_unfolded(&self) -> bool

Whether PPU $3000-$3EFF is independent RAM on this cartridge rather than a mirror of $2000-$2EFF.

fn cpu_read_driven_mask(&self, _addr: u16) -> u8

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.

fn ppu_read_sprite(&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 chr_phys(&self, _addr: u16) -> Option<u32>

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_reads_are_pure(&self) -> bool

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.

fn set_mmc3_revision_override( &mut self, _revision: Option<Mmc3Revision>, ) -> bool

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 nametable_fetch(&mut self, _addr: u16) -> Option<u8>

Optionally synthesize a nametable byte for addr ($2000-$3EFF).

fn nametable_write(&mut self, _addr: u16, _value: u8) -> bool

Optionally absorb a nametable write for addr ($2000-$3EFF) directly into mapper-resident storage.

fn peek_ex_attribute(&mut self, _v: u16) -> Option<ExAttribute>

Optionally provide per-tile extended attribute + CHR-bank override for the BG tile currently being fetched.

fn bg_split_state( &mut self, _scanline_y: u16, _coarse_x: u16, ) -> Option<BgSplitState>

Optionally redirect a BG fetch group into a vertical split-screen “alt region”.

fn nametable_address(&self, addr: u16) -> u16

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.

fn notify_a12(&mut self, _level: bool)

Notify of a PPU A12 line transition. Default no-op; MMC3 / MMC5 override this for IRQ counter clocking.

fn notify_a12_at_sub_dot(&mut self, level: bool, _sub_dot: u8)

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 reset(&mut self)

The console’s RESET button (a soft reset, not a power cycle).

fn notify_frame_event(&mut self, _events: MapperFrameEvents)

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_scanline_start(&mut self)

Notify the mapper that the PPU is starting a new rendered scanline.

fn notify_vblank(&mut self)

Notify the mapper that the PPU has entered vertical blank.

fn enable_vs_dual_wram(&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 set_vs_dual_sub(&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 drain_vs_dual_wram_writes(&mut self, dst: &mut Vec<(u16, u8)>)

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).

fn take_vs_dual_wram_writes(&mut self) -> Vec<(u16, u8)>

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 apply_vs_dual_wram_write(&mut self, offset: u16, value: u8)

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 take_vs_dual_wram(&mut self) -> Option<Box<[u8]>>

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 set_vs_dual_wram(&mut self, wram: Box<[u8]>)

v2.0.0 beta.5 (Vs. DualSystem): install a shared-WRAM copy (the other half of the restore normalization). Default no-op.

fn has_hardwired_mirroring(&self) -> bool

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.

fn save_data(&self) -> &[u8]

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.

fn save_data_mut(&mut self) -> &mut [u8]

Mutable Self::save_data, for loading a save.

fn clear_save_data(&mut self)

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 nsf_song_count(&self) -> u8

Number of selectable songs (0 for a non-NSF mapper).

fn nsf_current_song(&self) -> u8

The currently-selected 0-based song (0 for a non-NSF mapper).

fn nsf_set_song(&mut self, _song: u8) -> bool

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.