Struct SummaryBuddyAllocator 

pub struct SummaryBuddyAllocator<const ORDERS: usize, P: Provenance, G: GateConfig = DefaultGates> { /* private fields */ }

A lock-free, bitmap-only buddy allocator with a two-level summary bitmap that carves its bitmap out of the managed physical memory region at init time.

ORDERS is the number of size classes: order 0 corresponds to the base frame size (base.bytes()), order ORDERS - 1 to the largest block (base.bytes() << (ORDERS - 1)).

P is the Provenance strategy. Unlike the intrusive backends, this allocator only touches the managed memory at init - to obtain a pointer to the carved bitmap - and never reaches into the frames it hands out; so P::create is called exactly once, for the bitmap, and P::destroy is never needed (the bitmap is permanent).

Implementations

impl<const ORDERS: usize, P: Provenance, G: GateConfig> SummaryBuddyAllocator<ORDERS, P, G>

pub const fn new(base_frame: PageSize) -> Self

Create a new, empty allocator with the given base frame size.

All runtime state is zeroed. Call init / init_region to finish initialisation before allocating. max_page defaults to the max block (base_frame << (ORDERS-1)), the most conservative choice; use with_max_page to shrink the boundary init rounds phys_base down to (a smaller max_page shrinks the phantom prefix).

Examples found in repository

examples/basic.rs (line 89)

static PHYS: SummaryBuddyAllocator<ORDERS, IdentityProv> = SummaryBuddyAllocator::new(BASE);

fn main() {
    // A boot memory map with holes:
    //
    // The backing pool spans the whole window; we then declare only the *usable*
    // sub-ranges. Two holes stay reserved and are never handed out:
    //
    //   [  0 .. 100)  usable   <- the buddy carves its in-pool bitmap from here
    //   [100 .. 104)  RESERVED  (kernel image)
    //   [104 .. 200)  usable
    //   [200 .. 205)  RESERVED  (MMIO window)
    //   [205 .. 256)  usable
    let pool = Region::new(SPAN_FRAMES * BASE.bytes(), MAX_BLOCK);
    let phys_base = pool.addr(); // the "physical" origin

    let frame = BASE.bytes();
    let range = |lo: usize, hi: usize| PhysRange {
        base: phys_base + lo * frame,
        len: (hi - lo) * frame,
    };
    let usable = [range(0, 100), range(104, 200), range(205, 256)];

    // SAFETY: single-threaded, called once before any allocation. `phys_base` is
    // MAX_BLOCK-aligned (Region honours the requested alignment); the bitmap host
    // range is exclusively owned and reachable through `IdentityProv::create`; the
    // usable ranges are sorted, non-overlapping, base-frame-aligned, and within
    // the span.
    unsafe { PHYS.init(phys_base, SPAN_FRAMES * frame, &usable) };

    println!("Initialised SummaryBuddy over a 1 MiB span with two reserved holes.");
    print_stats("after init", &PHYS);

    // A few allocate / deallocate cycles:
    //
    // One single base frame, then a 4-frame (order-2) contiguous block. Every
    // address is physical and aligned to the request size.
    let single = PHYS
        .allocate_physical(BASE, n(1))
        .expect("single-frame alloc");
    let block = PHYS
        .allocate_physical(BASE, n(4))
        .expect("4-frame contiguous alloc");
    println!("\nallocate_physical(1 frame)  -> {single:#x}");
    println!("allocate_physical(4 frames) -> {block:#x}");
    print_stats("with 5 frames out", &PHYS);

    // SAFETY: each address came from `allocate_physical` with the same page size
    // and count and is not used afterwards.
    unsafe {
        PHYS.deallocate_physical(BASE, n(1), single);
        PHYS.deallocate_physical(BASE, n(4), block);
    }
    println!("\nfreed both — buddies merge back.");
    print_stats("after free", &PHYS);

    // Composition: a per-CPU magazine + shared depot over a fresh SummaryBuddy:
    compose_with_depot();
}

/// Wrap a `SummaryBuddyAllocator` in a [`DepotAllocator`].
fn compose_with_depot() {
    /// Uniprocessor selector: every CPU maps to slot 0. A real kernel returns an
    /// APIC id / `TPIDR_EL1` here.
    struct OneCpu;
    impl CpuId for OneCpu {
        fn current_cpu() -> usize {
            0
        }
    }
    const SLOTS: usize = 8; // magazines (>= CPUs you want disjoint)

    // Same const-new composability: the whole stack is one `static`-able value.
    let mag: DepotAllocator<SummaryBuddyAllocator<ORDERS, IdentityProv>, OneCpu, SLOTS> =
        DepotAllocator::new(BASE, SummaryBuddyAllocator::new(BASE));

    let pool = Region::new(SPAN_FRAMES * BASE.bytes(), MAX_BLOCK);
    // SAFETY: as above; here the whole region is usable, so the single-range
    // convenience applies.
    unsafe { mag.init_region(pool.addr(), SPAN_FRAMES * BASE.bytes()) };

    println!("\n── DepotAllocator<SummaryBuddyAllocator> ──");
    let a = mag.allocate_physical(BASE, n(1)).expect("mag alloc");
    // SAFETY: `a` came from this allocator; freed once, then not reused by us.
    unsafe { mag.deallocate_physical(BASE, n(1), a) };
    let b = mag.allocate_physical(BASE, n(1)).expect("mag re-alloc");
    println!("alloc {a:#x} -> free -> alloc {b:#x}");
    assert_eq!(a, b, "the magazine should return the just-freed frame");
    println!("re-alloc returned the cached frame (no backend round-trip).");
    // SAFETY: final free of a live frame.
    unsafe { mag.deallocate_physical(BASE, n(1), b) };
}

pub const fn with_max_page(base_frame: PageSize, max_page: PageSize) -> Self

Like new but pins max_page, the largest page a caller may request. It caps allocations (ps > max_page -> InvalidPageSize) and, equivalently, sets the boundary init rounds phys_base down to - the two are the same bound. Must lie in base_frame ..= base_frame << (ORDERS-1).

Trait Implementations

impl<const ORDERS: usize, P: Provenance, G: GateConfig> PhysicalAllocator for SummaryBuddyAllocator<ORDERS, P, G>

fn allocate_physical( &self, ps: PageSize, count: NonZeroUsize, ) -> Result<usize, AllocError>

Allocate count contiguous frames of size ps.

unsafe fn deallocate_physical( &self, ps: PageSize, count: NonZeroUsize, phys: usize, )

Return count contiguous frames of size ps starting at phys.

impl<const ORDERS: usize, P: Provenance, G: GateConfig> RegionInit for SummaryBuddyAllocator<ORDERS, P, G>

unsafe fn try_init( &self, phys_base: usize, span_len: usize, usable: &[PhysRange], ) -> Result<(), InitError>

Configure metadata over [phys_base, phys_base + span_len) and mark only the usable ranges free. Holes stay reserved.

unsafe fn add_usable(&self, base: usize, len: usize)

Transition a reserved (never-freed) in-span range to free. Repeatable after try_init. base/len must satisfy the same per-range constraints as a usable entry.

unsafe fn init(&self, phys_base: usize, span_len: usize, usable: &[PhysRange])

As try_init but panic on error.

unsafe fn try_init_region( &self, phys_base: usize, len: usize, ) -> Result<(), InitError>

Convenience: initialise from a single fully-usable contiguous region [phys_base, phys_base + len).

unsafe fn init_region(&self, phys_base: usize, len: usize)

As try_init_region but panic on error.