gb_bank/model/

mod.rs

//! Compile-time-safe ROM bank switching for the Game Boy.
//!
//! Game Boy cartridges larger than 32 KiB can only map one 16 KiB **ROM bank**
//! at a time into the `0x4000..0x8000` window; code or data in any other bank is
//! simply not addressable until that bank is switched in. Getting this wrong
//! (holding a pointer into a bank that is no longer mapped) is a classic source
//! of corruption. This crate moves the check to compile time.
//!
//! The model is borrowed from [GhostCell]: the *permission* is separated from
//! the *data*, and a brand type ties them together.
//!
//! - A [`Bank<G>`] is a zero-sized token: a witness that group `G`'s bank is
//!   currently mapped.
//! - A [`Far<T, G>`] is a pointer to a `T` living in group `G`'s bank. It cannot
//!   be read without a [`Bank<G>`](Bank).
//! - [`scope`] switches into a bank, lends you the token for the duration of a
//!   closure, then restores the previous bank. Because the token is borrowed
//!   `&mut` across the switch, a live reference into a bank can never outlive a
//!   switch away from it; the borrow checker rejects it.
//!
//! For dynamic dispatch across banks chosen at runtime, [`DynFar<T>`] erases the
//! group to a runtime bank number, and [`Warp`] is a deferred banked call: the
//! analog of a [`Future`], produced by a banked function and executed with
//! [`Warp::drive`].
//!
//! [GhostCell]: https://plv.mpi-sws.org/rustbelt/ghostcell/
//!
//! # Examples
//!
//! ```ignore
//! use gb_bank::*;
//!
//! // A bank group. (Normally generated by the `#[bank]` macro; shown raw here.)
//! struct Sound;
//! impl Group for Sound {
//!     const FIXED: bool = false;
//!     fn bank() -> BankNumber { BankNumber::new(2) }
//! }
//!
//! fn main_loop(anchor: Anchor, bank: &mut Bank<GroupZero>) {
//!     // Enter Sound's bank for a block; `b` witnesses that it is mapped.
//!     scope(anchor, bank, |b: &mut Bank<Sound>| {
//!         let tempo = *b.local(&TEMPO);   // read banked data, no extra switch
//!         // ... use `tempo` while still inside Sound's bank ...
//!     });
//!     // Sound's bank is restored to the caller's on the way out.
//! }
//! ```
//!
//! # Panics, unwinding, and interrupts
//!
//! The bank restore in [`scope`] (and the [`Far`] call / borrow paths) runs *after*
//! the closure returns, so an unwinding panic would skip it and leave the wrong
//! bank mapped. This is sound on the Game Boy because the target aborts on panic
//! (there is no unwinder), so a panic never resumes into a stale-bank token. These
//! types are not designed to be unwind-safe on a hosted, unwinding target.
//!
//! The safety model also assumes that nothing changes the mapped bank *behind the
//! token's back*. An interrupt handler that switches banks (e.g. to read banked
//! data) must save [`current_bank`] on entry and restore it before returning, so the
//! interrupted code resumes with the bank its live token still claims is mapped. An
//! ISR that is not bank-transparent breaks the invariant, just like a raw
//! [`switch_bank`] that is not paired with a matching restore. Under
//! `gb_wide_bank="mbc5"` a handler must not switch banks at all; see
//! [`switch_bank`].


use core::{any::TypeId, marker::PhantomData};

mod far;
pub(crate) mod warp;

pub use far::{DynFar, Far, FarCall, FarWith};
pub use warp::{Warp, BankSafe};

// ===== Low-level bank switch =====

/// The integer a [`BankNumber`] is stored in: one byte, or two under
/// `gb_wide_bank="mbc5"`. Public only so the `bank::module!` marker can name it.
#[doc(hidden)]
#[cfg(not(gb_wide_bank = "mbc5"))]
pub type BankRepr = u8;
#[doc(hidden)]
#[cfg(gb_wide_bank = "mbc5")]
pub type BankRepr = u16;

/// A ROM bank number, held as a `u8` or, under `gb_wide_bank="mbc5"`, a `u16`.
///
/// It is a type rather than a plain integer so that the storage width stays out of
/// every signature: how wide a bank number is, and how selecting one reaches the
/// cartridge, is a property of the build. `cargo-gb` derives it from `wide_banks`
/// in `header.toml` and passes `--cfg gb_wide_bank`; [`MAX`](BankNumber::MAX) is
/// all that changes between modes.
///
/// | `gb_wide_bank` | [`MAX`](BankNumber::MAX) | Bank register writes |
/// |---|---|---|
/// | unset | 255 | `0x2000` |
/// | `"mbc1"` | 127 | `0x2000` (5 bits), `0x4000` (2 bits) |
/// | `"mbc5"` | 511 | `0x3000` (bit 8), `0x2000` (low byte) |
///
/// This is the widest number the *build* can carry. The cartridge's own limit is
/// tighter and `gb-bank-pack` enforces it at link time.
///
/// # Wide banking and GBDK
///
/// GBDK reaches the bank register through its own one-byte shadow, exported here
/// as `_current_bank`, and writes only `0x2000`. `"mbc1"` keeps both, so linking
/// `gbdk-sys` still works; the parts of GBDK that read the shadow (its far
/// pointers, banked-call trampoline, and crash handler) would misread a bank above
/// 31, and none of them are reachable from Rust. `"mbc5"` has no one-byte shadow to
/// export, so a program linking `gbdk-sys` fails to link, and no interrupt handler
/// may switch banks (see [`switch_bank`]).
#[repr(transparent)]
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct BankNumber(BankRepr);

impl BankNumber {
    /// The highest bank number this build can represent.
    #[cfg(not(any(gb_wide_bank = "mbc1", gb_wide_bank = "mbc5")))]
    pub const MAX: u16 = 255;
    /// The highest bank number this build can represent.
    #[cfg(gb_wide_bank = "mbc1")]
    pub const MAX: u16 = 127;
    /// The highest bank number this build can represent.
    #[cfg(gb_wide_bank = "mbc5")]
    pub const MAX: u16 = 511;

    /// Name a bank, rejecting one this build cannot represent.
    ///
    /// In a `const` context an out-of-range number is a compile error.
    #[inline(always)]
    pub const fn new(n: u16) -> Self {
        assert!(n <= Self::MAX, "bank number is wider than this build carries");
        BankNumber(n as BankRepr)
    }

    /// Name a bank without the range check.
    ///
    /// # Safety
    ///
    /// `n` must be no greater than [`MAX`](BankNumber::MAX); a wider number is
    /// silently truncated and selects the wrong bank.
    #[doc(hidden)]
    #[inline(always)]
    pub const unsafe fn new_unchecked(n: u16) -> Self {
        BankNumber(n as BankRepr)
    }

    /// The bank number, for a [`Mapper`] writing it to the cartridge.
    #[inline(always)]
    pub const fn get(self) -> u16 {
        self.0 as u16
    }
}

// The software bank shadow. The MBC bank register is write-only, so the mapped
// bank is tracked here: High RAM cells read and written with the immediate `ldh`
// form through gb-hram. The runtime zero-initialises HRAM at reset (as gb-hram
// requires), so it starts at 0.
#[cfg(not(gb_wide_bank = "mbc5"))]
mod shadow {
    use super::BankNumber;
    use gb_hram::prelude::*;

    // `as "_current_bank"` exports the storage as the `__current_bank` symbol that
    // GBDK's C runtime also references (the target adds the leading underscore).
    gb_hram::hram! {
        static CURRENT_BANK as "_current_bank": HramAtomicCell<u8>;
    }

    #[inline(always)]
    pub fn set(bank: BankNumber) {
        CURRENT_BANK.set(bank.get() as u8);
    }

    #[inline(always)]
    pub fn get() -> BankNumber {
        unsafe { BankNumber::new_unchecked(CURRENT_BANK.get() as u16) }
    }
}

#[cfg(gb_wide_bank = "mbc5")]
mod shadow {
    use super::BankNumber;
    use gb_hram::prelude::*;

    // Two one-byte cells rather than one two-byte cell: each access stays a single
    // `ldh`, and no interrupt handler may switch banks in this mode, so nothing
    // observes the pair half updated. There is no `_current_bank` export because a
    // one-byte symbol cannot describe a nine-bit bank.
    gb_hram::hram! {
        static CURRENT_BANK_LO: HramAtomicCell<u8>;
        static CURRENT_BANK_HI: HramAtomicCell<u8>;
    }

    #[inline(always)]
    pub fn set(bank: BankNumber) {
        CURRENT_BANK_LO.set(bank.get() as u8);
        CURRENT_BANK_HI.set((bank.get() >> 8) as u8);
    }

    #[inline(always)]
    pub fn get() -> BankNumber {
        let n = CURRENT_BANK_LO.get() as u16 | (CURRENT_BANK_HI.get() as u16) << 8;
        unsafe { BankNumber::new_unchecked(n) }
    }
}

/// How a cartridge maps a bank into `0x4000..0x8000`.
///
/// A program on a stock cartridge never touches this: `header.toml` picks the
/// built-in that matches.
///
/// The controllers differ only in which registers a bank number is spread across,
/// so that is all this covers. A custom cartridge implements it and names the
/// implementation with [`set_mapper!`](crate::set_mapper).
///
/// # Safety
///
/// [`select`](Mapper::select) must leave bank `bank` mapped at `0x4000` and change
/// nothing else the program can observe.
pub unsafe trait Mapper {
    /// Map `bank` into `0x4000..0x8000`.
    ///
    /// # Safety
    ///
    /// The cartridge must have that bank.
    unsafe fn select(bank: BankNumber);
}

/// One register at `0x2000` takes the whole number: MBC1, MBC2 and MBC3, and MBC5
/// below bank 256.
#[doc(hidden)]
pub struct MbcN;

unsafe impl Mapper for MbcN {
    #[inline(always)]
    unsafe fn select(bank: BankNumber) {
        unsafe { core::ptr::write_volatile(0x2000 as *mut u8, bank.get() as u8) };
    }
}

/// MBC1 above bank 31: five bits at `0x2000` and two more at `0x4000`.
///
/// Those two extend the ROM bank only in banking mode 0, which is the power-on
/// default, so a program that selects mode 1 for RAM banking cannot reach bank 32
/// and up.
#[doc(hidden)]
pub struct Mbc1Wide;

unsafe impl Mapper for Mbc1Wide {
    #[inline(always)]
    unsafe fn select(bank: BankNumber) {
        let n = bank.get();
        unsafe {
            core::ptr::write_volatile(0x4000 as *mut u8, ((n >> 5) & 0x03) as u8);
            core::ptr::write_volatile(0x2000 as *mut u8, (n & 0x1F) as u8);
        }
    }
}

/// MBC5 above bank 255: the ninth bit lives in its own register at `0x3000`.
#[doc(hidden)]
pub struct Mbc5Wide;

unsafe impl Mapper for Mbc5Wide {
    #[inline(always)]
    unsafe fn select(bank: BankNumber) {
        let n = bank.get();
        unsafe {
            core::ptr::write_volatile(0x3000 as *mut u8, (n >> 8) as u8);
            core::ptr::write_volatile(0x2000 as *mut u8, n as u8);
        }
    }
}

/// Name the [`Mapper`] this program's cartridge uses.
///
/// Only a custom cartridge needs this; a stock one is picked from `header.toml`.
///
/// Write it once, anywhere in the program, and build with `--cfg gb_custom_mapper`
/// so that `gb-bank` does not also name one.
///
/// ```ignore
/// struct MyCart;
///
/// unsafe impl gb_bank::Mapper for MyCart {
///     unsafe fn select(bank: gb_bank::BankNumber) {
///         unsafe { core::ptr::write_volatile(0x2100 as *mut u8, bank.get() as u8) };
///     }
/// }
///
/// gb_bank::set_mapper!(MyCart);
/// ```
#[macro_export]
macro_rules! set_mapper {
    ($mapper:ty) => {
        const _: () = {
            #[unsafe(no_mangle)]
            unsafe extern "Rust" fn __gb_bank_select(bank: $crate::BankNumber) {
                unsafe { <$mapper as $crate::Mapper>::select(bank) }
            }
        };
    };
}

unsafe extern "Rust" {
    fn __gb_bank_select(bank: BankNumber);
}

// A cartridge with its own hardware sets `gb_custom_mapper` and names the
// implementation itself; without it the built-in one for the cartridge is used.
#[cfg(not(gb_custom_mapper))]
mod builtin {
    #[cfg(not(any(gb_wide_bank = "mbc1", gb_wide_bank = "mbc5")))]
    crate::set_mapper!(super::MbcN);
    #[cfg(gb_wide_bank = "mbc1")]
    crate::set_mapper!(super::Mbc1Wide);
    #[cfg(gb_wide_bank = "mbc5")]
    crate::set_mapper!(super::Mbc5Wide);
}

/// Switch the active ROM bank.
///
/// Writes the cartridge's bank register (see [`BankNumber`] for which, and how many)
/// and the software bank shadow that interrupt handlers rely on to save and
/// restore the mapped bank.
///
/// Prefer the safe [`scope`] / [`Far`] API; this is the raw primitive for hand
/// rolled control. After calling it, use [`Bank::assume`] to mint a matching
/// token.
///
/// A cartridge with no switchable window has nothing to write, so this compiles
/// to nothing.
///
/// # Safety
///
/// `bank` must be a valid bank for the cartridge's MBC, and the caller is
/// responsible for restoring the previous bank and for any pointers that become
/// invalid across the switch.
///
/// MBC1, MBC2, and MBC3 read a written `0` as `1`, so `switch_bank(BankNumber::new(0))`
/// maps bank 1 there while the shadow records 0, and an interrupt would restore the
/// wrong bank. Only MBC5 maps bank 0 into the window.
///
/// Under `gb_wide_bank="mbc5"` the shadow spans two cells, so an interrupt landing
/// between the two writes would afterwards read a bank that was never mapped. An
/// interrupt handler must not call this in that mode, which also rules out `far!`
/// and [`DynFar`] there, since those restore through [`current_bank`].
// With nothing left in the body on a flat ROM, the call would be all that remains.
#[cfg_attr(not(gb_flat_rom), inline(never))]
#[cfg_attr(gb_flat_rom, inline(always))]
pub unsafe fn switch_bank(bank: BankNumber) {
    if !FLAT_ROM {
        shadow::set(bank);
        unsafe { __gb_bank_select(bank) };
    }
}

/// Read the currently mapped bank from the software shadow.
///
/// The MBC register is write-only, so the active bank cannot be read from
/// hardware; this returns the shadow maintained by [`switch_bank`]. Intended for
/// interrupt save/restore; the normal call path restores via the caller's group
/// type and never needs it.
///
/// On a cartridge with no switchable window this is always bank 0, and no shadow
/// is kept.
#[inline]
pub fn current_bank() -> BankNumber {
    if FLAT_ROM {
        BankNumber::new(0)
    } else {
        shadow::get()
    }
}

// ===== Group brands =====

/// The compile-time identity of a bank group.
///
/// The implementing type *is* the brand: two values share a group iff they share
/// the type parameter `G`, checked entirely at compile time. The runtime
/// [`bank()`](Group::bank) number is only consulted for the actual hardware
/// switch.
///
/// Groups are normally generated by the `#[bank]` macro, one per banked module.
pub trait Group: 'static {
    /// Whether this group is permanently mapped, so switching to it is a no-op.
    ///
    /// [`GroupZero`] always is, and so is every group on a cartridge with no
    /// switchable window.
    const FIXED: bool;

    /// The physical bank number, resolved at link time by gb-bank-pack.
    fn bank() -> BankNumber;
}

/// Whether the cartridge has no switchable window, so every group sits in bank 0.
///
/// `cargo-gb` sets this from `cartridge_type` in `header.toml`. `bank::module!`
/// reads it through this const rather than the cfg directly, so a crate using the
/// macro does not have to declare the cfg itself.
#[doc(hidden)]
pub const FLAT_ROM: bool = cfg!(gb_flat_rom);

/// Bank 0: the always-mapped region.
///
/// Switching to or from a [`FIXED`](Group::FIXED) group is elided, so calls and
/// data accesses anchored at `GroupZero` never touch the MBC register.
pub struct GroupZero;

impl Group for GroupZero {
    const FIXED: bool = true;
    #[inline(always)]
    fn bank() -> BankNumber {
        BankNumber::new(0)
    }
}

// ===== Bank token + scope =====

/// A witness that group `G`'s bank is currently mapped.
///
/// This is the GhostCell-style permission token: a zero-sized value whose type
/// `G` is the brand. Borrowing it shared ([`local`](Far::local)) yields references
/// into the bank; borrowing it `&mut` (a switch via [`scope`]) is what changes
/// the mapping. Because you cannot do both at once, a reference obtained from
/// `local` can never be live across a switch; the conflict is a borrow error.
///
/// The token is `!Send` and only mintable through [`assume`](Bank::assume) (or,
/// safely, the closure argument of [`scope`]).
///
/// # Examples
///
/// ```ignore
/// fn play(b: &mut Bank<Sound>) {
///     let note = *b.local(&MELODY);   // `b` proves Sound is mapped
///     // ...
/// }
/// ```
///
/// The token is `!Send` and `!Sync`: a "this bank is mapped" proof cannot cross
/// threads, nor be parked in a `static` and read back later.
///
/// ```compile_fail
/// # use gb_bank::*;
/// fn assert_send<T: Send>() {}
/// assert_send::<Bank<GroupZero>>(); // ERROR: Bank is !Send
/// ```
///
/// ```compile_fail
/// # use gb_bank::*;
/// fn assert_sync<T: Sync>() {}
/// assert_sync::<Bank<GroupZero>>(); // ERROR: Bank is !Sync
/// ```
pub struct Bank<G: Group> {
    _bank: PhantomData<G>,
}

impl<G: Group> !Send for Bank<G> {}
impl<G: Group> !Sync for Bank<G> {}

impl<G: Group> Bank<G> {
    /// Mint a token, asserting that group `G`'s bank is already mapped.
    ///
    /// This is the escape hatch for hand-rolled control: after a raw
    /// [`switch_bank`] or inline asm, call `assume` to re-enter the safe
    /// [`local`](Far::local) / [`scope`] API.
    ///
    /// # Safety
    ///
    /// Group `G`'s bank must actually be mapped at the call site; otherwise every
    /// subsequent `local`/call through this token reads the wrong bank.
    #[inline(always)]
    pub const unsafe fn assume() -> Self {
        Bank { _bank: PhantomData }
    }
}

/// Proof that the holder runs in bank 0 (the always-mapped region), and
/// so may run a closure across a bank switch via [`scope`] / [`there`](FarWith::there).
///
/// Those operations lend a closure across a switch; the closure's *code* must stay
/// mapped while it runs, which only holds for code in bank 0. An `Anchor` is that
/// guarantee, as a zero-sized [`Copy`] capability. The `#[bank::main]` and
/// `#[bank::zero]` macros mint one at the top of every body (their code is
/// in bank 0); a `#[bank]` function gets none, so it cannot reach `scope` / `there`,
/// which would otherwise run a banked closure the switch unmaps.
///
/// Being `Copy`, it threads into nested scopes without borrow friction.
#[derive(Clone, Copy)]
pub struct Anchor(());

// An `Anchor` witnesses that the *current* code is in bank 0, so carrying one into a
// banked call would falsify it: the callee would hold a bank-0 capability while
// running from a switchable bank.
impl !BankSafe for Anchor {}

impl Anchor {
    /// Assert that the calling code runs in bank 0.
    ///
    /// # Safety
    ///
    /// The caller must physically reside in bank 0 (the always-mapped region): a
    /// `#[bank::main]` / `#[bank::zero]` body, or a plain `fn` the linker keeps
    /// in bank 0. A `#[bank]` function is *not* in bank 0 and must never mint one.
    ///
    /// An `Anchor` must also not be moved into `#[bank]` code: it witnesses that the
    /// *current* code is in bank 0, which carrying it into a banked function would
    /// falsify. (Safe code cannot do this: the macro-minted `Anchor` is hygienic and
    /// there is no other safe constructor.)
    #[inline(always)]
    pub const unsafe fn assume() -> Self {
        Anchor(())
    }
}

/// Enter group `G`'s bank for the duration of `f`, then restore the caller (`C`).
///
/// This is the safe heart of the crate. It switches to `G`, hands `f` a fresh
/// [`Bank<G>`] token, runs it, and switches back to `C`. Threading the caller's
/// `&mut Bank<C>` is what makes the cross-bank footgun a compile error: a
/// reference borrowed from one token cannot survive a nested [`scope`] that needs
/// the same token `&mut`.
///
/// The switch is elided entirely when `G` is [`FIXED`](Group::FIXED) or `C == G`
/// (same group, folded at compile time), so same-bank work costs nothing.
///
/// # Examples
///
/// ```ignore
/// fn run(anchor: Anchor, bank: &mut Bank<GroupZero>) {
///     let first = scope(anchor, bank, |b: &mut Bank<Sound>| *b.local(&MELODY).first().unwrap());
///     // back in the caller's bank here
/// }
/// ```
///
/// The borrow checker stops a banked reference from escaping the switch:
///
/// ```compile_fail
/// # use gb_bank::*;
/// # struct G;
/// # impl Group for G {
/// #     const FIXED: bool = false;
/// #     fn bank() -> BankNumber { BankNumber::new(1) }
/// # }
/// fn leak<'a>(anchor: Anchor, bank: &mut Bank<GroupZero>, data: &'a Far<u8, G>) -> &'a u8 {
///     scope(anchor, bank, |g| g.local(data)) // ERROR: the ref borrows the inner token
/// }
/// ```
#[inline]
pub fn scope<C: Group, G: Group, R: BankSafe>(
    _anchor: Anchor,
    outer: &mut Bank<C>,
    f: impl FnOnce(&mut Bank<G>) -> R,
) -> R {
    switch_run(outer, f)
}

/// The bank-switch primitive behind [`scope`] and the one-shot [`Warp::drive`] /
/// [`FarCall::invoke`]: switch to `G`, run `f`, restore `C`, eliding when `G` is
/// [`FIXED`](Group::FIXED) or `C == G`.
///
/// Unlike [`scope`] it takes no [`Anchor`], so it stays crate-internal: its callers
/// either thread an `Anchor` through (`scope` / [`there`](FarWith::there), whose `f`
/// is a user closure) or run no user closure at all (`drive` / `invoke` call the
/// banked function themselves, taking [`switch_run_far`] when the caller is banked).
#[inline]
pub(crate) fn switch_run<C: Group, G: Group, R>(
    _outer: &mut Bank<C>,
    f: impl FnOnce(&mut Bank<G>) -> R,
) -> R {
    if G::FIXED || const { TypeId::of::<C>() == TypeId::of::<G>() } {
        let mut b = unsafe { Bank::<G>::assume() };
        f(&mut b)
    } else {
        unsafe { switch_bank(G::bank()) };
        let mut b = unsafe { Bank::<G>::assume() };
        let r = f(&mut b);
        if !C::FIXED {
            unsafe { switch_bank(C::bank()) };
        }
        r
    }
}

/// [`switch_run`] for a caller that is itself banked, whose code leaves the window
/// during the call: `#[inline(never)]` keeps the switch in a bank-0 trampoline.
#[inline(never)]
pub(crate) fn switch_run_far<C: Group, G: Group, R>(
    outer: &mut Bank<C>,
    f: impl FnOnce(&mut Bank<G>) -> R,
) -> R {
    switch_run(outer, f)
}