Asuro/doc/src/memory/memory.heap.md

memory.heap

Bitmap-based kernel heap allocator providing kalloc, kfree, and large-allocation support.

Overview

memory.heap implements the Asuro logical memory manager (LMM). The heap is organized as a singly/doubly-linked list of 4 MiB virtual pages, each managed by a bitmap that tracks 8-byte allocation units.

Each heap page has the following layout:

Region	Offset	Size
THeapPageHeader	0x000000	24 bytes
Bitmap	0x000018	64,512 bytes (516,096 bits)
Padding	0x00FC18	1,000 bytes
Data area	0x010000	4,128,768 bytes (516,096 units × 8 bytes)

Every allocation is preceded by a 16-byte prefix: 4 bytes for the unit count, 12 bytes of padding. This ensures the returned pointer is 16-byte aligned (required for SSE 128-bit operations) and allows kfree to recover the allocation size without a separate metadata structure.

Allocations larger than a single heap page's capacity are handled by klalloc, which maps contiguous virtual pages and stores a magic sentinel ($FFFFFFFE) in the header so kfree can identify them and call klfree instead of the normal bitmap path.

kalloc and kfree disable interrupts for the duration of their critical sections using a stack-balanced pushfd/cli/pop sequence and restore the interrupt flag via restore_if on all exit paths.

Dependencies

• arch.x86.memory.physical
• arch.x86.memory.virtual
• io.syslog
• debug.tracer
• core.util, arch.x86.util
• core.panic

Boot Registration

Registered with boot.mgr as memory.heap, depending on glob arch.*.memory.* (waits for all matching entries).

Constants

Constant	Value	Description
ALLOC_UNIT	8	Bytes per allocation unit
DATA_OFFSET	$10000 (64 KiB)	Offset from page base to data area
PAGE_SIZE_LMM	$400000 (4 MiB)	Size of each heap virtual page
TOTAL_UNITS	516096	Allocation units per page ((PAGE_SIZE_LMM - DATA_OFFSET) / ALLOC_UNIT)
BITMAP_DWORDS	16128	32-bit words required to hold the bitmap
SIZE_PREFIX	16	Bytes prepended to every normal allocation
LARGE_ALLOC_MAGIC	$FFFFFFFE	Sentinel written at offset +4 in klalloc headers
GUARD_MAGIC	$DEADBEEF	Guard sentinel for overrun detection (debug builds only)

Types

THeapPageHeader / PHeapPageHeader

THeapPageHeader = packed record
    NextPage   : PHeapPageHeader;
    PrevPage   : PHeapPageHeader;
    FreeUnits  : uint32;
    NextFree   : uint32;
    TotalUnits : uint32;
    Reserved   : uint32;
end;

Located at the base address of each heap virtual page. NextFree is a roving hint that tracks the first bitmap index likely to contain free units, reducing average scan time for sequential allocations.

Functions and Procedures

init

procedure init;

Allocates the first heap page via new_heap_page, sets Root_Page and Search_Page to it. Panics if the root page cannot be allocated.

kalloc

function kalloc(size: uint32): void;

Allocates size bytes from the heap. Returns a 16-byte-aligned pointer. Returns nil for zero-size requests. Delegates to klalloc for requests too large for a single page. Searches pages starting from Search_Page using the NextFree roving hint, allocating a new page if no existing page can satisfy the request. Calls core.panic.panic if the system is completely out of memory. The allocated region is zeroed before being returned.

kfree

procedure kfree(area: void);

Frees a previously allocated block. Detects large allocations by checking the magic sentinel at area - 12 and delegates to klfree if found. For normal allocations, reads the unit count prefix, validates the range and double-free guard, clears the bitmap range, updates FreeUnits and NextFree, and calls try_release_page to return completely-free pages to the VMM.

klalloc

function klalloc(size: uint32): void;

Allocates size bytes by mapping contiguous virtual pages from the low virtual address range (page numbers 5 through KERNEL_PAGE_NUMBER - 1). Writes a header containing the page count and LARGE_ALLOC_MAGIC sentinel. Returns a pointer 16 bytes past the header. Returns nil if no contiguous range is available.

klfree

procedure klfree(address: uint32);

Frees a large allocation by reading the page count from the header at address and releasing each mapped virtual page back to the VMM. Validates the page count before proceeding.

kpalloc

function kpalloc(address: uint32): void;

Identity-maps a physical 4 MiB block at the specified address using force_alloc_block and map_page. Used for memory-mapped hardware regions that must appear at a fixed virtual address.

lmm_total_free

function lmm_total_free: uint32;

Returns the total free bytes across all heap pages by summing FreeUnits * ALLOC_UNIT for every page in the linked list.

lmm_page_count

function lmm_page_count: uint32;

Returns the number of heap pages currently in the linked list.

Notes

The restore_if helper checks bit 9 (IF) of the saved EFLAGS word and issues STI only if interrupts were enabled on entry. It uses STI rather than POPFD to avoid restoring potentially dangerous EFLAGS bits (IOPL, NT, VM, AC) that could trigger a General Protection Fault or Bad-TSS on the next IRET.

When DEBUG_LMM is defined, kalloc allocates one additional unit and writes GUARD_MAGIC at the end of the allocation. kfree verifies this sentinel before freeing; a mismatch triggers a GPF with a syslog error, catching buffer overruns at free time.

Double-free detection uses bitmap_all_set: if any bit in the allocation's range is already clear at free time, the allocator logs an error and GPFs rather than silently corrupting the bitmap.

Fully empty pages (other than the root page) are returned to the VMM by try_release_page, which unlinks the page from the doubly-linked list and calls arch.x86.memory.virtual.free_page_at_address.