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/README.md
+36
View File
@@ -0,0 +1,36 @@
# PS2 Reference Notes
This folder is a planning-oriented reference bundle for the `retroDE_ps2`
core. It is not meant to be an exhaustive PS2 encyclopedia; it is meant to
collect the implementation details that are likely to matter when we turn this
into an FPGA project.
Files in this folder:
- `hardware_overview.md`: PS2 subsystem map, memory map, and boot flow notes.
- `software_and_emulators.md`: Open-source SDK, graphics libraries, and
emulator projects worth mining for behavior and test ideas.
- `implementation_workstreams.md`: A subsystem-by-subsystem map of what the
project would need to account for, plus an `ao486` comparison.
- `source_log.md`: Source list with URLs and short notes.
- `supplemental/`: Second-pass additions (Claude). Primary Sony manuals,
PSX-on-FPGA prior art as methodology templates, academic / community
feasibility material. See `supplemental/README.md`.
Suggested reading order:
1. `hardware_overview.md`
2. `implementation_workstreams.md`
3. `software_and_emulators.md`
Notes:
- These notes favor primary or near-primary technical sources where possible:
emulator source trees, SDK/toolchain repos, and low-level hardware
references.
- Some PS2 knowledge still lives in community documentation rather than
official Sony publications. Where that is the case, the source is called out
clearly.
- I did not find a credible open-source HDL PS2 core during this pass. The
public material that surfaced is overwhelmingly emulator, homebrew SDK, and
reverse-engineering documentation.
references/hardware_overview.md
+158
View File
@@ -0,0 +1,158 @@
# PS2 Hardware Overview
This file is the quick architectural map for planning. The intent is to answer
"what major machines exist inside the PS2, how do they talk, and what has to
be present before software can do anything useful?"
## Big Picture
At a high level, the PS2 is not "CPU + GPU + RAM" in the simple console sense.
It is closer to a small multiprocessor system with a graphics subsystem tightly
coupled to DMA and vector processing:
- EE / R5900: main CPU.
- COP0, COP1, and MMI behavior: system control, floating point, multimedia
instructions.
- VU0 and VU1: vector processors with local code/data memories.
- VIF0 and VIF1: vector data upload / unpack / microprogram path.
- DMAC: central movement engine for many peripherals.
- GIF: packet formatter / path arbiter into the GS.
- GS: fixed-function graphics processor with its own VRAM.
- IPU: MPEG video decode block.
- IOP: separate MIPS-based I/O CPU with its own RAM and peripherals.
- SPU2: audio DSP / RAM / DMA complex.
- SIF: EE<->IOP communication path.
- CDVD, SIO2, DEV9, USB, FireWire, memory cards, controllers: IOP-side
peripherals.
- BIOS ROM: shared system firmware image visible to both EE and IOP.
The organizing lesson is that a PS2 bring-up is fundamentally a fabric problem
as much as a CPU problem. Data movement and coprocessor interaction are central.
## Memory Map
The most useful condensed map from a core-planning standpoint is the one in
`ps2tek`.
### EE virtual/physical view
- `0x00000000 -> 0x00000000`: 32 MiB main RAM.
- `0x20000000 -> 0x00000000`: uncached mirror of main RAM.
- `0x30100000 -> 0x00100000`: accelerated uncached RAM window.
- `0x10000000`: EE I/O registers.
- `0x11000000`: VU memories.
- `0x12000000`: GS privileged registers.
- `0x1C000000`: 2 MiB IOP RAM.
- `0x1FC00000`: 4 MiB BIOS.
- `0x70000000`: 16 KiB scratchpad RAM, virtual-only.
### IOP physical view
- `0x00000000`: 2 MiB IOP RAM.
- `0x1D000000`: SIF registers.
- `0x1F800000`: I/O register block.
- `0x1F900000`: SPU2 registers.
- `0x1FC00000`: shared BIOS ROM.
### Additional memories
- 4 MiB GS VRAM.
- 2 MiB SPU2 work RAM.
- 8 MiB memory card capacity per card.
## Important register clusters
These are the blocks that look most relevant for staged hardware bring-up:
- EE timers: `0x100000xx` through `0x100018xx`.
- IPU registers/FIFOs: `0x10002000`, `0x10007000`, `0x10007010`.
- GIF registers/FIFO: `0x10003000` block and `0x10006000`.
- EE DMAC channels:
- VIF0 ch0
- VIF1 ch1
- GIF ch2
- IPU_FROM ch3
- IPU_TO ch4
- SIF0 ch5
- SIF1 ch6
- SIF2 ch7
- SPR_FROM ch8
- SPR_TO ch9
- INTC: `0x1000F000` / `0x1000F010`.
- SIF registers: `0x1000F200` block on EE, `0x1D000000` block on IOP.
- GS privileged registers: `0x12000000` block, including `PMODE`,
`DISPLAY1/2`, `DISPFB1/2`, `BGCOLOR`, `GS_CSR`, `GS_IMR`.
- IOP DMA channels include CDVD, SPU2, DEV9, SIF0/1, and SIO2.
## Boot and Firmware Flow
The BIOS is not just a ROM blob we fetch instructions from. It also contains an
IOP bootstrap path and module-loading logic that matters for system bring-up.
Key points from `ps2tek`:
- The EE starts from BIOS space.
- The BIOS contains `IOPBOOT`, which is responsible for finding and parsing
`IOPBTCONF`.
- `IOPBTCONF` is the module list for IOP startup. It includes core IOP modules
such as `SYSMEM`, `LOADCORE`, interrupt handling, DMA management, timer
management, and more.
- The first loaded IOP module is `SYSMEM`, which sets up IOP-side memory
allocation.
What that means for planning:
- "BIOS fetches correctly" is only the first step.
- A useful early bring-up target is likely "EE reaches BIOS code and the IOP
bootstrap flow begins in a recognizable way."
- If the eventual project uses a real dumped BIOS, boot behavior will stress
more than just the EE core. It will quickly exercise memory mapping, DMA,
SIF, and IOP startup assumptions.
## Graphics Path Summary
A simplified practical view of the graphics data path:
1. EE code prepares packets.
2. DMAC moves packet data, often to GIF.
3. GIF arbitrates PATHs and reformats command/data traffic.
4. GS consumes packets, updates VRAM, and drives the PCRTC/display path.
The DobieStation "From Bits to Pixels" article is especially useful here: it
frames the first visible output as a memory-map plus DMAC plus GIF plus GS
problem, not merely a CPU problem.
## Audio / Peripheral Side Summary
The IOP side owns much of what makes the console feel complete:
- controller and memory card traffic via SIO2 and BIOS/IOP modules,
- SPU2 audio and SPU2 DMA,
- CD/DVD access,
- DEV9 expansion functions such as HDD/network in supported setups,
- USB / FireWire blocks.
This matters because a core can "boot code" long before it can convincingly
behave like a PS2.
## Planning Implications
From an FPGA-port perspective, the PS2 naturally breaks into these bring-up
layers:
1. Address map, RAM/ROM visibility, reset, and exception vectors.
2. EE execution plus enough COP0 behavior for BIOS progress.
3. DMAC, GIF, GS privileged register access, and some display proof-of-life.
4. IOP boot path and SIF interaction.
5. VIF/VU behavior sufficient for real software.
6. SPU2, SIO2, CDVD, DEV9, and the broader "console completeness" layer.
That layering is a big reason this project feels closer to `ao486` than to
`nes` or `gb`. The challenge is not one datapath; it is many cooperating
subsystems with firmware-visible contracts.
## Source Pointers
- `ps2tek`: https://psi-rockin.github.io/ps2tek/index.html
- DobieStation wiki, "Making a PS2 Emulator: From Bits to Pixels":
https://github.com/PSI-Rockin/DobieStation/wiki/Making-a-PS2-Emulator%3A-From-Bits-to-Pixels
references/implementation_workstreams.md
+268
View File
@@ -0,0 +1,268 @@
# PS2 Implementation Workstreams
This file is the planning map for "what would we actually have to account for?"
It is deliberately biased toward project decomposition rather than hardware
history.
## Executive Take
`ao486` is a reasonable organizational comparison, but only partially.
Why the comparison fits:
- both projects are full-system bring-ups, not narrow cartridge-style cores,
- both need firmware-aware boot behavior,
- both need host/media integration,
- both benefit from strong subsystem boundaries and platform glue isolation,
- both will need serious debug instrumentation.
Why the comparison breaks:
- PS2 leans harder on DMA orchestration and coprocessor interaction,
- PS2 has a more central "packetized graphics path" problem,
- PS2 has a stricter dual-CPU story with visible EE<->IOP coordination,
- PS2 includes vector units and fixed-function graphics behavior that are not
naturally analogous to a PC chipset.
My planning conclusion: treat this as `ao486`-class or harder, but not
`ao486`-shaped internally.
## Workstream Map
### 1. Platform shell integration
Needed work:
- retroDE top-level wrapper,
- clock/reset sequencing,
- HDMI/video adaptation strategy,
- audio output integration,
- HPS bridge register map,
- manifest/backend planning.
Questions:
- What clocks are generated locally versus inherited from the shared shell?
- Does the first implementation target native-like timings internally and adapt
outward, or simplify early output into a framebuffer path?
### 2. Main memory architecture
Needed work:
- 32 MiB EE main RAM behavior,
- 2 MiB IOP RAM behavior,
- 16 KiB scratchpad behavior,
- GS VRAM model,
- SPU2 RAM model,
- BIOS ROM visibility,
- arbitration between execution units, DMA, and graphics paths.
This is one of the hardest planning areas because the PS2 is not just "shared
DDR plus a CPU." Memory placement, visibility, and access rules are part of the
software contract.
### 3. EE / R5900 core
Needed work:
- MIPS III base behavior,
- relevant MIPS IV extensions,
- MMI instructions,
- exception / interrupt behavior,
- COP0 system behavior,
- FPU behavior and edge cases,
- TLB / mapping behavior or a scoped approximation if a staged bring-up allows.
A key planning question is whether there is any reusable R5900 implementation
candidate, or whether the project would require a major custom core effort.
### 4. VU / VIF complex
Needed work:
- VU0 and VU1 execution model,
- local code/data memories,
- microprogram upload path,
- VIF unpack / packet interpretation,
- synchronization rules between EE, VIF, VU, and GIF.
This is a major reason the project is not just "CPU + GPU." A lot of PS2-era
software performance depends on this path.
### 5. DMAC
Needed work:
- per-channel register behavior,
- channel scheduling / priority,
- stall / ring / status behavior,
- GIF, VIF, SIF, IPU, and scratchpad transfer semantics,
- interrupt generation.
If the DMAC is wrong, everything looks randomly broken. This is likely a
top-tier subsystem for instrumentation and standalone tests.
### 6. GIF + GS
Needed work:
- GIF tag/path handling,
- PATH prioritization behavior,
- GS command/register decode,
- VRAM layout / swizzle / formats,
- framebuffer / zbuffer behavior,
- display controller / output timing strategy,
- enough rendering fidelity to pass real software.
This is probably the subsystem most likely to dominate bring-up time after the
CPU/memory base exists.
### 7. IOP subsystem
Needed work:
- IOP CPU behavior,
- IOP RAM and I/O space,
- IOP DMA engine,
- interrupt/timer behavior,
- module boot expectations from BIOS,
- PS1-legacy-derived hardware blocks used in PS2 mode.
For planning purposes, the IOP should be treated as a real subsystem, not as
"peripheral glue."
### 8. SIF and EE<->IOP coordination
Needed work:
- SIF registers,
- DMA channels on both sides,
- command/flag behavior,
- RPC-visible behavior as exercised by system software.
This is likely one of the first places where "mostly works" breaks down when
moving from demos to real software.
### 9. Audio path
Needed work:
- SPU2 register behavior,
- SPU2 RAM behavior,
- DMA and AutoDMA cases,
- output mixing and timing,
- bridge into retroDE audio output.
A staged project might boot without accurate audio, but a believable PS2 core
cannot stop there.
### 10. Media and storage
Needed work:
- CDVD-visible behavior,
- optional HDD / DEV9 strategy,
- BIOS expectations around media presence,
- HPS-side image mounting or file-backed emulation.
This is one of the best arguments for an `ao486`-style host integration layer.
Media handling will almost certainly live partly on the HPS side.
### 11. Input and memory cards
Needed work:
- SIO2-visible controller path,
- memory card protocol / presence behavior,
- mapping retroDE input stack to DualShock-compatible semantics.
The good news is the retroDE platform already contains wired DualShock 2
controller work. That may help at the platform-input layer, even though it does
not solve PS2 console-side SIO2 semantics by itself.
### 12. BIOS / firmware strategy
Questions to settle early:
- Real dumped BIOS only?
- Any HLE stubs for debug-only bring-up?
- What is the policy for user-supplied ROM images and module assets?
This decision changes the bring-up plan significantly. A real BIOS path is more
authentic and more demanding. An HLE debug path may shorten early validation but
adds its own maintenance burden.
### 13. Debug and verification infrastructure
Needed work:
- trace taps for EE fetch/decode/exception flow,
- DMAC channel traces,
- GIF/GS packet capture,
- IOP/SIF event logging,
- golden-reference comparison points against emulators,
- tiny directed tests for memory map, DMA, VIF, GS, and SIF.
This project should probably assume that debug plumbing is a first-class feature,
not an afterthought.
## Suggested phased plan
### Phase 0: architecture lock
- choose upstream/reference strategy,
- choose BIOS policy,
- choose host/media policy,
- choose first display strategy,
- define subsystem boundaries.
### Phase 1: scaffold and observability
- create repo skeleton,
- define register/bridge map,
- add debug plumbing and trace formats,
- decide validation harnesses.
### Phase 2: minimal EE boot
- RAM/ROM map,
- reset vectors,
- enough EE behavior for BIOS progress,
- proof-of-life traces.
### Phase 3: first graphics proof
- minimal DMAC + GIF + GS path,
- simple visible output,
- likely driven by tiny test payloads before commercial software.
### Phase 4: IOP and SIF
- IOP bootstrap,
- SIF messaging and DMA,
- enough coordination for deeper BIOS progress.
### Phase 5: completeness layers
- VIF/VU correctness,
- SPU2,
- CDVD / DEV9 / storage,
- controller and memory card semantics,
- broader software compatibility work.
## Bottom line
If the question is "is this closer to `ao486` than to the simpler retroDE
cores?", the answer is yes.
If the question is "can we mostly copy the `ao486` strategy and just swap the
payload?", the answer is no.
The safe way to start is:
1. treat PS2 as a full-system architecture project,
2. lock memory / firmware / host integration decisions early,
3. build around subsystem ownership and instrumentation,
4. aim for staged proof-of-life milestones instead of "boots games" as the
first success bar.
references/software_and_emulators.md
+148
View File
@@ -0,0 +1,148 @@
# PS2 Software and Emulator References
This file tracks software-side sources that are useful for implementation
planning, test generation, and behavioral cross-checking.
## Homebrew SDK / Toolchain
### `ps2dev`
The modern community toolchain entry point is `ps2dev`. As of this research
pass, the project is still actively maintained and distributes a build/install
flow for:
- `ps2toolchain`
- `ps2sdk`
- `ps2sdk-ports`
- `gsKit`
Why this matters for FPGA work:
- It gives us a realistic software stack for directed tests and homebrew
smoke tests.
- It provides a path for EE-side and IOP-side sample programs.
- It gives us a straightforward way to assemble minimal bring-up artifacts
without depending on commercial game software.
### `ps2sdk`
`ps2sdk` is especially important because it reflects the software-visible split
of the platform:
- `ee/`: EE-side APIs and startup.
- `iop/`: IOP-side modules and APIs.
- `common/`: shared definitions.
- `samples/`: useful test and bring-up material.
The README explicitly notes that the PS2 has two independent CPUs and that the
source tree is split accordingly. That is not just a software organization
detail; it mirrors the hardware architecture we would be trying to realize.
### `gsKit`
`gsKit` is a low-level C interface to the Graphics Synthesizer and includes
`dmaKit` for DMAC usage. It is useful for:
- GS initialization studies,
- GIF/DMAC packet expectations,
- simple graphics smoke tests,
- learning what a "minimal working GS path" looks like from software.
For staged bring-up, `ps2sdk + gsKit` may be one of the best ways to generate
small, understandable graphics test payloads.
## Emulator Landscape
### PCSX2
PCSX2 is the longest-running open-source PS2 emulator in this source set. Its
README describes the project as emulating PS2 hardware using:
- MIPS interpreters,
- dynamic recompilers,
- a VM that manages hardware state and PS2 system memory.
Why it matters:
- It is a strong reference for edge cases and practical compatibility behavior.
- Its memory subsystem and hardware models can point us toward the parts of the
PS2 that real software stresses hardest.
- It is likely the deepest public implementation well for subtle behavior, even
if an FPGA port should not blindly mirror emulator design choices.
One useful immediate note from `pcsx2/Memory.cpp`: the file header still carries
an implementation-focused summary of the EE-visible RAM, scratchpad, and BIOS
regions, which is a good signpost when cross-checking memory assumptions.
### DobieStation
DobieStation is valuable because it also publishes a concise explanatory writeup
for early PS2 emulator bring-up. The strongest planning takeaway from its
"From Bits to Pixels" article is that first-frame graphics on PS2 already
requires:
- a correct-enough memory map,
- EE execution,
- DMAC channel behavior,
- GIF transfer handling,
- GS-side behavior.
That writeup is useful because it compresses the "minimum viable visible PS2"
problem into a few concrete dependencies.
### Play!
Play! is useful as a contrasting design point:
- it uses a built-in HLE BIOS instead of requiring an external BIOS dump,
- it targets many host platforms including mobile and web,
- it documents some practical issues around JIT and page protection.
Even though a retroDE FPGA core is unlikely to follow Play!'s HLE BIOS path,
Play! is still a good reminder that firmware strategy is a first-order
architectural decision, not an implementation detail.
## What these projects are good for
### Best sources for behavior questions
- PCSX2
- DobieStation
- `ps2tek`
### Best sources for test payloads and small samples
- `ps2sdk`
- `gsKit`
- broader `ps2dev` stack
### Best sources for boot and user-visible software assumptions
- dumped BIOS behavior as described in `ps2tek`
- emulator boot flows
- homebrew SDK samples
## Likely validation strategy
If this becomes a real implementation effort, these software sources suggest a
validation ladder:
1. Run tiny EE-side tests that only touch RAM and simple I/O.
2. Run `gsKit`-style minimal graphics payloads for first visible output.
3. Run BIOS-only boot traces and compare major milestones with emulator traces.
4. Add IOP/SIF-sensitive homebrew.
5. Only then move into complex game software.
## Source Pointers
- `ps2dev`: https://ps2dev.github.io/
- `ps2dev` repo: https://github.com/ps2dev/ps2dev
- `ps2sdk` repo: https://github.com/ps2dev/ps2sdk
- `gsKit` repo: https://github.com/ps2dev/gsKit
- PCSX2 repo: https://github.com/PCSX2/pcsx2
- PCSX2 memory source:
https://raw.githubusercontent.com/PCSX2/pcsx2/master/pcsx2/Memory.cpp
- DobieStation repo: https://github.com/PSI-Rockin/DobieStation
- DobieStation wiki article:
https://github.com/PSI-Rockin/DobieStation/wiki/Making-a-PS2-Emulator%3A-From-Bits-to-Pixels
- Play! repo: https://github.com/jpd002/Play-
references/source_log.md
+69
View File
@@ -0,0 +1,69 @@
# Source Log
Research pass date: 2026-04-16
This log records the main sources used to build the planning notes in this
folder.
## Hardware and low-level behavior
- `ps2tek - Documentation on PS2 internals`
URL: https://psi-rockin.github.io/ps2tek/index.html
Notes: best low-level consolidated hardware reference found in this pass;
useful for memory map, register blocks, BIOS structure, IOP boot modules,
DMA channels, and subsystem inventory.
- `Making a PS2 Emulator: From Bits to Pixels`
URL:
https://github.com/PSI-Rockin/DobieStation/wiki/Making-a-PS2-Emulator%3A-From-Bits-to-Pixels
Notes: strong practical explanation of the minimum pieces needed for first
visible output; especially helpful for framing memory map + DMAC + GIF + GS.
## SDK, tooling, and software-visible platform shape
- `ps2dev`
URL: https://ps2dev.github.io/
Notes: community entry point for PS2 homebrew development.
- `ps2dev/ps2dev`
URL: https://github.com/ps2dev/ps2dev
Notes: active toolchain/build umbrella for `ps2toolchain`, `ps2sdk`,
`ps2sdk-ports`, and `gsKit`.
- `ps2dev/ps2sdk`
URL: https://github.com/ps2dev/ps2sdk
Notes: important because it exposes the software-facing EE/IOP split and
offers samples and platform libraries.
- `ps2dev/gsKit`
URL: https://github.com/ps2dev/gsKit
Notes: low-level GS interface library; useful for understanding software-side
GS initialization and DMAC usage.
## Emulator projects
- `PCSX2/pcsx2`
URL: https://github.com/PCSX2/pcsx2
Notes: deepest and longest-running open-source PS2 emulator in this pass.
- `PCSX2 Memory.cpp`
URL: https://raw.githubusercontent.com/PCSX2/pcsx2/master/pcsx2/Memory.cpp
Notes: useful implementation-side memory summary and a signpost for how a
mature emulator structures host-visible EE/IOP/VU memory.
- `PSI-Rockin/DobieStation`
URL: https://github.com/PSI-Rockin/DobieStation
Notes: helpful as a second emulator reference and because it publishes useful
implementation commentary.
- `jpd002/Play-`
URL: https://github.com/jpd002/Play-
Notes: useful contrasting design point; uses a built-in HLE BIOS rather than
external BIOS dumps.
## Search outcome note
I specifically looked for credible open-source HDL / FPGA PS2 core material.
This pass did not surface a meaningful public RTL implementation. The strongest
public sources that appeared were emulator codebases, PS2 homebrew tooling, and
reverse-engineering references.
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.