architecture

Architecture & Repository Layout

Where things live in the repository, how a build turns them into one PS2 ELF, and the runtime rules that keep the console stable.

Repository layout

Path	Contents
src/, include/	The EE application. dash_*.c is the dashboard (home, apps, files, tools, settings, themes, sound, worker thread, PNG/JPEG viewers, widgets); filer*.c is the File Browser and copy engine; main*.c is boot, MISC command dispatch and info screens; config*.c is classic LAUNCHELF.CNF and network settings; init.c loads and resets IOP driver stacks on demand; cloud_http.c, cloud_google.c, self_update.c, update_psu.c are the native HTTPS, Google Drive and updater code; mmce_backup.c, mmce_igr.c, mc_card_export.c are backup/recovery; neutrino_iso.c, popstarter*.c, ember*.c are the external-core handoffs; remote_control.c and pc_game_receiver.c are the PC file protocols; hdd*.c and hdl_rpc.c are APA/HDL management; pad.c/pad_ds34.c are controller input; embed_blobs.S embeds plain binary payloads.
iop/	IOP (I/O processor) modules. Source-built with ps2.yaml targets: udpfs_smap, ps2ips_rpc (vendored PS2IP socket RPC server used by dashboard network clients such as clock sync), usbd-ra, mmceman, vmcman, ps2hdd_osd, ata_bd, hdl_info, xparam, AllowDVDV, dev9_poweroff, ps2host (PS2Link file I/O), oldlibs/ps2ftpd, pccf (PC CARD CF). Optional ds34usb/ds34bt for the DualShock variant. __precompiled/ holds only the UDPFS ministack and ioman peers (embedded) and the defective historical udpfs_smap.irx that the check script verifies is not embedded; every other module is a ps2.yaml target or an SDK package. __v10/ holds the PS2SDK v1.0 DEV9/PS2IP fallback pair.
ee_libs/	EE libraries built by ps2.yaml because the SDK does not supply them in a usable form: iopreboot (SifIopRebootBuffer) and hdd (libhdd). Sound uses the SDK audsrv-compat package and the SDK audio driver, not code in this tree.
loader/, igr/	Two small separate ELFs embedded into the main one. loader is the ELF loader linked into the low-memory window 0x84000..0xa0000; igr/wle_igr.c is the WLE-IGR trampoline installed for OPL Exit-to returns.
exploits/, res/, Lang/	Embedded payloads: memory-card exploit installer files (installer); UI sound effects, updater CA, BGM sidecar, button icons and the cloud config template; the nine built-in language tables.
scripts/	Build helpers, CI checks, packaging, release notes, wiki sync and host tools. See Building from Source.
tests/	Host-side regression tests (plain Python scripts, many compiling production C against stubs). See Contributing & Testing.
docs/, docs-site/	Maintainer notes and wiki guides in docs/; the published website source in docs-site/ (content/*.html, manifest.json, static/, build.py).
windows/, research/, __Headers/	The optional Windows rclone cloud relay; a non-shipping sd2psXtd restore-transaction reference model; sample APA injection headers.
.github/, .claude/	Workflows (compile.yml, docs-pages.yml, sync-wiki.yml), the issue form, and the Claude cloud-session hook.
ps2.yaml, iop/pccf/ps2.yaml	PS2BUILD project definitions (the only build path).

How the build fits together

ps2.yaml declares IOP targets, EE libraries, the loader, the WLE-IGR helper and the main wLaunchELF target. IOP modules built here, SDK driver packages and the loader/IGR ELFs are listed under embed_irx: and become byte arrays inside the main ELF; plain files are embedded by src/embed_blobs.S. Feature flags (MMCE, MX4SIO, ETH, UDPFS, EXFAT, ILINK, DVRP, XFROM, DS34, WLE_NATIVE_CLOUD and others) are defines: on that target and gate code with #ifdef. The DualShock build is generated from the same file, so the two variants cannot drift. Everything is then packed with ps2pack and wrapped into the ZIP/PSU packages. Full commands are in Building from Source.

Runtime rules

• One shell. main() performs early boot, input and display initialization, optional IGR backup, then calls DashRun(), which never returns. Settings, the File Browser, HDD Manager, Text Editor and exploit installer are dashboard screens.
• Lazy drivers. Embedding a module only places it in the ELF; init.c decides when to load it, and each load_* function checks whether the stack is already resident. Nothing for USB, ATA/HDD, MMCE, MX4SIO, iLink, networking or controllers beyond the pad driver starts until a screen needs it.
• Exclusive stacks. Some families cannot coexist (ETH versus UDPFS networking, MMCE versus MX4SIO on the same SIO2 bus, PS2 versus PSX HDD stacks, the PC CARD CF driver versus DEV9). Switching between them normally resets the IOP and clears residency tracking so the next access reloads what it needs (the PSX APA/DVR HDD stacks are the exception: they load without a reset). Neutrino quick-boot reuses the mounted stack; Ember's USB path performs a controlled clean rebuild first.
• Background worker. One EE thread (dash_worker.c) runs queued file, memory-card and driver jobs at lower priority; while it runs the UI thread does no I/O of its own, jobs never draw or show dialogs, and completion callbacks run back on the UI thread. Anything that reboots the IOP or launches an ELF first drains the queue. Some USB and device probes are still synchronous IOP calls and can block on failing hardware.
• Persistence. The dashboard never edits LAUNCHELF.CNF; it writes DASHBOARD.CNF, DASHAPPS.CNF and DASHLIB.CNF next to the loaded configuration or in mc0:/SYS-CONF/, with explicit Save/Discard semantics.
• Safety first for backups. MMCE history is written to .PART files, verified and renamed; recovery produces new files and never overwrites an active card; direct restore stays disabled (research/sd2psxtd is a reference model only and is not linked into any ELF).

Refactoring status

The oversized legacy files have been split along behavior-neutral lines: main.c into main_actions, main_boot, main_modules, main_menu, main_info_screens, main_gameid and others; filer.c into filer_device, filer_mount, filer_fileops, filer_actions, filer_browser, filer_copy, gui_sort, gui_texteditor, gui_hdd0_format and psu_functions; PSU layout structs are shared via include/psu_types.h. The legacy SMB and classic JPG-viewer subsystems were removed; images are viewed by the dashboard's bounded PNG (dash_png.c) and JPEG (dash_jpeg.c, libjpeg-turbo) decoders. The largest hand-written files now are dash_settings.c, dash_browser.c, init.c, main_exploit_installer.c and filer_browser.c (make stale-audit lists the top ten). Keep each further split behavior-neutral and verify it in an emulator and on real hardware.

Maintainer notes

More detail for maintainers lives in docs/architecture-maintenance.md, docs/BUILDING.md, the dashboard reference docs/dashboard.md and the dated plans and audits under docs/plans/.