People have dreamed of running macOS on iPad for more than a decade. Today, that dream comes true. With Virtual Mac, iPad finally breaks free from iPadOS, enabling pro apps like Xcode, Terminal, Final Cut Pro, Logic Pro, and Pixelmator Pro to run directly on device. Requires iPad Pro (M1, M2) or iPad Air (M1) running iPadOS 14 up to 16.3.1.
Shell
#!/usr/bin/env python3
"""Exercise Virtualization.framework's private guest GDB stub.
This is a development probe, not part of the shipped app. It intentionally
implements only the small acknowledged-packet subset used by Apple's stub so
bring-up does not depend on LLDB's kernel plugin.
"""
import argparse
import socket
import struct
def checksum(payload: bytes) -> bytes:
return f"{sum(payload) & 0xff:02x}".encode("ascii")
class Remote:
def __init__(self, host: str, port: int) -> None:
self.socket = socket.create_connection((host, port), timeout=5)
self.socket.settimeout(5)
self.pending = bytearray()
self.no_ack = False
self.socket.sendall(b"+")
def _receive_byte(self) -> int:
if not self.pending:
chunk = self.socket.recv(65536)
if not chunk:
raise ConnectionError("GDB stub closed the connection")
self.pending.extend(chunk)
value = self.pending[0]
del self.pending[0]
return value
def _receive_packet(self) -> bytes:
while self._receive_byte() != ord("$"):
pass
payload = bytearray()
while True:
value = self._receive_byte()
if value == ord("#"):
break
payload.append(value)
received = bytes((self._receive_byte(), self._receive_byte()))
if checksum(payload) != received.lower():
self.socket.sendall(b"-")
raise ValueError("GDB packet checksum mismatch")
if not self.no_ack:
self.socket.sendall(b"+")
return bytes(payload)
def request(self, text: str) -> bytes:
payload = text.encode("ascii")
self.socket.sendall(b"$" + payload + b"#" + checksum(payload))
# Apple's stub acknowledges every request before sending its reply.
if not self.no_ack:
while self._receive_byte() != ord("+"):
pass
return self._receive_packet()
def start_no_ack_mode(self) -> None:
if self.request("QStartNoAckMode") != b"OK":
raise RuntimeError("GDB stub refused no-ack mode")
self.no_ack = True
def close(self) -> None:
try:
try:
print("detach:", self.request("D").decode("ascii", "replace"))
except (ConnectionError, OSError, TimeoutError):
pass
finally:
self.socket.close()
def read_memory(self, address: int, length: int) -> bytes:
result = bytearray()
# Apple's endpoint supports large binary reads. A 256 KiB request was
# validated on-device and makes whole-kernel pattern scans fast enough
# to use during normal VM startup.
while len(result) < length:
amount = min(0x40000, length - len(result))
current = address + len(result)
# Use GDB's binary-memory command. An address beginning in `ffff`
# makes the packet appear as `$xffff...` in LLDB packet logs: the
# first `x` is the command, not part of the address.
response = self.request(f"x{current:x},{amount:x}")
if (len(response) == 3 and response.startswith(b"E") and
all(byte in b"0123456789abcdefABCDEF"
for byte in response[1:])):
raise OSError(f"guest memory read failed: {response!r}")
value = bytearray()
position = 0
while position < len(response):
byte = response[position]
position += 1
if byte == ord("}"):
if position >= len(response):
raise OSError("truncated GDB binary escape")
byte = response[position] ^ 0x20
position += 1
value.append(byte)
if len(value) != amount:
raise OSError(
f"short guest memory read: wanted {amount}, "
f"got {len(value)}")
result.extend(value)
return bytes(result)
def write_memory(self, address: int, value: bytes) -> None:
encoded = value.hex()
response = self.request(f"M{address:x},{len(value):x}:{encoded}")
if response != b"OK":
raise OSError(f"guest memory write failed: {response!r}")
def register(self, number: int) -> int:
encoded = self.request(f"p{number:x}")
return int.from_bytes(bytes.fromhex(encoded.decode("ascii")), "little")
MH_MAGIC_64 = 0xFEEDFACF
CPU_TYPE_ARM64 = 0x0100000C
MH_EXECUTE = 2
MH_FILESET = 12
LC_SEGMENT_64 = 0x19
def find_kernel(remote: Remote, pc: int) -> tuple[int, dict[str, tuple[int, int]]]:
page = pc & ~0x3FFF
for _ in range((128 * 1024 * 1024) // 0x4000):
try:
header = remote.read_memory(page, 32)
except OSError:
page -= 0x4000
continue
fields = struct.unpack("<IIIIIIII", header)
magic, cpu_type, _, file_type, ncmds, sizeofcmds, _, _ = fields
if (magic != MH_MAGIC_64 or cpu_type != CPU_TYPE_ARM64 or
file_type not in (MH_EXECUTE, MH_FILESET) or
not 0 < ncmds < 1000 or
sizeofcmds > 1024 * 1024):
page -= 0x4000
continue
commands = remote.read_memory(page + 32, sizeofcmds)
segments: dict[str, tuple[int, int]] = {}
offset = 0
valid = True
for _ in range(ncmds):
if offset + 8 > len(commands):
valid = False
break
command, size = struct.unpack_from("<II", commands, offset)
if size < 8 or offset + size > len(commands):
valid = False
break
if command == LC_SEGMENT_64 and size >= 72:
raw_name = commands[offset + 8:offset + 24]
name = raw_name.split(b"\0", 1)[0].decode("ascii", "replace")
vm_address, vm_size = struct.unpack_from("<QQ", commands,
offset + 24)
segments[name] = (vm_address, vm_size)
offset += size
if valid and "__TEXT" in segments and "__TEXT_EXEC" in segments:
return page, segments
page -= 0x4000
raise RuntimeError("kernel Mach-O header not found")
def sign_extend(value: int, bits: int) -> int:
sign = 1 << (bits - 1)
return (value ^ sign) - sign
def decode_adrp(pc: int, instruction: int) -> int:
immediate = (((instruction >> 5) & 0x7FFFF) << 2) | \
((instruction >> 29) & 3)
return (pc & ~0xFFF) + (sign_extend(immediate, 21) << 12)
def scan_text(remote: Remote, start: int, size: int, callback):
chunk_size = 0x40000
overlap = 32
offset = 0
tail = b""
while offset < size:
amount = min(chunk_size, size - offset)
chunk = remote.read_memory(start + offset, amount)
data = tail + chunk
data_address = start + offset - len(tail)
for position in range((-data_address) & 3, len(data) - 28, 4):
result = callback(data, position, data_address + position)
if result is not None:
return result
tail = data[-overlap:]
offset += amount
return None
def find_boot_args_pointer(remote: Remote, start: int, size: int) -> int:
prefix = struct.pack("<III", 0xAA0203E3, 0xAA0103E2, 0xAA0003E1)
def match(data: bytes, position: int, pc: int):
if data[position:position + 12] != prefix:
return None
adrp, add, load, command_line = struct.unpack_from("<IIII", data,
position + 12)
if adrp & 0x9F00001F != 0x90000008:
return None
if add & 0xFFC003FF != 0x91000108:
return None
if load & 0xFFC003FF != 0xF9400108:
return None
if command_line != 0x9101B100: # add x0, x8, #0x6c
return None
add_value = ((add >> 10) & 0xFFF) << (12 if add & (1 << 22) else 0)
load_value = ((load >> 10) & 0xFFF) * 8
return decode_adrp(pc + 12, adrp) + add_value + load_value
result = scan_text(remote, start, size, match)
if result is None:
raise RuntimeError("PE_parse_boot_argn pattern not found")
return result
def looks_like_boot_args(value: bytes) -> bool:
"""Validate the public XNU arm64 boot_args prefix and CommandLine."""
if len(value) < 128:
return False
revision, version = struct.unpack_from("<HH", value)
virtual_base, physical_base, memory_size, top = struct.unpack_from(
"<QQQQ", value, 8)
device_tree = struct.unpack_from("<Q", value, 96)[0]
device_tree_length = struct.unpack_from("<I", value, 104)[0]
command = value[108:128].split(b"\0", 1)[0]
return (1 <= revision <= 4 and 1 <= version <= 2 and
virtual_base & 0xFFF == 0 and physical_base & 0xFFF == 0 and
128 << 20 <= memory_size <= 1 << 40 and
physical_base <= top <= physical_base + memory_size and
device_tree >= 0xFFFF_0000_0000_0000 and
0 < device_tree_length <= 64 << 20 and
all(0x20 <= byte <= 0x7E for byte in command))
def find_boot_args_pointer_by_data(
remote: Remote, segments: dict[str, tuple[int, int]],
slide: int) -> int:
"""Find PE_state.bootArgs without relying on compiler instruction order.
XNU's boot_args prefix is public and stable, while PE_boot_args has been
inlined differently across Monterey, Tahoe, and Golden Gate kernels.
"""
live_segments = {
name: (address + slide, size)
for name, (address, size) in segments.items()
}
image_start = min(address for address, _ in live_segments.values())
image_end = max(address + size
for address, size in live_segments.values())
data_segments: list[tuple[int, bytes]] = []
for name, (address, size) in live_segments.items():
if ((name.startswith("__DATA") or name.startswith("__BOOTDATA")) and
size <= 64 << 20):
data_segments.append((address, remote.read_memory(address, size)))
external: list[tuple[int, int]] = []
internal: list[tuple[int, int]] = []
seen_external: set[int] = set()
seen_internal: set[int] = set()
for address, contents in data_segments:
for offset in range(0, len(contents) - 7, 8):
target = struct.unpack_from("<Q", contents, offset)[0]
if target < 0xFFFF_0000_0000_0000:
continue
points_into_data = any(
start <= target < start + len(data)
for start, data in data_segments)
if target < image_start or target >= image_end:
if target not in seen_external:
seen_external.add(target)
external.append((address + offset, target))
elif points_into_data and target not in seen_internal:
seen_internal.add(target)
internal.append((address + offset, target))
for candidates in (external, internal):
for slot, target in candidates:
value = None
for address, contents in data_segments:
offset = target - address
if 0 <= offset and offset + 128 <= len(contents):
value = contents[offset:offset + 128]
break
if value is None:
try:
value = remote.read_memory(target, 128)
except OSError:
continue
if looks_like_boot_args(value):
return slot
raise RuntimeError("validated boot_args structure not found")
def find_csr_config(remote: Remote, start: int, size: int) -> int:
tail = (0x12003109, 0x321D012A, 0x5280022B, 0x6A0B011F,
0x1A8A0128, 0x6A28001F, 0x1A9F07E0, 0xD65F03C0)
def match(data: bytes, position: int, pc: int):
if position + 40 > len(data):
return None
instructions = struct.unpack_from("<10I", data, position)
adrp, load = instructions[:2]
logical_mask = instructions[2]
if (logical_mask & 0xFF8003FF != 0x12000109 or
tuple(instructions[3:]) != tail[1:]):
return None
if adrp & 0x9F00001F != 0x90000008:
return None
if load & 0xFFC003FF != 0xB9400108:
return None
load_value = ((load >> 10) & 0xFFF) * 4
return decode_adrp(pc, adrp) + load_value
result = scan_text(remote, start, size, match)
if result is None:
raise RuntimeError("csr_check pattern not found")
return result
def patch_runtime_policy(remote: Remote, pc: int) -> None:
kernel, segments = find_kernel(remote, pc)
static_text, _ = segments["__TEXT"]
static_exec, exec_size = segments["__TEXT_EXEC"]
slide = kernel - static_text
live_exec = static_exec + slide
print(f"kernel: 0x{kernel:x}, slide: 0x{slide:x}")
# Both platform-expert and CSR initialization live near the front of
# __TEXT_EXEC on supported macOS kernels. Keep the stopped-boot scan
# bounded rather than reading the many embedded kexts that follow it.
patchfinder_size = min(exec_size, 32 * 1024 * 1024)
try:
boot_args_pointer = find_boot_args_pointer(remote, live_exec,
patchfinder_size)
except RuntimeError:
boot_args_pointer = find_boot_args_pointer_by_data(remote, segments,
slide)
csr_config = find_csr_config(remote, live_exec, patchfinder_size)
boot_args = int.from_bytes(remote.read_memory(boot_args_pointer, 8),
"little")
command_address = boot_args + 0x6C
command = remote.read_memory(command_address, 1024).split(b"\0", 1)[0]
tokens = command.decode("utf-8", "replace").split()
required = ("-arm64e_preview_abi", "amfi_get_out_of_my_way=1",
"ipc_control_port_options=0")
for token in required:
if token not in tokens:
tokens.append(token)
updated = " ".join(tokens).encode("utf-8")
if len(updated) >= 1024:
raise RuntimeError("guest boot arguments are full")
remote.write_memory(command_address, updated + b"\0")
remote.write_memory(csr_config, struct.pack("<I", 0xFFF))
print(f"boot_args: 0x{boot_args:x}, csr_config: 0x{csr_config:x}")
print("command:", updated.decode("utf-8"))
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("--host", default="127.0.0.1")
parser.add_argument("--port", type=int, default=12346)
parser.add_argument("--continue-until-kernel", action="store_true")
parser.add_argument("--patch-runtime-policy", action="store_true")
args = parser.parse_args()
remote = Remote(args.host, args.port)
try:
remote.start_no_ack_mode()
stop_response = b""
for request in ("qSupported", "?"):
response = remote.request(request)
print(f"{request}: {response.decode('ascii', 'replace')}")
if request == "?":
stop_response = response
if args.continue_until_kernel or args.patch_runtime_policy:
for attempt in range(8):
fields = {}
stop_fields = stop_response.decode("ascii").replace(";", ",")
for field in stop_fields.split(","):
if ":" in field:
key, value = field.split(":", 1)
fields[key] = value
if "20" not in fields:
raise RuntimeError("stop reply did not include the PC")
pc = int.from_bytes(bytes.fromhex(fields["20"]), "little")
print(f"stop {attempt}: pc=0x{pc:x}")
if pc >= 0xffff_0000_0000_0000:
break
remote.socket.settimeout(60)
stop_response = remote.request("c")
remote.socket.settimeout(5)
print("continue:",
stop_response.decode("ascii", "replace"))
else:
raise RuntimeError("guest did not reach the kernel stop")
if args.patch_runtime_policy:
patch_runtime_policy(remote, pc)
finally:
remote.close()
if __name__ == "__main__":
main()