gb_bank/model/

far.rs

//! Far pointers and the operations on them.
//!
//! A [`Far<T, G>`] is a pointer into a *statically known* bank (group `G`); an
//! [`DynFar<T>`] is the same thing with the group erased to a runtime number, for
//! heterogeneous dynamic dispatch. The [`FarCall`] and [`FarWith`] traits unify
//! the two so that calling a function or borrowing data reads the same whichever
//! you hold.

use core::marker::{PhantomData, Tuple};

use super::{
    scope, switch_bank, switch_run, switch_run_far, Anchor, Bank, BankNumber, BankSafe, Group,
    GroupZero,
};

// ===== Far: static-bank far pointer =====

/// A pointer to a `T` living in group `G`'s bank.
///
/// `Far` is itself a plain value (just an address plus the group brand), so
/// it is [`Copy`] and may be stored and passed around freely. What it points at,
/// however, is only addressable when `G`'s bank is mapped, so it cannot be
/// dereferenced without a [`Bank<G>`] token. `T` may be data (e.g. `[u8; N]`) or
/// a function pointer (`fn(..) -> R`).
///
/// Use [`local`](Far::local) / [`there`](FarWith::there) for data and
/// [`invoke`](FarCall::invoke) for functions, or [`erase`](Far::erase) to drop the
/// static group for dynamic dispatch.
///
/// # Examples
///
/// ```ignore
/// // Generated by `#[bank] static TILES: [u8; 256] = ..;`
/// // const TILES: Far<[u8; 256], Sprites> = ..;
///
/// fn first_tile(anchor: Anchor, bank: &mut Bank<GroupZero>, tiles: &Far<[u8; 256], Sprites>) -> u8 {
///     tiles.there(anchor, bank, |t| t[0])   // switch into Sprites, read, switch back
/// }
/// ```
pub struct Far<T: ?Sized, G: Group> {
    pub(crate) ptr: *const T,
    _g: PhantomData<G>,
}

unsafe impl<T: ?Sized, G: Group> Sync for Far<T, G> {}

impl<T: ?Sized, G: Group> Far<T, G> {
    /// Construct a far pointer. Normally emitted by the `#[bank]` macro.
    ///
    /// # Safety
    ///
    /// For data, `ptr` must be the address of the `T` in group `G`'s bank window.
    /// For a function `T = fn(..)`, `ptr` is the function's own address (e.g.
    /// `real_fn as *const _`), which [`invoke`](FarCall::invoke) reinterprets as the
    /// fn pointer.
    #[doc(hidden)]
    #[inline(always)]
    pub const unsafe fn new(ptr: *const T) -> Self {
        Far {
            ptr,
            _g: PhantomData,
        }
    }

    /// Erase the static group into a runtime bank number, yielding an [`DynFar`].
    ///
    /// Use this to store far pointers of *different* groups together (a dispatch
    /// table) or to pass one where the group is not known at compile time.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let table: [DynFar<fn(u8)>; 2] = [a.erase(), b.erase()];
    /// ```
    #[inline]
    pub fn erase(self) -> DynFar<T> {
        unsafe { DynFar::new(self.ptr, G::bank()) }
    }

    /// Read the data in place, given a token already in its bank: no switch.
    ///
    /// The same-bank read. `here` proves `G` is mapped, so the data is addressable;
    /// the reference borrows `here`, and a switch needs the token `&mut`, so it
    /// cannot be held across a switch away from the bank. (The cross-bank borrow is
    /// [`there`](FarWith::there).) A token of the wrong group is a type error:
    ///
    /// ```compile_fail
    /// # use gb_bank::*;
    /// # struct G1; struct G2;
    /// # impl Group for G1 {
    /// #     const FIXED: bool = false;
    /// #     fn bank() -> BankNumber { BankNumber::new(1) }
    /// # }
    /// # impl Group for G2 {
    /// #     const FIXED: bool = false;
    /// #     fn bank() -> BankNumber { BankNumber::new(2) }
    /// # }
    /// fn wrong(b: &Bank<G1>, far: &Far<u8, G2>) -> u8 {
    ///     *far.local(b) // ERROR: a G2 far needs a G2 token, not G1
    /// }
    /// ```
    #[inline(always)]
    pub fn local<'a>(&self, _here: &'a Bank<G>) -> &'a T {
        unsafe { &*self.ptr }
    }
}

impl<T: ?Sized> Far<T, GroupZero> {
    /// A far pointer to bank 0 data, built *safely*.
    ///
    /// Safe because [`GroupZero`] is always mapped: the pointer is always valid,
    /// so there is no bank-mapping precondition to uphold. Use it to hand bank-0
    /// data to code written in terms of [`Far`] / [`DynFar`], e.g. a dispatch table
    /// mixing data from several banks.
    ///
    /// `data` must genuinely live in bank 0: an ordinary
    /// `static` or `const`, not a `#[bank]` static. Plain statics always qualify
    /// (the linker keeps them in bank 0); only data deliberately placed in a
    /// switchable bank would not, and the safe API gives no `&'static` reference to
    /// such data anyway.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// static PALETTE: [u8; 4] = [0, 1, 2, 3];
    /// let far: Far<[u8; 4], GroupZero> = Far::resident(&PALETTE);
    /// ```
    #[inline(always)]
    pub const fn resident(data: &'static T) -> Self {
        Far { ptr: data, _g: PhantomData }
    }
}

impl<T: ?Sized, G: Group> Copy for Far<T, G> {}
impl<T: ?Sized, G: Group> Clone for Far<T, G> {
    #[inline(always)]
    fn clone(&self) -> Self {
        *self
    }
}

// ===== DynFar: runtime-bank (erased) far pointer =====

/// A far pointer whose bank is known only at runtime: a group-erased [`Far`].
///
/// `DynFar` is the no-alloc, vtable-free type erasure of [`Far`]: the group type
/// becomes a [`BankNumber`] stored inline, so far pointers of *different* banks
/// share one type and can live in the same collection. Every access switches to the
/// stored bank (there is no compile-time group to elide it against).
///
/// Obtain one with [`Far::erase`].
///
/// # Examples
///
/// ```ignore
/// fn run_each(bank: &mut Bank<GroupZero>, behaviours: &[DynFar<fn(u8)>], state: u8) {
///     for b in behaviours {
///         b.invoke(bank, (state,));   // switch to each one's bank, run, restore
///     }
/// }
/// ```
pub struct DynFar<T: ?Sized> {
    ptr: *const T,
    bank: BankNumber,
}

unsafe impl<T: ?Sized> Sync for DynFar<T> {}

impl<T: ?Sized> DynFar<T> {
    /// Construct an erased far pointer from a raw address and bank number.
    ///
    /// # Safety
    ///
    /// `ptr` must be valid when `bank` is mapped. Prefer [`Far::erase`], which
    /// fills in the bank from the group.
    #[doc(hidden)]
    #[inline(always)]
    pub const unsafe fn new(ptr: *const T, bank: BankNumber) -> Self {
        DynFar { ptr, bank }
    }
}

impl<T: ?Sized> Copy for DynFar<T> {}
impl<T: ?Sized> Clone for DynFar<T> {
    #[inline(always)]
    fn clone(&self) -> Self {
        *self
    }
}

/// A far pointer that can be *called* across a bank boundary.
///
/// Implemented by [`Far`] and [`DynFar`] over function pointers, this is the
/// unified call interface: [`invoke`](FarCall::invoke) switches into the target
/// bank, invokes the function with `args`, and restores the caller's bank `C`.
/// The `#[bank]` macro rewrites `recv.invoke(args)` onto it.
pub trait FarCall<Args: Tuple + BankSafe> {
    /// The function's return type.
    type Output: BankSafe;

    /// Switch into the far function's bank, call it with `args`, restore `C`.
    fn invoke<C: Group>(&self, outer: &mut Bank<C>, args: Args) -> Self::Output;
}

impl<F: Copy + Fn<Args>, G: Group, Args: Tuple + BankSafe> FarCall<Args> for Far<F, G>
where
    F::Output: BankSafe,
{
    type Output = F::Output;
    // A resident caller inlines the switch; a banked one, whose code leaves the
    // window during the call, takes the bank-0 trampoline instead.
    #[inline]
    fn invoke<C: Group>(&self, outer: &mut Bank<C>, args: Args) -> F::Output {
        let run = |_b: &mut Bank<G>| {
            // `ptr` is the function's address; reinterpret it as the fn pointer.
            let f: F = unsafe { core::mem::transmute_copy(&self.ptr) };
            f.call(args)
        };
        if C::FIXED {
            switch_run(outer, run)
        } else {
            switch_run_far(outer, run)
        }
    }
}

impl<F: Copy + Fn<Args>, Args: Tuple + BankSafe> FarCall<Args> for DynFar<F>
where
    F::Output: BankSafe,
{
    type Output = F::Output;
    // See `Far`'s impl above. The target bank is a runtime value, so this cannot go
    // through `switch_run` and carries its own trampoline.
    #[inline]
    fn invoke<C: Group>(&self, _outer: &mut Bank<C>, args: Args) -> F::Output {
        let run = || {
            let f: F = unsafe { core::mem::transmute_copy(&self.ptr) };
            f.call(args)
        };
        if C::FIXED {
            unsafe { switch_bank(self.bank) };
            run()
        } else {
            dyn_invoke_far::<C, _>(self.bank, run)
        }
    }
}

/// [`DynFar::invoke`](FarCall::invoke) for a banked caller. `C` is never
/// [`FIXED`](Group::FIXED) here, so the restore is unconditional.
#[inline(never)]
fn dyn_invoke_far<C: Group, R>(bank: BankNumber, f: impl FnOnce() -> R) -> R {
    unsafe { switch_bank(bank) };
    let r = f();
    unsafe { switch_bank(C::bank()) };
    r
}

/// Borrowing a far pointer's *data* across a bank boundary.
///
/// Switches into the data's bank, lends `&T` to `f`, then restores the caller `C`:
/// the cross-bank counterpart of [`Far::local`]. Implemented by [`Far`] (switch via
/// [`scope`], then [`local`](Far::local)) and [`DynFar`] (switch to its runtime bank).
pub trait FarWith<T: ?Sized> {
    /// Switch into the data's bank, lend `&T` to `f`, restore `C`.
    ///
    /// `anchor` proves the caller is in bank 0: `f` runs across a bank switch, so its
    /// code must stay mapped. A `#[bank]` function holds no [`Anchor`] and so cannot
    /// call this (use [`local`](Far::local) for same-bank data instead).
    fn there<C: Group, R: BankSafe>(&self, anchor: Anchor, outer: &mut Bank<C>, f: impl FnOnce(&T) -> R) -> R;
}

impl<T: ?Sized, G: Group> FarWith<T> for Far<T, G> {
    #[inline]
    fn there<C: Group, R: BankSafe>(&self, anchor: Anchor, outer: &mut Bank<C>, f: impl FnOnce(&T) -> R) -> R {
        scope(anchor, outer, |b: &mut Bank<G>| f(self.local(b)))
    }
}

impl<T: ?Sized> FarWith<T> for DynFar<T> {
    #[inline]
    fn there<C: Group, R: BankSafe>(&self, _anchor: Anchor, _outer: &mut Bank<C>, f: impl FnOnce(&T) -> R) -> R {
        unsafe { switch_bank(self.bank) };
        let r = f(unsafe { &*self.ptr });
        if !C::FIXED {
            unsafe { switch_bank(C::bank()) };
        }
        r
    }
}