thejayman77/retroDE_ps2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: retroDE_ps2 — first-of-its-kind PS2 GS FPGA core (DE25-Nano / Agilex 5)

Browse Source 
RTL (GS rasterizer, EE core stub, platform bridge, LPDDR4B path), sim regression
(272 TBs), docs, and tooling. Copyrighted PS2 content (BIOS, game code, GS dumps,
and all dump-derived textures/traces) is excluded via .gitignore and stays local.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
thejayman77
2026-06-29 20:10:50 -04:00
commit ec82764bef
2462 changed files with 2174303 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
references/supplemental/README.md
+20
View File
@@ -0,0 +1,20 @@
# Supplemental References (Claude pass)
These notes supplement the top-level `references/` files produced by the Codex
pass. Goal: add sources Codex did not surface, without duplicating its memory
map / workstream / emulator-landscape work.
Files in this folder:
- `sony_official_docs.md`: primary Sony register manuals for GS and the VUs.
Codex leaned on `ps2tek` (community-compiled); these are one layer closer to
the silicon.
- `fpga_prior_art.md`: PSX-on-FPGA projects. None are PS2, but they are the
closest real-world methodology templates for a console-gen FPGA effort.
- `architecture_studies.md`: high-level architecture writeups, an academic
VU-on-FPGA feasibility thesis, and MiSTer community consensus on why PS2
has not been attempted.
- `source_log.md`: sources introduced in this pass, with URLs and short notes.
These are reference-only. No implementation claims, no planning overrides —
Codex's `implementation_workstreams.md` remains the planning map.
references/supplemental/architecture_studies.md
+84
View File
@@ -0,0 +1,84 @@
# Architecture Studies and Community Signal
Context sources that complement Codex's register-level material. These are for
orientation and feasibility reasoning rather than implementation detail.
## High-level architecture
### Rodrigo Copetti — "PlayStation 2 Architecture: A Practical Analysis"
- URL: https://www.copetti.org/writings/consoles/playstation-2/
- One of the clearest pedagogical writeups of the PS2 as a system. Covers the
EE, VU complex, GS, IOP, and data paths with diagrams.
- Good onboarding reading for anyone joining the project cold. Not a spec.
### psdevwiki — PS2 section
- URL: https://www.psdevwiki.com/ps2/
- Community-maintained counterpart to `ps2tek`. Strong on IOP modules, SPU2,
peripheral protocols, and regional/hardware revision differences.
- Useful cross-check: when `ps2tek` and `psdevwiki` agree, treat as settled.
When they disagree, flag for verification against Sony manuals or emulator
behavior.
### Wikipedia — PS2 technical specifications / Emotion Engine
- URLs:
- https://en.wikipedia.org/wiki/PlayStation_2_technical_specifications
- https://en.wikipedia.org/wiki/Emotion_Engine
- Orientation only. Not suitable as an implementation source.
## Academic / feasibility
### VPU Thesis — "A Study on the Feasibility of ... VU [on FPGA]"
- URL: https://gamehacking.org/faqs/VPUThesis.pdf
- Academic study specifically looking at implementing the PS2 Vector Unit on
FPGA. Directly relevant to Codex workstream 4 (VU/VIF).
- Worth reading carefully before any VU design decisions — likely surfaces
pitfalls that would otherwise be discovered the hard way in simulation.
## Community consensus (why nobody has done this)
These threads are not technical references, but they capture the current
community baseline of what has been tried, what was abandoned, and why. Useful
for setting expectations with stakeholders.
- MiSTer Forum — "Advanced cores for MiSTer future FPGA hardware":
https://misterfpga.org/viewtopic.php?t=4884
- MiSTer Forum — "What Do You Think Will Happen Once MiSTer Reaches Its Limits?":
https://misterfpga.org/viewtopic.php?t=2512
- Time Extension — MiSTer Pi and next-gen FPGA gaming:
https://www.timeextension.com/news/2025/03/the-next-generation-of-fpga-gaming-could-be-just-around-the-corner-thanks-to-mister-pi
Distilled consensus (as of 2026-04):
- No PS2 FPGA core exists, anywhere, open or closed.
- Mainstream view is that PS2 exceeds MiSTer-class FPGA fabric (DE10-Nano
Cyclone V): the EE+VU+GS combination is the wall, and Dreamcast is already
considered near the ceiling.
- The only publicly-discussed PS2-via-FPGA effort has been a *hybrid*: a PCIe
FPGA card offloading specific hot blocks (128-bit math, possibly GS-adjacent
work) to a host CPU running an emulator. Not a self-contained core.
- Cost estimate for an FPGA that could plausibly fit full PS2 at useful
timing: "$1000+ for the chip alone" in forum discussions.
## Implication for retroDE_ps2
The feasibility picture is not an argument against the project — it is a
framing argument for the plan. Realistic posture options:
1. **Hybrid architecture** (host CPU + FPGA co-processing). Matches the only
known active PS2-via-FPGA effort. Changes the retroDE shell contract.
2. **Subset / staged core** (e.g. EE + IOP + minimal GS, software-rendered
framebuffer first). Closer to homebrew/demo compatibility than full-title
compatibility. Lets bring-up progress without waiting for the full GIF/GS
problem.
3. **Future-hardware target**. Design against a more capable FPGA than the
current retroDE platform. Decouples the project from today's fabric
constraints at the cost of harder validation.
4. **Full native on current hardware**. Widely considered infeasible; would
require pushing past what any open console-FPGA project has achieved.
Worth settling which of these retroDE_ps2 is aiming at before Phase 0 locks
memory/firmware/host decisions.
references/supplemental/fpga_prior_art.md
+65
View File
@@ -0,0 +1,65 @@
# FPGA Prior Art (Adjacent Consoles)
Codex correctly noted that no credible open-source HDL PS2 core surfaced. What
*did* surface, and what Codex did not log, is a small cluster of PSX-on-FPGA
projects. None are PS2, but they are the closest real-world templates for how
a console-generation FPGA effort is scoped, built, and validated.
## PSX_MiSTer — Robert Peip (FPGAzumSpass)
- Repo: https://github.com/MiSTer-devel/PSX_MiSTer
- Most feature-complete and widely-used PSX FPGA core.
- Author's prior work: GBA, Atari Lynx, WonderSwan cores on MiSTer.
The methodology is the useful part, not the RTL:
1. Peip wrote his own cycle-accurate PSX *software* emulator first.
2. Only then did he start the FPGA implementation, using the emulator as a
continuous cycle-level golden model.
3. Test vectors and traces were generated by the emulator and replayed into
the RTL under simulation.
Why this matters for retroDE_ps2:
- This is the only known methodology that has produced a credible, accurate
console-gen FPGA core from open-source work. Worth taking seriously as a
starting playbook, even if the final plan diverges.
- It implies the reference-emulator choice (PCSX2 vs DobieStation vs Play! vs
a purpose-built tiny one) is an architectural decision, not just a
debugging nicety.
## PS-FPGA
- Repo: https://github.com/PS-FPGA/ps-fpga
- Separate PSX-on-FPGA effort. Useful as a comparison point for project
organization, module decomposition, and test harness layout.
## pgate1/PlayStation_on_FPGA
- Repo: https://github.com/pgate1/PlayStation_on_FPGA
- Smaller / more hobbyist-scale PSX FPGA. Useful as a "minimum viable scaffold"
reference if the project needs a leaner starting shape than PSX_MiSTer.
## What these do not give us
- Zero usable RTL for EE, GS, VU0/VU1, VIF, GIF, SPU2, or the DMAC. The PSX's
GPU is not a GS, its CPU is not an R5900, and it has no VU complex. Nothing
transfers as a datapath.
- No GIF/GS packet path equivalent. This is a PS2-specific problem the PSX
cores did not need to solve.
## What they do give us
- A methodology template: golden-reference emulator → RTL with cycle-level
trace comparison.
- A feel for scope discipline: PSX took Peip years *with* strong prior FPGA
experience. PS2 is materially larger.
- Practical file layout, build, testbench, and host-integration patterns on
MiSTer-class platforms.
## Planning implication
Before Phase 0 lock, it is worth deciding explicitly whether retroDE_ps2 will
follow the "cycle-accurate reference emulator first" pattern, adopt an
existing emulator (PCSX2 or DobieStation) as the golden model, or take a
different validation approach entirely. The answer changes Phase 1 scope.
references/supplemental/sony_official_docs.md
+56
View File
@@ -0,0 +1,56 @@
# Official Sony Documentation
Codex's pass leaned on `ps2tek` as the low-level reference. `ps2tek` is
excellent but community-compiled. For register semantics where authority
matters, the two original Sony manuals below sit one layer closer to silicon.
## GS User's Manual v6.0
- Primary register reference for the Graphics Synthesizer.
- Covers the privileged register block at `0x12000000`: `PMODE`, `SMODE1/2`,
`SYNCH1/2`, `SYNCHV`, `SRFSH`, `DISPFB1/2`, `DISPLAY1/2`, `EXTBUF`,
`EXTDATA`, `EXTWRITE`, `BGCOLOR`, `CSR`, `IMR`, `BUSDIR`, `SIGLBLID`.
- Covers GS-internal host-visible registers (PRIM, PRMODE, RGBAQ, ST, UV, XYZ,
TEX0/1, CLAMP, FOG, TRXPOS, TRXREG, TRXDIR, etc.) and their packet forms.
- Authoritative for PCRTC output-side behavior that `ps2tek` summarizes.
Location: `GS Users Manual` — https://usermanual.wiki/Pdf/GSUsersManual.1012076781/html
Suggested use: primary reference for any GIF/GS implementation work. When
`ps2tek` and this manual disagree on a register detail, defer to the manual.
## VU User's Manual
- Official reference for VU0 and VU1.
- Defines the dual-pipeline 64-bit doubleword instruction format (upper +
lower pipe).
- Defines register files: 32 × 128-bit VF, 16 × 16-bit VI.
- Defines VU memories: VU0 has 4 KiB MicroMem0 + 4 KiB VU Mem0; VU1 has
16 KiB MicroMem1 + 16 KiB VU Mem1.
- Defines the two execution modes: micro mode (VU as standalone microprogram
engine) and macro mode (VU0 as EE COP2; VU1 usually in micro).
- Covers VIF-to-VU interaction enough to interpret microprogram upload paths.
Location: `VU User's Manual (Emotion Engine Vector Operation Unit Guide)` —
https://studylib.net/doc/25815876/vuusersmanual.158394566
Suggested use: primary reference for VIF/VU workstream (Codex workstream 4).
Re-read before locking any instruction-decode or pipeline-timing decision.
## Why these matter for FPGA planning
- Emulator source trees encode *one interpretation* of Sony's hardware. When
the RTL has to behave like silicon at a cycle or packet level, the original
manuals are the tiebreaker.
- Several non-GS "hacks" in PCSX2 exist because the emulator's floating-point
behavior diverges from the VU/EE spec. Reading the manual clarifies which of
those are true hardware quirks vs. emulator workarounds — a distinction that
matters more for FPGA than for software emulation.
## Caveats
- Both manuals are Sony confidential documents that leaked years ago. They are
the authoritative source on register semantics but were never officially
published. Treat them as technical reference, not as a licensing document.
- Version drift: the GS manual is v6.0 in the linked copy. Late-silicon
revisions may not be covered exhaustively.
references/supplemental/source_log.md
+87
View File
@@ -0,0 +1,87 @@
# Source Log — Supplemental Pass
Research pass date: 2026-04-16
Pass author: Claude (second research pass, after Codex)
This log covers sources introduced by the supplemental pass. It does not
re-list sources from `../source_log.md`; see that file for the Codex pass.
## Official Sony manuals
- `GS User's Manual v6.0` — Sony Computer Entertainment Inc.
URL: https://usermanual.wiki/Pdf/GSUsersManual.1012076781/html
Notes: primary register reference for the Graphics Synthesizer. Authoritative
for `0x12000000` privileged block and GS packet-form registers. Confidential
in origin.
- `VU User's Manual (Emotion Engine Vector Operation Unit Guide)` — Sony.
URL: https://studylib.net/doc/25815876/vuusersmanual.158394566
Notes: primary reference for VU0/VU1 pipeline, register files, memories,
micro/macro modes, and VIF coupling. Confidential in origin.
## FPGA prior art (adjacent consoles)
- `MiSTer-devel/PSX_MiSTer` — Robert Peip (FPGAzumSpass)
URL: https://github.com/MiSTer-devel/PSX_MiSTer
Notes: closest real-world methodology template. Methodology = cycle-accurate
software emulator first, RTL second, with emulator as golden model.
- `PS-FPGA/ps-fpga`
URL: https://github.com/PS-FPGA/ps-fpga
Notes: alternate PSX FPGA project. Useful for comparing module decomposition.
- `pgate1/PlayStation_on_FPGA`
URL: https://github.com/pgate1/PlayStation_on_FPGA
Notes: smaller-scale PSX FPGA. Reference for minimal scaffold shape.
## Architecture studies
- Rodrigo Copetti — "PlayStation 2 Architecture: A Practical Analysis"
URL: https://www.copetti.org/writings/consoles/playstation-2/
Notes: high-level pedagogical writeup. Onboarding reading, not a spec.
- `psdevwiki` PS2 section
URL: https://www.psdevwiki.com/ps2/
Notes: community-maintained counterpart to `ps2tek`. Strong on IOP modules,
SPU2, peripheral protocols, and hardware revisions.
- VPU Thesis — "A Study on the Feasibility of ... VU [on FPGA]"
URL: https://gamehacking.org/faqs/VPUThesis.pdf
Notes: academic FPGA-feasibility study specifically on the VU. Directly
relevant to Codex workstream 4.
- Wikipedia — PS2 / Emotion Engine
URLs:
https://en.wikipedia.org/wiki/PlayStation_2_technical_specifications
https://en.wikipedia.org/wiki/Emotion_Engine
Notes: orientation only.
## Community consensus threads
- MiSTer Forum — `Advanced cores for MiSTer future FPGA hardware`
URL: https://misterfpga.org/viewtopic.php?t=4884
- MiSTer Forum — `What Do You Think Will Happen Once MiSTer Reaches Its Limits?`
URL: https://misterfpga.org/viewtopic.php?t=2512
- Time Extension — `MiSTer Pi and next-generation FPGA gaming`
URL: https://www.timeextension.com/news/2025/03/the-next-generation-of-fpga-gaming-could-be-just-around-the-corner-thanks-to-mister-pi
Notes: capture the current community baseline. No public PS2 FPGA core
exists; consensus view places PS2 beyond current MiSTer-class fabric; only
active public effort is a hybrid PCIe-FPGA + host-CPU arrangement.
## Search deltas vs Codex pass
Sources Codex covered and this pass does not re-log:
- `ps2tek`, DobieStation `From Bits to Pixels` wiki, `ps2dev`, `ps2sdk`,
`gsKit`, `PCSX2`, `DobieStation`, `Play-`, `pcsx2/Memory.cpp`.
Sources this pass added that were absent from the Codex log:
- Sony GS User's Manual.
- Sony VU User's Manual.
- PSX_MiSTer, PS-FPGA, PlayStation_on_FPGA (adjacent-console FPGA prior art).
- Copetti architecture writeup.
- `psdevwiki` PS2 section.
- VPU thesis.
- MiSTer community consensus threads on PS2 feasibility.