diff --git a/README.md b/README.md index 2db745cc1f..58ff137cba 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,9 @@ The game can play system link games on a local network and on the internet: ## Build the game +An independent [Apple Silicon runtime memory probe](port/macos/README.md) +is available for early macOS port development. It does not build or run the game. + You do not need the Xbox SDK. The port supplies the SDK declarations that the game uses. Refer to [port/include/xdk](port/include/xdk/README.md). diff --git a/port/macos/README.md b/port/macos/README.md new file mode 100644 index 0000000000..c182eae4ab --- /dev/null +++ b/port/macos/README.md @@ -0,0 +1,85 @@ +# Apple Silicon runtime foundation (draft) + +This is a native arm64 macOS **memory probe**, not a playable port. It +establishes a small host-side memory contract before adding a game loader, +ABI bridges or graphics. It builds independently of the existing platforms +and needs only Python 3 and Xcode Command Line Tools, with no downloaded +dependencies or game assets. + +From the repository root: + +```sh +python3 tools/macos_memory_probe.py +``` + +The script builds `build/macos-runtime/memory_probe` with warnings as errors +and executes it. It rejects other platforms and Python running under Rosetta. +It does not change the default Ninja target or claim a `ninja macos` game build. + +## Memory contract + +The Android implementation is the reference for the game's 32-bit address +layout (`port/android/include/halo_android_abi.h`). The Xbox window starts at +`0x80000000`, spans 128 MiB, and the Android guest image starts at `0x88000000`. +The probe imports those constants rather than maintaining a second copy. + +On macOS, this experiment leaves low process addresses alone. Mach allocates +a separate 4 GiB-aligned, 4 GiB virtual region without replacing any existing +mapping. Guest addresses become offsets into that region: + +```text +host pointer = region base + unsigned 32-bit Xbox address +``` + +The reservation starts inaccessible and is backed on demand when pages are +made writable and touched; reserving it does not touch 4 GiB of physical RAM. +Guest address zero represents NULL. Translation rejects empty or overflowing +ranges and pointers outside the reservation. It checks address bounds, not +whether pages have been made readable. Reverse translation must be used +before storing a host pointer in a 32-bit game field. + +Protection calls require exact host-page boundaries and allow only read/write +permissions. They deliberately reject subpage requests rather than silently +altering protection of neighbouring Xbox blocks. The runtime has no executable +memory loader. A memory instance has one owner and must outlive every user. + +## Validation + +Locally verified on Apple Silicon, macOS 27.0.1, Apple clang 21.0.0: + +- Native arm64 host, 8-byte pointers and 16,384-byte host pages. +- Two distinct simultaneous 4 GiB-aligned reservations. +- Access and round-trip translation at the existing Xbox window offset. +- Guest NULL, empty ranges, 32-bit boundary and 64-bit size overflow rejection. +- Read/write, read-only and inaccessible transitions, queried through Mach. +- Adjacent pages and the guest-image address remain inaccessible. +- Misaligned and executable protection requests rejected. +- Reservation destruction, cleared state and recreation. + +These are host-runtime checks. No game execution, guest ABI interoperability, +save compatibility, renderer, multiplayer or older macOS version was tested. + +## Remaining decisions + +1. Select the guest execution strategy. Android's ILP32 instructions cannot + simply dereference these rebased addresses: every relevant memory access + and indirect code pointer needs translation. Alternatively, an LP64 source + conversion must retain explicit 32-bit fields in Xbox data structures. +2. Implement and validate the image loader and guest/host calls, including + function pointers, stack addresses, TLS, varargs and callback lifetimes. +3. Define 4 KiB guest-block bookkeeping on 16 KiB host pages. The current + strict protection API does not implement allocator or texture write tracking. +4. Add the platform services and graphics backend, then test actual game data. + +## Related work + +This branch starts from `cybersecurity/halo-ce-universal/main` and does not +include the browser PR's commits. Relevant existing work includes: + +- [#12: browser runtime](https://github.com/cybersecurity/halo-ce-universal/pull/12). +- [#16: experimental Apple Silicon target](https://github.com/cybersecurity/halo-ce-universal/pull/16). +- [#20: ILP32 macOS port with address rebasing](https://github.com/cybersecurity/halo-ce-universal/pull/20). +- [#22: macOS port with 64-bit source conversion](https://github.com/cybersecurity/halo-ce-universal/pull/22). + +This draft is a small independently runnable foundation for discussion alongside +those ports, not a claim to supersede their loaders or working game builds. diff --git a/port/macos/runtime/guest_memory.c b/port/macos/runtime/guest_memory.c new file mode 100644 index 0000000000..ee85be3a70 --- /dev/null +++ b/port/macos/runtime/guest_memory.c @@ -0,0 +1,85 @@ +#include "guest_memory.h" + +#include +#include + +kern_return_t halo_macos_memory_create(struct halo_macos_memory *memory) +{ + mach_vm_address_t base = 0; + kern_return_t result; + long page_size; + + if (!memory || memory->base || memory->page_size) + return KERN_INVALID_ARGUMENT; + page_size = sysconf(_SC_PAGESIZE); + if (page_size <= 0) + return KERN_FAILURE; + /* The alignment mask requests a 4 GB-aligned free range. ANYWHERE does + not overwrite an existing mapping, unlike a fixed mmap replacement. */ + result = mach_vm_map(mach_task_self(), &base, HALO_MACOS_ADDRESS_SPACE_SIZE, + HALO_MACOS_ADDRESS_SPACE_SIZE - 1, VM_FLAGS_ANYWHERE, + MEMORY_OBJECT_NULL, 0, FALSE, VM_PROT_NONE, + VM_PROT_READ | VM_PROT_WRITE, VM_INHERIT_NONE); + if (result != KERN_SUCCESS) + return result; + if (base < HALO_MACOS_ADDRESS_SPACE_SIZE || + base % HALO_MACOS_ADDRESS_SPACE_SIZE != 0 || + base > UINTPTR_MAX - HALO_MACOS_ADDRESS_SPACE_SIZE) + { + mach_vm_deallocate(mach_task_self(), base, HALO_MACOS_ADDRESS_SPACE_SIZE); + return KERN_NO_SPACE; + } + memory->base = (uintptr_t)base; + memory->page_size = (size_t)page_size; + return KERN_SUCCESS; +} + +kern_return_t halo_macos_memory_destroy(struct halo_macos_memory *memory) +{ + kern_return_t result; + + if (!memory || !memory->base) + return KERN_INVALID_ARGUMENT; + result = mach_vm_deallocate(mach_task_self(), memory->base, + HALO_MACOS_ADDRESS_SPACE_SIZE); + if (result == KERN_SUCCESS) + { + memory->base = 0; + memory->page_size = 0; + } + return result; +} + +void *halo_macos_guest_pointer(const struct halo_macos_memory *memory, + uint32_t address, uint64_t size) +{ + if (!memory || !memory->base || !address || !size || + size > HALO_MACOS_ADDRESS_SPACE_SIZE - address) + return NULL; + return (void *)(memory->base + address); +} + +int halo_macos_guest_address(const struct halo_macos_memory *memory, + const void *pointer, uint32_t *address) +{ + uintptr_t value = (uintptr_t)pointer; + + if (!memory || !memory->base || !address || value <= memory->base || + value - memory->base >= HALO_MACOS_ADDRESS_SPACE_SIZE) + return 0; + *address = (uint32_t)(value - memory->base); + return 1; +} + +kern_return_t halo_macos_memory_protect(const struct halo_macos_memory *memory, + uint32_t address, uint64_t size, vm_prot_t protection) +{ + void *pointer = halo_macos_guest_pointer(memory, address, size); + + if (!pointer || !memory->page_size || address % memory->page_size || + size % memory->page_size || + (protection & ~(VM_PROT_READ | VM_PROT_WRITE))) + return KERN_INVALID_ARGUMENT; + return mach_vm_protect(mach_task_self(), (mach_vm_address_t)pointer, + size, FALSE, protection); +} diff --git a/port/macos/runtime/guest_memory.h b/port/macos/runtime/guest_memory.h new file mode 100644 index 0000000000..88c0df75ae --- /dev/null +++ b/port/macos/runtime/guest_memory.h @@ -0,0 +1,34 @@ +/* Preliminary Darwin host memory contract; no game ABI conversion yet. */ +#ifndef HALO_MACOS_GUEST_MEMORY_H +#define HALO_MACOS_GUEST_MEMORY_H + +#include +#include +#include + +#define HALO_MACOS_ADDRESS_SPACE_SIZE (UINT64_C(1) << 32) + +struct halo_macos_memory +{ + uintptr_t base; + size_t page_size; +}; + +/* Zero-initialize before use. Ownership is exclusive; do not copy a live + instance or destroy it while another thread uses it. No executable pages. */ +kern_return_t halo_macos_memory_create(struct halo_macos_memory *memory); +kern_return_t halo_macos_memory_destroy(struct halo_macos_memory *memory); + +/* Zero is the guest NULL pointer. Translation checks bounds, not accessibility. + A translated host pointer must never be stored in a 32-bit game field. */ +void *halo_macos_guest_pointer(const struct halo_macos_memory *memory, + uint32_t address, uint64_t size); +int halo_macos_guest_address(const struct halo_macos_memory *memory, + const void *pointer, uint32_t *address); + +/* Require exact host-page boundaries: never silently widen a 4 KB game + request to a 16 KB host page and change a neighbouring block's protection. */ +kern_return_t halo_macos_memory_protect(const struct halo_macos_memory *memory, + uint32_t address, uint64_t size, vm_prot_t protection); + +#endif diff --git a/port/macos/tests/memory_probe.c b/port/macos/tests/memory_probe.c new file mode 100644 index 0000000000..7459f42a8e --- /dev/null +++ b/port/macos/tests/memory_probe.c @@ -0,0 +1,95 @@ +#include "../runtime/guest_memory.h" +#include "../../android/include/halo_android_abi.h" + +#include +#include + +#define CHECK(condition) do { if (!(condition)) { \ + fprintf(stderr, "FAIL line %d: %s\n", __LINE__, #condition); \ + goto failure; } } while (0) + +static int protection_is(void *pointer, vm_prot_t expected) +{ + mach_vm_address_t address = (mach_vm_address_t)pointer; + mach_vm_size_t size; + vm_region_basic_info_data_64_t info; + mach_msg_type_number_t count = VM_REGION_BASIC_INFO_COUNT_64; + mach_port_t object = MACH_PORT_NULL; + kern_return_t result = mach_vm_region(mach_task_self(), &address, &size, + VM_REGION_BASIC_INFO_64, (vm_region_info_t)&info, &count, &object); + if (object != MACH_PORT_NULL) + mach_port_deallocate(mach_task_self(), object); + return result == KERN_SUCCESS && address <= (mach_vm_address_t)pointer && + info.protection == expected; +} + +int main(void) +{ + struct halo_macos_memory memory = {0}, second = {0}; + uint32_t address = 0; + volatile uint32_t *window; + void *image; + + CHECK(halo_macos_memory_create(&memory) == KERN_SUCCESS); + printf("arm64 host: pointers=%zu, page=%zu, guest base=0x%llx\n", + sizeof(void *), memory.page_size, (unsigned long long)memory.base); + CHECK(sizeof(void *) == 8); + CHECK(memory.base % HALO_MACOS_ADDRESS_SPACE_SIZE == 0); + CHECK(halo_macos_memory_create(&memory) == KERN_INVALID_ARGUMENT); + CHECK(halo_macos_memory_create(&second) == KERN_SUCCESS); + CHECK(second.base != memory.base); + + window = halo_macos_guest_pointer(&memory, HALO_GUEST_WINDOW_BASE, + HALO_GUEST_WINDOW_SIZE); + image = halo_macos_guest_pointer(&memory, HALO_GUEST_IMAGE_BASE, memory.page_size); + CHECK(window && image); + CHECK(protection_is((void *)window, VM_PROT_NONE)); + CHECK(halo_macos_memory_protect(&memory, HALO_GUEST_WINDOW_BASE, + memory.page_size, VM_PROT_READ | VM_PROT_WRITE) == KERN_SUCCESS); + window[0] = 0x48414c4f; + window[memory.page_size / sizeof(*window) - 1] = 0x12345678; + CHECK(window[0] == 0x48414c4f); + CHECK(window[memory.page_size / sizeof(*window) - 1] == 0x12345678); + CHECK(halo_macos_guest_address(&memory, (void *)window, &address)); + CHECK(address == HALO_GUEST_WINDOW_BASE); + CHECK(!halo_macos_guest_pointer(&memory, 0, 1)); + CHECK(!halo_macos_guest_pointer(&memory, 1, 0)); + CHECK(!halo_macos_guest_pointer(&memory, UINT32_MAX, 2)); + CHECK(!halo_macos_guest_pointer(&memory, 1, UINT64_MAX)); + CHECK(halo_macos_guest_pointer(&memory, UINT32_MAX, 1)); + CHECK(halo_macos_guest_address(&memory, + halo_macos_guest_pointer(&memory, UINT32_MAX, 1), &address)); + CHECK(address == UINT32_MAX); + CHECK(!halo_macos_guest_address(&memory, NULL, &address)); + CHECK(!halo_macos_guest_address(&memory, (void *)memory.base, &address)); + CHECK(!halo_macos_guest_address(&memory, + (void *)(memory.base + HALO_MACOS_ADDRESS_SPACE_SIZE), &address)); + CHECK(!halo_macos_guest_address(&memory, &memory, &address)); + CHECK(halo_macos_memory_protect(&memory, HALO_GUEST_WINDOW_BASE + 1, + memory.page_size, VM_PROT_READ) == KERN_INVALID_ARGUMENT); + if (memory.page_size > 4096) + CHECK(halo_macos_memory_protect(&memory, HALO_GUEST_WINDOW_BASE, + 4096, VM_PROT_READ) == KERN_INVALID_ARGUMENT); + CHECK(halo_macos_memory_protect(&memory, HALO_GUEST_WINDOW_BASE, + memory.page_size, VM_PROT_EXECUTE) == KERN_INVALID_ARGUMENT); + CHECK(halo_macos_memory_protect(&memory, HALO_GUEST_WINDOW_BASE, + memory.page_size, VM_PROT_READ) == KERN_SUCCESS); + CHECK(protection_is((void *)window, VM_PROT_READ)); + CHECK(protection_is((char *)window + memory.page_size, VM_PROT_NONE)); + CHECK(protection_is(image, VM_PROT_NONE)); + CHECK(window[0] == 0x48414c4f); + CHECK(halo_macos_memory_protect(&memory, HALO_GUEST_WINDOW_BASE, + memory.page_size, VM_PROT_NONE) == KERN_SUCCESS); + CHECK(protection_is((void *)window, VM_PROT_NONE)); + CHECK(halo_macos_memory_destroy(&memory) == KERN_SUCCESS); + CHECK(!halo_macos_guest_pointer(&memory, HALO_GUEST_WINDOW_BASE, 4)); + CHECK(halo_macos_memory_destroy(&second) == KERN_SUCCESS); + CHECK(halo_macos_memory_create(&memory) == KERN_SUCCESS); + CHECK(halo_macos_memory_destroy(&memory) == KERN_SUCCESS); + puts("PASS: reservation, Xbox offsets, bounds, protection isolation, lifecycle"); + return 0; +failure: + if (second.base) halo_macos_memory_destroy(&second); + if (memory.base) halo_macos_memory_destroy(&memory); + return 1; +} diff --git a/tools/macos_memory_probe.py b/tools/macos_memory_probe.py new file mode 100644 index 0000000000..74467f895b --- /dev/null +++ b/tools/macos_memory_probe.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python3 +"""Build and run the preliminary Apple Silicon memory probe; no game data needed.""" + +import platform +import subprocess +from pathlib import Path + + +def main(): + if platform.system() != "Darwin" or platform.machine() != "arm64": + raise SystemExit("Run on native Apple Silicon macOS (not under Rosetta).") + root = Path(__file__).resolve().parent.parent + output = root / "build/macos-runtime" + output.mkdir(parents=True, exist_ok=True) + executable = output / "memory_probe" + subprocess.run([ + "xcrun", "clang", "-arch", "arm64", "-std=c11", "-O2", "-g", + "-Wall", "-Wextra", "-Werror", "-Wconversion", "-Wshadow", + str(root / "port/macos/runtime/guest_memory.c"), + str(root / "port/macos/tests/memory_probe.c"), + "-o", str(executable), + ], check=True) + subprocess.run([str(executable)], check=True) + + +if __name__ == "__main__": + main()