Step 34 · First contribution · D1
The developer curriculum
A source-grounded route from understanding KytyPS5 to making and verifying a focused contribution.
Before this page: Building, linking & debugging · ELF to first guest instruction · One draw to GPU completion. View the learning route.
This is a route from reading the emulator to making a defensible change. It is pinned to d2413fc2 (7 October 2026), not a guarantee about future main. The traces follow selected real source paths; the labs deliberately introduce caller mistakes in isolated fixtures. They do not demonstrate that a game works, and they do not claim upstream has these bugs.
Before you start
Before this contributor track, build a small C++20 executable, read pointers and half-open ranges, distinguish integers from addresses, and explain ownership and synchronization. If any are new, follow Start here through the beginner lessons, foundations and both source traces; read C4 before threaded changes. The project practice checklist is an optional companion for readers who already meet these prerequisites. Use the gates below as evidence of developer readiness.
Keep two roots distinct: this learning repository, and the emulator checkout at KytyPS5/. Run the native labs from the learning root. Run emulator build commands from the emulator root. The committed site can be served directly. Authors regenerate shared excerpts and navigation with the documentation script. Beginner labs need only CMake and a C++20 toolchain; these developer labs also use the emulator source checkout.
git -C KytyPS5 rev-parse HEAD git -C KytyPS5 status --short git status --short
Record the full source SHA, compiler, OS and test command. If your checkout differs, compare the named functions before trusting the trace. Do not reset an existing worktree just to match a lesson.
The developer route: pass by evidence
The core route has already introduced the boot and draw traces. Review that evidence here, then follow diagnostics, reading a run, the worked diagnosis, the debugging labs and your first change. The gates below assess evidence; they do not define a competing chapter order.
Ready for the developer route
These ticks record orientation, not completion of the later labs or capstone. Keep the evidence for those on their own lesson pages.
| Gate | Work | Evidence needed to pass |
|---|---|---|
| 0 · Orientation | Read the foundations and build material. Classify guest CPU code, HLE code, GPU command processing and host Vulkan work. | A source map with one owning function per boundary, plus a successful build of the standalone labs. |
| 1 · Boot | D2: ELF to first guest instruction. | An address worksheet, the ordered boot chain, and a correct distinction between module initialization, executable entry and main(). Static-only work is labelled as such. |
| 2 · One draw | D3: PM4 to completion. | A packet/state/binding/submission ledger. Identify the actual completion condition and one legal early-return path. |
| 3 · Memory correctness | Lab A: page coverage. | The original failing case, a local correction, and passing boundary/overflow checks. Explain why aligning size alone fails. |
| 4 · Lifetime and contracts | Lab B and Lab C. | Reproduce all three intentional failures, fix the marked callers, and justify error-path output preservation and completion-based retirement. |
| 5 · Contribution | A bounded first change, or a regression test for existing behavior. | A test that fails before and passes after, adjacent negative tests, a focused diff, and an honest report separating build, unit, integration and game evidence. |
A checked box records your progress, not certification. If a test passes only after weakening an assertion, disabling validation, skipping a draw, or inventing a success result, the gate has not been passed.
Coverage map: what you can learn here
Overview means orientation and source pointers. Guided trace follows a selected implementation path and its invariants. Executable lab has a deterministic oracle, but only within the stated fixture. Not covered names the next work instead of implying mastery. A detailed trace of one path is not comprehensive coverage of its subsystem.
| Area | Current depth and starting point | Still not covered in depth |
|---|---|---|
| C++, ABI, native guest execution | Foundations + C1–C4/C10; guided boot trace. | Complete x86 instruction semantics, all platform exception/unwind behavior and all patcher edge cases. |
| ELF, NIDs, relocation, TLS | Loading topics and D2; address arithmetic and actual source checkpoints. | Every ELF/SELF variant, every relocation type, exhaustive TLS and module unload/reload behavior. |
| Guest memory and coherency | Memory topics; executable alignment lab; draw ownership trace. | Full sparse/direct/flexible allocation proofs, all fault/replay interleavings, mapping races and stress coverage. |
| PM4 and ordinary graphics draws | PM4/register topics and guided non-indexed draw. | Every opcode, predication/indirect interactions, all metadata operations and every format/tiling mode. |
| Shader compilation and caches | Shader topic + C9 program cache; cache hit/miss checkpoints in D3. | Instruction-by-instruction compiler correctness, full SSA/CFG derivation, all SPIR-V emission and specialization cases. |
| GPU lifetime and synchronization | D3 completion trace + executable LRU caller lab. | Complete Vulkan synchronization/queue-family proof, GPU-driven stress tests, all download/page-manager races. |
| HLE and guest-visible contracts | First-change workflow + fictional output-contract lab. | All library contracts, pointer validation policy, real ABI integration for the fixture, full libc/kernel behavior. |
| APR, files, .zar and savedata | C5 overview; real test entry points in D4. | Step-by-step APR scheduler, cancellation/error semantics, SaveDataMemory2 persistence/recovery lab and archive corruption cases. |
| Audio, NGS2, video, input | C5 overview and owning-source references. | Codec/mixer routing internals, timing/resampling, microphone and haptics labs, AV sync and hardware matrix. |
| Tessellation and mesh | Source overview and branching notes in D3. | Complete tessellation/mesh traces. Tessellation is opt-in in this snapshot. |
| Ray tracing / BVH | C11: detailed research and implementation roadmap, with executable mathematical/encoding teaching fixtures. | Exhaustive node/encoding coverage, hardware conformance and game results. Full-float BVH32/BVH64 runs through software SPIR-V; A16/D16 and incomplete NSA forms remain unsupported. |
| Profiling, presentation, platforms | Debugging/performance topics and existing teaching diagrams. | Measured cross-driver benchmarks, full swapchain/video-out trace, launcher workflows and platform-specific conformance. |
Capstone: make one claim you can defend
Choose a small behavior whose contract you can establish. A regression test for a working subsystem is a valid contribution; a guessed HLE success stub is not automatically one. For memory work, start from a boundary case. For graphics work, narrow a mismatch to a specific draw, shader or binding before changing the compiler.
- Write the expected behavior, its source of evidence, and a falsifiable failure condition.
- Preserve the pre-change failure: exact input, source revision, output and exit status. Remove unrelated variables.
- Make the smallest fix; test ordinary, boundary and error behavior. Explain why the fix belongs at this layer.
- Inspect ownership and concurrency across callers. A correct return value can still conceal stale memory or early destruction.
- Build the affected targets. Run focused tests, then broader checks in proportion to the risk. Keep game verification separate and use your own lawful content if needed.
- Review the diff for accidental formatting, probes and unsupported claims. Follow upstream's contribution policy before submitting.
Evidence record to hand off
Source SHA / branch: Binary and symbols / compiler / OS: Claim and contract evidence: Minimal input and reproduction command: Before: actual result, exit code: After: actual result, exit code: Negative and boundary checks: Ownership / synchronization implications: Integration or game route, if tested: Not tested / remaining risks: Files changed and why:
Do not report “game fixed” from a unit test, “GPU completed” from a CPU log, or “all platforms supported” from one Windows build. Record missing evidence explicitly.
Keep the curriculum current
On an upstream update, compare the old and new source revisions, re-walk the functions named by D2/D3, rebuild the labs and re-run the documentation checks. Edit the owning topic paragraphs and docs/content/learning.json, regenerate shared copies and navigation with scripts/build-docs.cjs --write, then regenerate the search index. Review unique long-form explanations separately. A source-symbol check detects a renamed function, not a semantic change; manual review is still required.
node scripts/build-docs.cjs node scripts/check-beginner.cjs node scripts/check-docs.cjs node scripts/check-doc-examples.cjs node scripts/check-curriculum.cjs node scripts/build-search-index.cjs
The browser animations are bounded teaching models. They illustrate state transitions, not a replacement for actual source, debugger evidence, Vulkan validation or a guest behavior test.