From 500a48ecd93cd50efb066bf2e56ff808f439d0a1 Mon Sep 17 00:00:00 2001 From: Brian Degenhardt Date: Sun, 12 Jul 2026 16:08:05 -0700 Subject: [PATCH] readme update --- README.md | 164 ++++-------------------------------------------------- 1 file changed, 11 insertions(+), 153 deletions(-) diff --git a/README.md b/README.md index 6f3e1673cc..786b5f95bd 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,19 @@ -# ARMSX2 โ€” Native ARM64 JIT Fork +# ARMSX2 โ€” Native ARM64 JIT Fork of PCSX2 +[![All Platforms](https://img.shields.io/github/actions/workflow/status/ARMSX2/ARMSX2/build-all.yml?branch=master&label=All%20Platforms)](https://github.com/ARMSX2/ARMSX2/actions/workflows/build-all.yml) -> ๐ŸŽ **This fork is dedicated to bringing native ARM64 JIT recompilers to ARMSX2 so that Apple Silicon Macs (and other ARM64 platforms) can run PS2 games at playable speed without Rosetta 2.** -> -> It tracks upstream ARMSX2 closely and adds a complete ARM64 recompiler backend, from **one shared core** that drives the ARM64 PC builds (macOS, Windows, Linux) **and** the Android and iOS apps. +ARMSX2 is a free and open-source PlayStation 2 (PS2) emulator based on PCSX2. Its purpose is to emulate the PS2's hardware, using a combination of MIPS CPU [Interpreters](), [Recompilers](https://en.wikipedia.org/wiki/Dynamic_recompilation) and a [Virtual Machine](https://en.wikipedia.org/wiki/Virtual_machine) which manages hardware states and PS2 system memory. This allows you to play PS2 games on your phone, PC, or gaming handheld, with many additional features and benefits. -[![MacOS Build Status](https://img.shields.io/github/actions/workflow/status/ARMSX2/ARMSX2/macos_build_matrix.yml?branch=macOS&label=%F0%9F%8D%8E%20MacOS%20Builds)](https://github.com/ARMSX2/ARMSX2/actions/workflows/macos_build_matrix.yml) -[![All Platforms](https://img.shields.io/github/actions/workflow/status/ARMSX2/ARMSX2/build-all.yml?branch=macOS&label=All%20Platforms)](https://github.com/ARMSX2/ARMSX2/actions/workflows/build-all.yml) +## Thank You -> [!IMPORTANT] -> **The repository is being restructured into a single-core monorepo.** The `macOS` -> branch is the canonical core and is becoming `main`; the Android and iOS apps now -> live as thin frontends under `platforms/`. If you are a collaborator, read -> **[Repository Layout](#-repository-layout)** and **[Monorepo Refactor โ€” In Progress](#-monorepo-refactor--in-progress)** below before branching, and see -> [`REFACTOR_STATUS.md`](REFACTOR_STATUS.md) for the full plan. +The ARMSX2 team is eternally indebted to the [PCSX2 project](https://pcsx2.net) it is based on. We are so fortunate to build on their 20 years of hardcore development. -ARMSX2 is a free and open-source PlayStation 2 (PS2) emulator. Its purpose is to emulate the PS2's hardware, using a combination of MIPS CPU [Interpreters](), [Recompilers](https://en.wikipedia.org/wiki/Dynamic_recompilation) and a [Virtual Machine](https://en.wikipedia.org/wiki/Virtual_machine) which manages hardware states and PS2 system memory. This allows you to play PS2 games on your PC, with many additional features and benefits. - -## ๐ŸŽ About This Fork +## About This Fork [![Project Demo](https://img.youtube.com/vi/a1_zydGhVaE/maxresdefault.jpg)](https://www.youtube.com/watch?v=a1_zydGhVaE) -The upstream PCSX2 project ships an ARM64 *interpreter* build for macOS, but its high-performance **JIT recompilers** (EE, IOP, VU0, VU1, and vtlb fast memory) are x86-64 only. On Apple Silicon that means either running under Rosetta 2 (emulated x86-64, slower and deprecated by Apple) or falling back to the interpreter core (orders of magnitude too slow for most games). +The upstream PCSX2 project ships an ARM64 *interpreter* build for ARM, but its high-performance **JIT recompilers** (EE, IOP, VU0, VU1, and vtlb fast memory) are x86-64 only. -**This fork exists to close that gap.** It is a line-for-line ARM64 port of the existing, battle-tested x86-64 JIT recompilers. The recompiler *architecture*, *block model*, *analysis passes*, and *JIT logic* are intentionally kept identical to upstream โ€” what changes is the backend emitter: x86-64 assembly (x86emitter) is translated to ARM64 assembly via [VIXL](https://github.com/Linaro/vixl). +**This fork exists to close that gap.** The goal is to preserve the correctness features of 20 years of PCSX2 development, while generating the fastest native ARM performance possible. **Current status:** - โœ… EE (Emotion Engine) recompiler โ€” integer, float, MMI, COP0/COP1/COP2, branches, load/store @@ -34,8 +25,6 @@ The upstream PCSX2 project ships an ARM64 *interpreter* build for macOS, but its - โœ… PS1 games (IOP mode) run at full speed โ€” e.g. *Gran Turismo 2* is fully playable - โœ… 3D games run (if crash try disabling MTVU) -**Native Apple Silicon** builds are provided. - ### Why LLMs / AI Were Used A word on methodology: @@ -44,86 +33,7 @@ The x86-64 JIT code in upstream ARMSX2 is **already proven correct** โ€” it has Large language models (LLMs) were used as an **accelerant for this translation work** โ€” pattern-matching x86 JIT boilerplate to ARM64 equivalents, scaffolding emit routines, and keeping the porting velocity high. The JIT *logic* (block compiler, dispatcher, analysis passes, flag pipelines, clamping rules, Tri-Ace hacks, etc.) is taken directly from the upstream x86 implementation and validated against it. **Nothing was hallucinated from scratch.** -In other words: the hard engineering was done by the ARMSX2 team over two decades. The hard *typing* โ€” translating ~50k lines of x86 emitter code into ARM64 โ€” is what AI helped compress. - -## ๐Ÿ—‚ Repository Layout - -Everything is built from **one shared PCSX2 core + ARM64 JIT** at the repository -root. Platform frontends are thin subfolders that consume that single core โ€” no -more per-platform forks of the emulator. - -``` -/ Shared PCSX2 core + ARM64 JIT (pcsx2/, common/, 3rdparty/, cmake/) -โ”œโ”€โ”€ pcsx2-qt/ Desktop Qt GUI โ†’ ARM64 PC builds for macOS ยท Windows ยท Linux -โ”œโ”€โ”€ platforms/ -โ”‚ โ”œโ”€โ”€ android/ Android app (Gradle + JNI); thin CMake sources the root core -โ”‚ โ””โ”€โ”€ ios/ iOS / iPadOS app (native UIKit + bridge); CMake sources the root core -โ””โ”€โ”€ .github/workflows/build-all.yml Builds every target on every push -``` - -Platform-specific code that lives in the core is guarded (`if(ANDROID)`, -`ARMSX2_IOS`, `APPLE`, `WIN32`, โ€ฆ); the mobile apps add only their UI, input, -and OS glue on top. - -| Target | Where it builds from | Output | -|---|---|---| -| macOS (Apple Silicon) | root + `pcsx2-qt/` | `ARMSX2.app` | -| Windows on ARM64 | root + `pcsx2-qt/` | *(workflow WIP โ€” see status)* | -| Linux on ARM64 | root + `pcsx2-qt/` | AppImage | -| Android | `platforms/android/` | `.apk` | -| iOS / iPadOS | `platforms/ios/` | `.app` | - -## ๐Ÿšง Monorepo Refactor โ€” In Progress - -The single-core restructure is happening on branch **`refactor/monorepo`** (cut -from `macOS`). This section is the short version for collaborators; the full -detail, decisions, and command references are in -[`REFACTOR_STATUS.md`](REFACTOR_STATUS.md). - -**Why:** the Android (`refresh-experimental`) and iOS (`iOS-refresh`) branches -each carried their *own* diverged copy of the PCSX2 core (iOS vendored ~12.8k -core files โ€” 93% of the branch). That triple-fork is being collapsed into the -single root core so every platform tracks the same emulator and JIT. - -**Done** - -- โœ… Android frontend snapshotted to `platforms/android/`; its vendored core - deleted; the Android-only core additions (Oboe audio, EGL-Android, NEON SPU2, - Android stubs, etc.) relocated into the root core behind `if(ANDROID)`. -- โœ… iOS frontend snapshotted to `platforms/ios/`; its vendored core **and** - vendored `3rdparty` deleted; iOS-only additions relocated behind `ARMSX2_IOS`; - CMake rewired to the root core (all iOS SDK / bundle / JIT-entitlement config - preserved). -- โœ… Both mobile builds rewired to source the single root `{pcsx2, common, 3rdparty}`. -- โœ… Unified CI (`build-all.yml`) โ€” one push builds PC macOS-arm64, PC Linux-arm64, - Android APK, and iOS `.app`, each uploading its own artifact. - -**Remaining** (help welcome) - -1. **Get each platform compiling green.** The collapsed-core builds have not been - compiled yet โ€” the Android/iOS CI jobs are `continue-on-error` on purpose and - are the mechanism to surface fixes. Flip them to blocking once green. -2. **Shared-file reconciliation (~250 files).** Only net-new mobile files were - relocated; Android's *edits to shared files* (FullscreenUI, Achievements, GS - device backends, VMManager, MemoryCardFile) still need folding in behind - platform guards. Deltas: `git diff macOS refresh-experimental -- pcsx2 common`. -3. **Port 3 ARM64 JIT fixes** from Android (`45b4b68d10`, `75351e8545`, `ec06302ccf`). -4. **De-duplicate 3rdparty** (`platforms/android/.../cpp/3rdparty`) against root once - the NDK build is green โ€” keep only Android-only deps (adrenotools, oboe). -5. **Add the Windows-on-ARM64 PC workflow** and a `pc-windows-arm64` job. - -**Branch plan** โ€” non-destructive: - -- `macOS` / `refactor/monorepo` โ†’ default **`main`**. -- `master` (22.6k commits behind, old upstream) โ†’ **`master-archive`**. -- `refresh-experimental` and `iOS-refresh` kept as archives (full mobile history - lives there; the monorepo takes a snapshot, not the history). - -## Project Details - -PCSX2 has been in development for more than 20 years. Past versions could only run a few public domain game demos, but newer versions can run most games at full speed, including popular titles such as Final Fantasy X and Devil May Cry 3. Visit the [PCSX2 compatibility list](https://pcsx2.net/compat/) to check the latest compatibility status of games (with more than 2500 titles tested). - -Installers and binaries for both stable and nightly builds are available from [our website](https://pcsx2.net/downloads/). +In other words: the hard engineering was done by the PCSX2 team over two decades. The hard *typing* โ€” translating ~50k lines of x86 emitter code into ARM64 โ€” is what AI helped compress. ## System Requirements @@ -131,58 +41,6 @@ ARMSX2 targets ARM64 across desktop (macOS, Windows, Linux) and mobile (Android, Please note that a BIOS dump from a legitimately-owned PS2 console is required to use the emulator. For more information, visit [this page](https://pcsx2.net/docs/setup/bios/). -### Apple Silicon (macOS) +## Building -| Requirement | Notes | -|---|---| -| macOS 12+ | Monterey or later | -| Apple Silicon (M1/M2/M3/M4) | Native ARM64 JIT; Rosetta 2 not required | -| 8 GB RAM minimum | 16 GB recommended for heavier titles | -| BIOS | Same requirement as x86-64 builds | - -## Building on Apple Silicon - -> Pre-built releases are coming soon. Until then, build from source. - -Prerequisites: Xcode command-line tools, CMake, Qt6, and the ARMSX2 dependency bundle. - -```bash -# 1. Dependencies can be built using -bash .github/workflows/scripts/macos/build-dependencies-universal.sh "path/to/pcsx2-deps" -``` - -```bash -# 2. Configure (one-time) -cmake -DCMAKE_PREFIX_PATH="/path/to/pcsx2-deps" \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_OSX_ARCHITECTURES="arm64" \ - -DDISABLE_ADVANCE_SIMD=ON \ - -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=OFF \ - -DUSE_LINKED_FFMPEG=ON \ - -DCMAKE_DISABLE_PRECOMPILE_HEADERS=ON \ - -B build . - -# 3. Build -cmake --build build --target pcsx2-qt -j$(sysctl -n hw.ncpu) - -# 4. Post-process macOS bundle (required!) -cmake --build build --target pcsx2-postprocess-bundle -codesign --force --deep --sign - build/pcsx2-qt/ARMSX2.app - -# 5. Run -open build/pcsx2-qt/ARMSX2.app -``` - -### Mobile builds - -The mobile apps build against the same root core: - -- **Android** โ€” `platforms/android/` (Gradle): `./gradlew :app:assembleRelease` - (requires JDK 17 + Android SDK/NDK). Its native `CMakeLists.txt` sources the - repo-root core. -- **iOS / iPadOS** โ€” `platforms/ios/` (Xcode/CMake): configure - `platforms/ios/app/src/main/cpp` with `-G Xcode -DCMAKE_SYSTEM_NAME=iOS`. - -Both are wired but not yet verified green โ€” see the -[refactor status](#-monorepo-refactor--in-progress). The canonical reference for -each build is the `build-all.yml` workflow. +Check out our [github actions](https://github.com/ARMSX2/ARMSX2/actions/workflows/build-all.yml) for the latest build recipe