Struct FrameAllocOptions 

pub struct FrameAllocOptions { /* private fields */ }

Options controlling how a physical frame is allocated.

The default configuration (FrameAllocOptions::new()) produces a zeroed frame. Callers that need a non-zeroed frame (e.g. DMA buffers that are immediately filled by hardware, or frames that will be fully overwritten before any read) must explicitly call .zeroed(false).

Example

// Allocate a zeroed page-table frame (the safe default).
let frame = FrameAllocOptions::new()
    .purpose(FramePurpose::PageTable)
    .allocate(token)?;

// Allocate a user-data frame without zeroing (caller guarantees it will
// be fully overwritten, e.g. by an ELF segment load).
let frame = FrameAllocOptions::new()
    .zeroed(false)
    .purpose(FramePurpose::UserData)
    .allocate(token)?;

Implementations

impl FrameAllocOptions

pub fn new() -> Self

Creates allocation options with safe defaults:

• zeroed = true
• purpose = KernelData

pub fn zeroed(self, zeroed: bool) -> Self

Override the zero-initialisation policy.

Safety contract (enforced by convention, not the type system)

If zeroed is set to false, the caller MUST fully overwrite every byte of the frame before allowing any other CPU or subsystem to read it. Violating this rule is a memory-safety hazard: stale bytes in an intermediate page-table node cause the CPU to follow arbitrary PTEs.

pub fn purpose(self, p: FramePurpose) -> Self

Set the intended purpose of the frame.

PageTable purpose forces zeroing even if .zeroed(false) was called.

pub fn allocate(self, token: &IrqDisabledToken) -> Result<PhysFrame, AllocError>

Allocate a single 4 KiB frame according to the configured options.

The allocation path is:

1. Ask the buddy allocator for an order-0 frame (exclusive ownership is guaranteed by the buddy’s own bitmap + free-list discipline).
2. Optionally zero the 4 KiB frame contents via the HHDM.
3. Stamp FrameMeta::flags with the purpose flags using Release ordering.
4. Store refcount = 1 with Release ordering so any later Acquire load of the refcount observes the fully-initialised metadata and (if zeroed) zeroed content.

Sentinel handoff: CAS(REFCOUNT_UNUSED -> 1)

buddy.rs maintains the invariant that every frame on the free list has refcount == REFCOUNT_UNUSED. mark_block_allocated() leaves this sentinel intact, so the frame arriving here still carries REFCOUNT_UNUSED.

The CAS atomically claims the frame and acts as a fail-fast corruption check: if the same frame appears twice in the buddy free list (double-free or metadata corruption), the second allocation attempt will observe a refcount of 1 (set by the first allocation) and panic immediately rather than silently aliasing memory.

Trait Implementations

impl Default for FrameAllocOptions

fn default() -> Self

Returns the “default value” for a type.