Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
85 changes: 85 additions & 0 deletions port/macos/README.md
Original file line number Diff line number Diff line change
@@ -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.
85 changes: 85 additions & 0 deletions port/macos/runtime/guest_memory.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
#include "guest_memory.h"

#include <mach/mach_vm.h>
#include <unistd.h>

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);
}
34 changes: 34 additions & 0 deletions port/macos/runtime/guest_memory.h
Original file line number Diff line number Diff line change
@@ -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 <mach/mach.h>
#include <stddef.h>
#include <stdint.h>

#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
95 changes: 95 additions & 0 deletions port/macos/tests/memory_probe.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
#include "../runtime/guest_memory.h"
#include "../../android/include/halo_android_abi.h"

#include <mach/mach_vm.h>
#include <stdio.h>

#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;
}
27 changes: 27 additions & 0 deletions tools/macos_memory_probe.py
Original file line number Diff line number Diff line change
@@ -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()