ASA-EMulatR Reference Guide > Introduction > Architecture Overview > Chapter 5 - Memory System Architecture > 5.5 GuestMemory

5.5.1 Definition

GuestMemory represents the entire physical address space visible to all CPUs. It is the conceptual memory system — the single shared physical address space that receives load/store requests, applies routing, and tracks LL/SC reservations. There is one global GuestMemory instance shared by all CPUs (accessed via global_GuestMemory()).

GuestMemory contains:

•Physical RAM (via SafeMemory)

•MMIO regions (via mmio_Manager)

•PA routing table (QVector<PARouteEntry>)

•Reservation tracking (via ReservationManager)

Invariant: GuestMemory is global and authoritative. All CPUs observe the same backing store. No per-CPU private memory exists.

5.5.2 PA Routing Table

GuestMemory routes physical addresses to subsystems via a PA routing table (non-overlapping, ordered by PA). Each entry specifies a start PA (inclusive), end PA (exclusive), target subsystem, and an offset base for address translation into the subsystem's internal address space.

struct PARouteEntry {

quint64 startPA; // Inclusive

quint64 endPA; // Exclusive

RouteTarget target; // SafeMemory, MMIOManager

quint64 offsetBase; // Added to (pa - startPA) for subsystem offset

};

5.5.3 Default PA Region Map

The default physical address map (Option A) defines the following non-overlapping regions:

0x0000_0000 – 0x0001_0000 (64 KB) → SafeMemory — Low memory scratch, includes HWRPB at PA 0x2000

0x0001_0000 – 0x2000_0000 (~512 MB) → Unmapped — Reserved, faults on access

0x2000_0000 – 0x2020_0000 (2 MB) → SRM Firmware — clipper.bin, read-only

0x2020_0000 – 0x8000_0000 (~1.5 GB) → Unmapped — Reserved

0x8000_0000 – 0x8_8000_0000 (32 GB) → SafeMemory — Main RAM

0x8_8000_0000 – 0x10_0000_0000 (~96 GB) → Unmapped — Reserved for future expansion

0x10_0000_0000 – 0x20_0000_0000 (64 GB) → MMIO Manager — Device CSRs, BARs, PCI config

0x20_0000_0000+ → Unmapped — Reserved

5.5.4 Read/Write API

GuestMemory provides typed read/write methods at all standard widths: read8/write8, read16/write16, read32/write32, read64/write64, and bulk readPA/writePA. All methods route through the PA routing table via findRoute(pa), which returns the matching PARouteEntry or nullptr (AccessViolation) for unmapped regions.

The routing logic dispatches to SafeMemory::load/store (for RAM), SRM firmware (read-only), or mmio_Manager::handleRead/handleWrite (for device regions). The routing path also provides classifyPA() and classifyPARange() for pre-flight address classification.

5.5.5 Span-Based Access

For bulk operations (e.g., HWRPB initialization, PAL CSERVE PUTS), GuestMemory provides getSpanToPA(pa, requestedLen, intent) which returns a MemorySpan — a direct pointer into SafeMemory's backing storage. Spans are truncated at page boundaries and are not available for MMIO regions. This avoids per-byte routing overhead for large transfers.

Implementation: GuestMemory.h (286 lines) + GuestMemory.cpp.