Trait RegionInit 

pub unsafe trait RegionInit {
    // Required methods
    unsafe fn try_init(
        &self,
        phys_base: usize,
        span_len: usize,
        usable: &[PhysRange],
    ) -> Result<(), InitError>;
    unsafe fn add_usable(&self, base: usize, len: usize);

    // Provided methods
    unsafe fn init(
        &self,
        phys_base: usize,
        span_len: usize,
        usable: &[PhysRange],
    ) { ... }
    unsafe fn try_init_region(
        &self,
        phys_base: usize,
        len: usize,
    ) -> Result<(), InitError> { ... }
    unsafe fn init_region(&self, phys_base: usize, len: usize) { ... }
}

Memory-map-aware initialisation interface for physical frame allocators.

try_init configures the allocator’s metadata over the whole span and frees only the usable ranges; holes between them stay reserved (never handed out).

Contract guarantees

• On Err, the allocator is untouched - it remains in the valid empty state it had before the call, and a corrected retry is permitted.
• At most one successful call. A returned Ok(()) consumes the one-time initialisation; a returned Err(_) does not, so a caller may retry with corrected arguments after any failure.

Safety

These preconditions are unverifiable from the arguments and so remain the caller’s responsibility (violating any of them is undefined behaviour, not an InitError):

• Backends reach the managed memory through a Provenance strategy of their own, obtaining pointers for the physical addresses they are given; the caller supplies no mapping pointer. Each backend’s Provenance # Safety contract states what it requires of that mapping.
• Each usable range’s memory must be exclusively owned and not aliased while registered.
• Must be called single-threaded, and the allocator must be published to other threads with a happens-before edge (thread spawn, mutex, or a Release store / Acquire load of a ready flag) before any concurrent use.

Errors

The checkable preconditions are reported rather than assumed. See InitError for the full list; in summary try_init returns:

• InitError::AlreadyInitialized if a previous call already succeeded;
• InitError::Misaligned if phys_base is not base-frame aligned (it need not itself be usable RAM);
• InitError::InvalidSpan if span_len is zero, not a base-frame multiple, or overflows the address space;
• InitError::InvalidUsable if any usable range is empty, misaligned, out of order, overlapping, or escapes the span;
• InitError::MetadataWontFit if no usable range can host the allocator’s in-pool metadata.

An empty usable slice is permitted by this interface, but some implementations may reject it with InitError::MetadataWontFit: an allocator that keeps its metadata inside the managed pool needs enough usable RAM to host that metadata.

Required Methods

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.

On success the one-time initialisation is consumed; on failure the allocator is untouched and the call may be retried. See the trait-level documentation for the full contract, the # Errors conditions, and the # Safety preconditions.

Errors

See the trait-level # Errors documentation.

Safety

See the trait-level safety documentation.

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.

Safety

try_init must have succeeded first. [base, base + len) must be base-frame aligned, lie within the span, be currently reserved (not already free), exclusively owned, and not aliased while registered.

Provided Methods

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

As try_init but panic on error.

Safety

See the trait-level safety documentation.

Panics

Panics if try_init returns an InitError.

Examples found in repository

examples/basic.rs (line 117)

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();
}

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

Errors

See the trait-level # Errors documentation.

Safety

See the trait-level safety documentation; the whole region is usable.

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

As try_init_region but panic on error.

Safety

See the trait-level safety documentation; the whole region is usable.

Panics

Panics if initialisation returns an InitError.

Examples found in repository

examples/basic.rs (line 168)

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) };
}

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<A: RegionInit, S, const SLOTS: usize, const CAP: usize, const DEPOT_CAP: usize, I: InterruptControl> RegionInit for DepotAllocator<A, S, SLOTS, CAP, DEPOT_CAP, I>

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