Memory Architecture

Firmware history becomes Arcology OS state

The UEFI memory map is validated and translated once. After that transition it becomes immutable bootstrap history; allocation and reservation policy consult the Physical Region Database rather than asking firmware to remain the authority.

Every region records its aligned base, pages, state, owner, Provider, reason, and flags. The database reserves its own metadata as well as the Arcology OS image, framebuffer, runtime firmware, ACPI, MMIO, and initial page tables.

Transactional region policy

A sub-range reservation must either fit completely and leave valid prefix/reserved/suffix records, or fail before modifying the database. The source refuses to disguise partial overlap as success.

ArcoBASICArcology source: owner-aware first-fit allocation

' Find the first free physical region large enough for the request.
FUNCTION PRDAllocateFirstFreeForOwner(database AS MMIOPTR, capacity AS U32, requestedPages AS U64, owner AS U32, purpose AS U32) AS U64
    ' Zero-page allocations cannot represent a real resource.
    IF requestedPages = 0 THEN RETURN 0
    LET count AS U32 = PRDRegionCount(database)
    LET index AS U32 = 0
    WHILE index < count
        ' Each region record occupies 64 bytes after the database header.
        LET record AS MMIOPTR = ADDRESS.Offset(database, 8 + (index * 64))
        LET state AS U32 = MEMORY.Read32(ADDRESS.Offset(record, 16))
        LET pages AS U64 = MEMORY.Read64(ADDRESS.Offset(record, 8))
        IF state = 0 AND pages >= requestedPages THEN
            LET base AS U64 = MEMORY.Read64(record)
            ' An exact fit can reuse the existing record in place.
            IF pages = requestedPages THEN
                MEMORY.Write32(ADDRESS.Offset(record, 16), 2)
                MEMORY.Write32(ADDRESS.Offset(record, 24), owner)
                MEMORY.Write32(ADDRESS.Offset(record, 40), purpose)
                RETURN base
            END IF
            ' A larger free region is split into allocated and remaining parts.
            IF count >= capacity THEN RETURN 0
            LET allocated AS MMIOPTR = ADDRESS.Offset(database, 8 + (count * 64))
            MEMORY.Write64(allocated, base)
            MEMORY.Write64(ADDRESS.Offset(allocated, 8), requestedPages)
            MEMORY.Write32(ADDRESS.Offset(allocated, 16), 2)
            MEMORY.Write32(ADDRESS.Offset(allocated, 24), owner)
            MEMORY.Write64(record, base + (requestedPages * 4096))
            MEMORY.Write64(ADDRESS.Offset(record, 8), pages - requestedPages)
            MEMORY.Write32(database, count + 1)
            RETURN base
        END IF
        index = index + 1
    WEND
    RETURN 0
END FUNCTION

Why the database uses numeric offsets

The allocator example addresses fields such as record + 16 or record + 24. These are byte offsets inside the current fixed Physical Region Database record format, not arbitrary memory locations. The database begins with an 8-byte header, then stores records that are each 64 bytes wide.

For example, record points to the start of one selected record. Offset 8 reaches its page-count field, offset 16 reaches state, offset 24 reaches owner, and offset 40 reaches purpose. Keeping the layout fixed lets freestanding code read records before richer language-level structures are available. The planned persistent record ABI should expose named accessors so ordinary policy code does not repeat raw offsets.

8 + (index × 64): skip the database header and select one 64-byte record
record + 8: page count
record + 16: allocation state
record + 24: owner identity
record + 40: purpose code
base + (requestedPages × 4,096): first address after the newly allocated page range

Virtual memory boundary

Physical Regions remain the sole backing authority. Address Spaces own root page tables and virtual policy; every mapping is intended to become a persistent Virtual Region Database record with protection, ownership, Provider, sharing, and lifecycle state.

ArcoBASIC validates mapping policy. The compiler supplies only unavoidable mechanisms such as CR3 access and page invalidation.

ArcoBASICArcology source: explicit address-space mechanisms

' Ask the CPU to use a new page-table root, then report what became active.
FUNCTION SwitchAddressSpace(root AS U64) AS U64
    CPU.WriteCR3(root)
    RETURN CPU.ReadCR3()
END FUNCTION

' Discard one stale virtual-address translation after a mapping changes.
FUNCTION InvalidateVirtualPage(address AS VIRTUALPTR) AS U64
    CPU.InvalidatePage(address)
    RETURN 0
END FUNCTION

All-or-nothing beats mostly-right

The allocator above either fits a request completely, leaving valid records behind, or fails before it changes anything. There is no partial state where a split has begun but not finished. That guarantee is worth more than the specific 64-byte record layout it happens to be written against.

Design mutations so a caller only ever sees the state before the change or the state after it, never a partial one. A split allocation that fails halfway through is a bug that will eventually corrupt something; refusing to start is always cheaper than cleaning up a half-finished mutation.
When a fast, simple, fixed-layout format is genuinely necessary at the boundary, as raw byte offsets are here, keep it isolated and plan the named-accessor layer explicitly rather than letting the raw offsets spread through the rest of the codebase.
Treat validated firmware or external input as immutable history the moment you have finished checking it. Re-deriving policy from a mutable source after that point reopens every race and inconsistency the validation step was meant to close.

LEARNING LAYER

Key terms, in plain language

You do not need a systems background to follow the work. These are the specialized terms used on this page.

PRDPhysical Region Database: Arcology OS records every known piece of physical memory here, including who owns it, what it is for, and whether it is free or reserved. This replaces scattered allocator knowledge with one inspectable source of truth.
Physical address: A location in the machine’s actual addressable memory or device space. Firmware and hardware report physical locations; applications normally should not use them directly.
Virtual address: A location in the address space currently presented to software. Page tables decide which physical memory or device, if any, appears at that virtual location.
Address alignment: Placing an address on a boundary required by the hardware, such as a multiple of 4 KiB or 2 MiB. Aligning down removes the lower offset bits while preserving the containing region.
Page table: A data structure used by the CPU to translate the virtual addresses a program uses into physical memory locations. It also carries access rules such as writable or executable.
CR3Control Register 3: An x86-64 CPU register that points to the active top-level page table. Writing CR3 changes which virtual-memory map the processor uses.
MMIOMemory-Mapped Input/Output: A way to control a hardware device by reading and writing special address ranges as if they were memory. A framebuffer is a common example.
UEFIUnified Extensible Firmware Interface: The standardized firmware environment that starts a modern computer before an operating system takes control. Arcology OS currently enters through UEFI during hardware bring-up.
Firmware: Software supplied with the machine that initializes hardware and starts the next stage of the system. It sits below ordinary applications and usually below the operating system.