Skip to content

Architecture

Jump to bottom
bot edited this page Sep 14, 2026 · 1 revision

Architecture

HyperHLE is a high-level emulator: it executes the app's original ARMv7 machine code on an interpreter/CPU core, but implements the iPhone OS system (frameworks, system calls) in Rust on the host, instead of emulating a full iOS kernel.

Layer map

App binary (Mach-O)
   +--> dyld          loads Mach-O, links symbols to host implementations
   +--> cpu           ARM interpreter executing guest code
   |       +--> guest->host calls: Objective-C msgSend, C functions, syscalls
   +--> objc          Objective-C runtime (classes, selectors, messages)
   +--> frameworks    iPhone OS framework re-implementations (the bulk)
   |       UIKit, Foundation, Core Graphics, OpenGLES, AudioToolbox,
   |       AVFoundation, GameKit, StoreKit, WebKit, ... (see src/frameworks/)
   +--> gles          GLES 1.1/2.0 translated to desktop OpenGL
   +--> audio.rs      audio device (OpenAL Soft under the hood)
   +--> window.rs     SDL2 window + input events
   +--> mem           guest address space (sparse flat memory)
   +--> fs            guest filesystem sandbox backed by the host FS

Key modules (src/)

  • mach_o.rs, dyld/ — binary parsing and dynamic linking; symbol binding decides which guest calls become host calls.
  • cpu/, cpu.rs — ARM interpreter; guest code runs at native speed only when it touches nothing external, otherwise it traps into the host.
  • objc/, objc.rs — Objective-C runtime; apps mostly talk to the "system" through objc_msgSend, which dispatches to registered host classes.
  • frameworks/ — ~70 re-implemented frameworks, one file each. Unimplemented methods log warnings (see Debugging).
  • mem/, mem.rs — guest memory: sparse flat address space with allocation tracking.
  • options.rs — CLI options (--help shows all).
  • gdb.rs — optional GDB stub for guest debugging.

AppDB (separate product)

appdb/ is a Python/FastAPI + SQLite web app for collecting compatibility reports (https://appdb.touchhle.org). It lives in the same repo; see AppDB.

Fork-specific areas

  • Android: android/ Gradle project wraps the Rust lib via cargo-ndk; android_web_view.rs hosts in-app web content.
  • Auto-incrementing versionCode derived from git history so APKs always upgrade in place.
  • GPU/GLES fixes: shader translation, texture formats, EAGL/Core Animation composition (black-screen fixes).

HyperHLE

Clone this wiki locally