# 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-