rex::memory::Memory

Overview

The Memory class models the entire Xbox 360 guest memory system, providing interfaces to both virtual and physical memory with TLB and page table management for allocation, mapping, and protection.

The memory is backed by a memory-mapped file and placed at a stable fixed host address (typically 0x100000000). This allows efficient guest-to-host address translation and easy sharing across subsystems.

Memory Layout

The guest memory address space is split into several ranges with varying properties:

Virtual Heaps: Standard guest virtual address ranges
Physical Heaps: Hardware-mapped memory for audio/graphics subsystems
Each range has its own page size, caching strategy, and protection settings

Class Definition

namespace rex::memory {
  class Memory;
}

Initialization

Memory()

Constructs a new Memory instance.

Memory();

Initialize()

Initializes the memory system by reserving host address space and setting up the memory-mapped file.

bool Initialize();

Returns: true on success, false if host address space reservation or file mapping fails

Reset()

Resets all memory to zero and clears all allocations.

void Reset();

Address Translation

TranslateVirtual()

Translates a guest virtual address to a host pointer.

template <typename T = uint8_t*>
T TranslateVirtual(uint32_t guest_address) const;

Parameters:

guest_address - Guest virtual address to translate

Returns: Host pointer to the memory location

The contents at the translated host address are in big-endian byte order.

TranslatePhysical()

Translates a guest physical address to a host pointer.

template <typename T = uint8_t*>
T TranslatePhysical(uint32_t guest_address) const;

Parameters:

guest_address - Guest physical address to translate

Returns: Host pointer to the memory location

HostToGuestVirtual()

Translates a host address back to a guest virtual address.

uint32_t HostToGuestVirtual(const void* host_address) const;

Parameters:

host_address - Host pointer to translate

Returns: Guest virtual address

GetPhysicalAddress()

Returns the guest physical address for a given guest virtual address.

uint32_t GetPhysicalAddress(uint32_t address) const;

Parameters:

address - Guest virtual address

Returns: Guest physical address, or UINT32_MAX if unavailable

Memory Operations

Zero()

Zeros out a range of guest memory.

void Zero(uint32_t address, uint32_t size);

Parameters:

address - Starting guest address
size - Number of bytes to zero

Fill()

Fills a range of guest memory with a byte value.

void Fill(uint32_t address, uint32_t size, uint8_t value);

Parameters:

address - Starting guest address
size - Number of bytes to fill
value - Byte value to write

Copy()

Copies a non-overlapping range of guest memory.

void Copy(uint32_t dest, uint32_t src, uint32_t size);

Parameters:

dest - Destination guest address
src - Source guest address
size - Number of bytes to copy

SearchAligned()

Searches for a sequence of dword values in big-endian order.

uint32_t SearchAligned(uint32_t start, uint32_t end, 
                       const uint32_t* values, size_t value_count);

Parameters:

start - Starting guest address
end - Ending guest address
values - Array of dword values to search for
value_count - Number of values in the array

Returns: Guest address where the sequence was found, or 0 if not found

System Heap Allocation

SystemHeapAlloc()

Allocates virtual memory from the system heap for kernel structures and internal allocations.

uint32_t SystemHeapAlloc(uint32_t size, uint32_t alignment = 0x20,
                         uint32_t system_heap_flags = kSystemHeapDefault);

Parameters:

size - Number of bytes to allocate
alignment - Alignment requirement (default: 32 bytes)
system_heap_flags - Allocation flags (see SystemHeapFlag)

Returns: Guest address of allocated memory, or 0 on failure

SystemHeapFree()

Frees memory allocated with SystemHeapAlloc().

void SystemHeapFree(uint32_t address);

Parameters:

address - Guest address to free

Heap Management

LookupHeap()

Gets the heap containing the given address.

const BaseHeap* LookupHeap(uint32_t address) const;
BaseHeap* LookupHeap(uint32_t address);

Parameters:

address - Guest address to lookup

Returns: Pointer to the heap, or nullptr if not found

LookupHeapByType()

Gets a heap with specific properties.

BaseHeap* LookupHeapByType(bool physical, uint32_t page_size);

Parameters:

physical - true for physical heap, false for virtual
page_size - Required page size

Returns: Pointer to matching heap, or nullptr

GetPhysicalHeap()

Gets the physical base heap.

VirtualHeap* GetPhysicalHeap();

Returns: Pointer to the physical heap

MMIO (Memory-Mapped I/O)

AddVirtualMappedRange()

Defines an MMIO virtual address range with read/write callbacks.

bool AddVirtualMappedRange(uint32_t virtual_address, uint32_t mask, uint32_t size,
                           void* context,
                           runtime::MMIOReadCallback read_callback,
                           runtime::MMIOWriteCallback write_callback);

Parameters:

virtual_address - Starting virtual address
mask - Address mask
size - Size of the range
context - User context pointer passed to callbacks
read_callback - Callback for read operations
write_callback - Callback for write operations

Returns: true on success

LookupVirtualMappedRange()

Gets the MMIO range for a virtual address.

runtime::MMIORange* LookupVirtualMappedRange(uint32_t virtual_address);

Parameters:

virtual_address - Address to lookup

Returns: Pointer to MMIO range, or nullptr

Physical Memory Callbacks

RegisterPhysicalMemoryInvalidationCallback()

Registers a callback for physical memory invalidation events.

void* RegisterPhysicalMemoryInvalidationCallback(
    PhysicalMemoryInvalidationCallback callback,
    void* callback_context);

Parameters:

callback - Callback function
callback_context - User context pointer

Returns: Handle for unregistering the callback

UnregisterPhysicalMemoryInvalidationCallback()

Unregisters a physical memory invalidation callback.

void UnregisterPhysicalMemoryInvalidationCallback(void* callback_handle);

Parameters:

callback_handle - Handle returned from registration

EnablePhysicalMemoryAccessCallbacks()

Enables physical memory access callbacks for a memory range.

void EnablePhysicalMemoryAccessCallbacks(
    uint32_t physical_address, uint32_t length,
    bool enable_invalidation_notifications,
    bool enable_data_providers);

Parameters:

physical_address - Starting physical address
length - Length of the range
enable_invalidation_notifications - Enable write invalidation callbacks
enable_data_providers - Enable data provider callbacks

Function Table API

These methods support static recompilation by providing a function dispatch table stored in guest memory at IMAGE_BASE + IMAGE_SIZE.

InitializeFunctionTable()

Initializes the function table region for recompiled code dispatch.

bool InitializeFunctionTable(uint32_t code_base, uint32_t code_size,
                             uint32_t image_base, uint32_t image_size);

Parameters:

code_base - Base address of code section
code_size - Size of code section
image_base - Base address of executable image
image_size - Size of executable image

Returns: true on success, false if allocation fails

SetFunction()

Registers a host function for a guest address.

void SetFunction(uint32_t guest_address, PPCFunc* host_function);

Parameters:

guest_address - Guest address to map
host_function - Host function pointer

GetFunction()

Gets the registered host function for a guest address.

PPCFunc* GetFunction(uint32_t guest_address) const;

Parameters:

guest_address - Guest address to lookup

Returns: Host function pointer, or nullptr if not registered

HasFunctionTable()

Checks if the function table has been initialized.

bool HasFunctionTable() const;

Returns: true if initialized

Properties

file_name()

Gets the path to the memory-mapped backing file.

const std::filesystem::path& file_name() const;

virtual_membase()

Gets the base address of virtual memory in host address space.

uint8_t* virtual_membase() const;

This is typically 0x100000000 on 64-bit systems.

physical_membase()

Gets the base address of physical memory in host address space.

uint8_t* physical_membase() const;

This is typically 0x200000000 on 64-bit systems.

Enumerations

SystemHeapFlag

enum SystemHeapFlag : uint32_t {
  kSystemHeapVirtual = 1 << 0,
  kSystemHeapPhysical = 1 << 1,
  kSystemHeapDefault = kSystemHeapVirtual
};

HeapType

enum class HeapType : uint8_t {
  kGuestVirtual,
  kGuestXex,
  kGuestPhysical,
  kHostPhysical
};

MemoryAllocationFlag

enum MemoryAllocationFlag : uint32_t {
  kMemoryAllocationReserve = 1 << 0,
  kMemoryAllocationCommit = 1 << 1
};

MemoryProtectFlag

enum MemoryProtectFlag : uint32_t {
  kMemoryProtectRead = 1 << 0,
  kMemoryProtectWrite = 1 << 1,
  kMemoryProtectNoCache = 1 << 2,
  kMemoryProtectWriteCombine = 1 << 3,
  kMemoryProtectNoAccess = 0
};

Runtime

Application

Codegen

Subsystems

Memory & Threading

Filesystem

​Overview

​Memory Layout

​Class Definition

​Initialization

​Memory()

​Initialize()

​Reset()

​Address Translation

​TranslateVirtual()

​TranslatePhysical()

​HostToGuestVirtual()

​GetPhysicalAddress()

​Memory Operations

​Zero()

​Fill()

​Copy()

​SearchAligned()

​System Heap Allocation

​SystemHeapAlloc()

​SystemHeapFree()

​Heap Management

​LookupHeap()

​LookupHeapByType()

​GetPhysicalHeap()

​MMIO (Memory-Mapped I/O)

​AddVirtualMappedRange()

​LookupVirtualMappedRange()

​Physical Memory Callbacks

​RegisterPhysicalMemoryInvalidationCallback()

​UnregisterPhysicalMemoryInvalidationCallback()

​EnablePhysicalMemoryAccessCallbacks()

​Function Table API

​InitializeFunctionTable()

​SetFunction()

​GetFunction()

​HasFunctionTable()

​Properties

​file_name()

​virtual_membase()

​physical_membase()

​Enumerations

​SystemHeapFlag

​HeapType

​MemoryAllocationFlag

​MemoryProtectFlag

​See Also

Build docs developers (and LLMs) love

Overview

Memory Layout

Class Definition

Initialization

Memory()

Initialize()

Reset()

Address Translation

TranslateVirtual()

TranslatePhysical()

HostToGuestVirtual()

GetPhysicalAddress()

Memory Operations

Zero()

Fill()

Copy()

SearchAligned()

System Heap Allocation

SystemHeapAlloc()

SystemHeapFree()

Heap Management

LookupHeap()

LookupHeapByType()

GetPhysicalHeap()

MMIO (Memory-Mapped I/O)

AddVirtualMappedRange()

LookupVirtualMappedRange()

Physical Memory Callbacks

RegisterPhysicalMemoryInvalidationCallback()

UnregisterPhysicalMemoryInvalidationCallback()

EnablePhysicalMemoryAccessCallbacks()

Function Table API

InitializeFunctionTable()

SetFunction()

GetFunction()

HasFunctionTable()

Properties

file_name()

virtual_membase()

physical_membase()

Enumerations

SystemHeapFlag

HeapType

MemoryAllocationFlag

MemoryProtectFlag

See Also