Module frame 

Physical frame allocator abstraction.

MetaSlot (per-frame metadata, issue #38)

Each 4 KiB physical frame has a dedicated 64-byte MetaSlot in a separate contiguous array (initialized by init_metadata_array). Buddy free-list FreeListLink nodes, reference counts, purpose flags, meta_guard bits, a per-allocation generation counter, and an optional FrameMetaVtable live here : not in the mapped page bytes, so mappings see a pristine payload.

Revue / invariants (issue #38)

• Pas de métadonnées dans la charge utile : les liens buddy sont dans FreeListLink, jamais écrits comme « faux pointeurs » dans les 4 KiB mappés.
• generation : incrémentée uniquement par MetaSlot::note_new_allocation_epoch après un CAS réussi dans FrameAllocOptions::allocate. Ne pas utiliser MetaSlot::set_generation sauf bootstrap/tests : sinon les schémas « généalogiques » deviennent incohérents.
• meta_guard::POISONED vs frame_flags::POISONED : deux espaces (bits dédiés guard vs flags logiques). Pour marquer une frame corrompue, préférer MetaSlot::mark_poisoned qui pose les deux.
• vtable_ref / try_vtable_ref : bits 0 → défaut ; bits non alignés ou invalides → défaut (pas d’UB). Les pointeurs alignés doivent désigner une FrameMetaVtable 'static valide lorsqu’ils sont enregistrés par le noyau.
• Cache order-0 : buddy::alloc(0) peut servir depuis le cache local ; le chemin FrameAllocOptions::allocate applique quand même le CAS + epoch sur la même frame.

Modules

frame_flags

Persistent flags stored in MetaSlot / FrameMeta.

meta_guard

Guard bits stored in MetaSlot::guard (issue #38 : extensible without touching page bytes).

Structs

FrameAllocOptions

Options controlling how a physical frame is allocated.

FrameMetaVtable

Custom vtable for frame-type-specific behavior (DMA teardown, device hooks, …).

FrameRangeInclusive

Iterator over an inclusive range of physical frames

FreeListLink

Buddy free-list link storage (intrusive list nodes live in MetaSlot, not in frame bytes).

MetaSlot

64-byte cache-line metadata for one physical frame (issue #38).

PhysFrame

Physical frame (4KB aligned physical memory)

Enums

AllocError

Frame allocation errors

FramePurpose

Describes the intended purpose of an allocated frame.

Constants

FRAME_META_ALIGN

FRAME_META_LINK_NONE

FRAME_META_SIZE

META_SLOT_REFCOUNT_BYTE_OFFSET

Byte offset of MetaSlot::refcount from the start of each metadata slot (layout contract).

PAGE_SIZE

REFCOUNT_UNUSED

Sentinel refcount for a frame that is in the buddy free list.

Statics

DEFAULT_FRAME_META_VTABLE

Default vtable used when MetaSlot::vtable is 0.

Traits

FrameAllocator

Frame allocator trait

Functions

block_phys_has_poison_guard

Returns true if any page in [phys, phys + 2^order * PAGE_SIZE) has MetaSlot::is_guard_poisoned.

frame_meta_debug_snapshot

(generation, guard_bits, vtable_bits) for debugging (e.g. serial_println!).

get_meta

Get the MetaSlot for a given physical frame (same as get_meta_slot).

get_meta_slot

Preferred name matching the frame metadata design (issue #38).

init_metadata_array

Initialize the global metadata array for all physical frames.

invoke_vtable_on_last_ref

Invokes on_last_ref from the frame vtable, if any (last refcount drop).

invoke_vtable_on_unmap

Invokes on_unmap from the frame vtable, if any (issue #38 : unmap / release path).

meta_generation_matches

Returns true if MetaSlot::generation matches expected for phys (epoch check for use-after-free guards).

metadata_size_for

The metadata array size for ram_size bytes, rounded up to the nearest page since each frame has a dedicated metadata entry. @param ram_size Total RAM size to be covered by the metadata (in bytes).

Type Aliases

FrameMeta

Backwards-compatible name for MetaSlot.