Console Backend skill

console-backend

The Backend Engineer makes the runtime under the recompiled game complete enough for it to run. The generated code is a literal translation of the game; everything it expects from the PS2 (the kernel, the SDK libraries, the disc, the I/O processor) has to exist in ps2xRuntime and ps2xIOP. Every missing piece shows up as a log line. This skill reads those lines, ranks them, and says which of the four fix tools applies and in which file.

Honest limits: the tool reads logs and the checkout; it does not write C++ for you. Some fixes are a one-line case in the dispatcher, others are a whole subsystem. A game usually stops at the first missing piece, so expect one fix per run early on, and fix in order.

${CLAUDE_SKILL_DIR} below is this skill's folder (where this SKILL.md lives).

python3 "${CLAUDE_SKILL_DIR}/stubs.py" scan console/runs/latest.log --repo ../PS2Recomp   # ranked fixes
python3 "${CLAUDE_SKILL_DIR}/stubs.py" scan console/runs/*.log --markdown                # table for STATE.md
python3 "${CLAUDE_SKILL_DIR}/stubs.py" handlers --repo ../PS2Recomp --grep sceCd         # real handler names
python3 "${CLAUDE_SKILL_DIR}/stubs.py" handlers --repo ../PS2Recomp --todo               # handlers still TODO
python3 "${CLAUDE_SKILL_DIR}/stubs.py" syscall 0x3C --repo ../PS2Recomp                  # name a syscall
python3 "${CLAUDE_SKILL_DIR}/stubs.py" syscall -0x1A                                     # interrupt variant

scan exits 1 when it finds something to fix and 0 on a clean log; every command takes --json.

What it reads and writes

File	What
runtime logs (console/runs/*.log from /console-tester, or saved stdout+stderr)	read, line by line, any size
ps2xRuntime/include/ps2_call_list.h (with --repo)	PS2_SYSCALL_LIST and PS2_STUB_LIST: the handler names a binding may use
ps2xRuntime/src/lib/Kernel/Syscalls/Dispatcher.cpp (with --repo)	which syscall number goes to which handler
ps2xRuntime/src/lib/Kernel/**/*.cpp (with --repo)	where each handler lives and which are still TODO_NAMED
stdout	the ranked list, or a Markdown table to paste into STATE.md's "Stubs and syscalls"

Without --repo it uses a built-in table of standard EE kernel syscalls and guesses files from names, and says so. Read reference/runtime-layers.md before the first fix of a session: the three layers, how a call reaches a handler, triage stubs, the IOP, disc I/O and the subsystem file map.

The layers, in short

Layer	What	Rule
Recompiled code	ps2xRuntime/src/runner/*.cpp, one C++ function per game function, dispatched by guest ADDRESS through one function table	never edited, never listed
Runtime	ps2xRuntime/src/lib/: kernel syscalls (Kernel/Syscalls/), SDK stubs (Kernel/Stubs/), memory, GS, VU, audio, pad, files; ps2xIOP/: the game's IRX modules	your fixes go in its .cpp files
Host	raylib (window, input, sound), the file system, FFmpeg	untouched

A bound stub calls a named handler; an unbound or skipped one logs Unimplemented PS2 stub called and throws; a syscall goes through Kernel/Syscalls/Dispatcher.cpp and an unknown number logs [Syscall TODO] and returns 0. Subsystem by subsystem, the first file to open is in section 7 of reference/runtime-layers.md (threads and semaphores, interrupts, SIF and modules, fio*, sceCd*, memory card, pad, audio, GS, movies, libc).

The method

1. Read STATE.md first (state.py show from /console-reverse): the phase, the runner command, the stub table, the open strikes.
2. Get one log per run. /console-tester (run.py boot) keeps them in console/runs/; by hand, run the command from STATE.md with a short timeout and save stdout and stderr.
3. Scan it: stubs.py scan <log> --repo <PS2Recomp>. Issues come in the order they first appeared. The first one usually caused the stop ("ended the run"); later ones can be consequences. Note that unknown syscalls do not stop the game (the runtime returns 0), so an early [Syscall TODO] is a prime suspect for a strange crash later.
4. Pick the fix tool the scan names, then check it in the source before writing anything:

The log says	Fix tool	Where
a handler that is still TODO_NAMED	Runtime C++	its Kernel/Stubs/<File>.cpp
sub_XXXXXXXX or a name with no handler	TOML	bind "<Handler>@0xADDR", or recompile it if it is game code, or ret0@ for one run to classify it
a handler that works but logged anyway	TOML	it is in skip: move it to stubs
[Syscall TODO]	Runtime C++	a case in Kernel/Syscalls/Dispatcher.cpp (+ the handler in Kernel/Syscalls/<File>.cpp)
missing function, codeRegion=yes	Recompiler	entry_points hint in the TOML, then re-run ps2_recomp (batch them)
missing function, codeRegion=no	Investigate	overlay, second program or bad pointer: the caller at RA-8
[IOP/RPC trace:unhandled]	IOP	is the IRX on the extracted disc and loaded? then ps2xIOP imports
sceCdSearchFile failed	Disc files	the file, the extraction, the run path
sceCdRead unresolved LBN	Game override	point cdImage at the user's own plain .iso
fatal exception: Unhandled ... at 0x.. raw=0x..	Game override	replace that function; record it as an upstream issue

5. Triage stubs are temporary. ret0@/ret1@/reta0@ only answer "does it get further if this succeeds?". Record each one in STATE.md as TEMPORARY and promote it: bind the real handler, implement the TODO handler, or write an override. Never leave one on a function that allocates memory, creates a thread or carries game logic.
6. Prefer fixes that do not touch headers. Implementing an existing TODO handler or adding a dispatcher case rebuilds the runtime library only. A new name in PS2_STUB_LIST (ps2_call_list.h) rebuilds every generated file: ask first, or put the body in a game override with runtime.replaceFunction(addr, fn) instead.
7. Every replacement function returns with ctx->pc = getRegU32(ctx, 31); unless it calls the original. Arguments are getRegU32(ctx, 4..7), results setReturnU32/S32, guest pointers getMemPtr(rdram, addr) (null when invalid).
8. Build through /console-reverse's build gate, run, scan again, and compare with the previous log (/console-tester triage.py compare). Fixed: update the row in STATE.md and log one line. Same stop after a fix: state.py strike; at three strikes, stop guessing (circuit breaker).

Write C++ only after the adversarial check from /console-reverse: what you will change, why it fixes the cause, what it could break, and whether you read the code or remembered it.

IOP and disc I/O in one paragraph each

IOP. ps2xIOP runs the game's own IRX modules from the extracted disc on an R3000A interpreter, with generic HLE services only for MCSERV, LIBSD and DBCMAN. [SIF module] load-emulated ... lines show what loaded. An unhandled SID means the serving module is missing, failed to load, or needs an import the virtual IOP kernel lacks (ps2xIOP/src/emulator/). No BIOS is involved or wanted.

Disc and files. cdrom0: is the folder of the ELF passed to the runner, mc0/ sits beside it, and the runtime matches names as written (on Linux, case matters). Replacing a file in the extracted folder swaps it in the game, no ISO rebuild. Games that read raw sectors need a plain 2048-byte .iso of the user's own disc set as cdImage in a game override (reference/runtime-layers.md has the snippet; iso.py plain in /console-reverse converts a raw .bin).

Guard rails

• Bring your own game. Only games the user owns, dumped from their own disc. Never download ISOs, ELFs, IRX modules or BIOS files, never help find them, never ask for them. PS2Recomp needs no BIOS, and neither do these fixes.
• Nothing from the game gets published. Logs can quote game strings and paths: keep them local. The disc, the ELF, the IRX modules and the recompiled C++ stay on the user's machine; runtime fixes you write are yours to share (they contain no game code), as are overrides that only hold addresses and your own logic. Upstream issues carry an address and an instruction word, never game files.
• Not affiliated with Sony. PlayStation is a trademark of Sony Interactive Entertainment.
• Skill-specific: never edit generated runner/*.cpp or list runner/; never edit a header without the user's OK; never clean the build; read-only access to the checkout from these tools.

Hands off to

/console-tester to run again and compare logs, /console-reverse for entry points, re-exports, recompiles and the build gate, /console-mod when the fix is a game-specific override, /console-controller, /console-graphics, /console-sound and /console-saves when the first issue sits in their subsystem.