chimera-gfx-Public/RESEARCH.md

# Research record

Evidence cutoff: **2026-07-17**. Only primary upstream repositories and release
metadata are used below. Each statement is labelled `FACT`, `INFERENCE`, or
`UNKNOWN`.

## Evidence snapshot

### PS5 Payload SDK

- **FACT:** release `v0.41` maps to commit
  `d2e2e585740362976a39fdd5ccf390f199a7bc37` and was published on
  2026-06-28. [Release](https://github.com/ps5-payload-dev/sdk/releases/tag/v0.41)
- **FACT:** GitHub's `releases/latest` endpoint still resolved to v0.41 on
  2026-07-17.
- **FACT:** GitHub release metadata reports `ps5-payload-sdk.zip` SHA-256
  `ebfb0acb5260511951a80e17db41650c62d20a8caf8659a230b928dc85005984`.
- **FACT:** `sce_stubs/libSceGnmDriver.c` contains 158 export stubs, including
  submit, draw, dispatch, compute-queue, embedded-shader, resource-registration,
  and synchronization-related names. The file is assembly labels only and does
  not establish C signatures. [Pinned stub](https://github.com/ps5-payload-dev/sdk/blob/d2e2e585740362976a39fdd5ccf390f199a7bc37/sce_stubs/libSceGnmDriver.c)
- **FACT:** the pinned SDK tree has no public GNM header and no GNM/GPU sample.
  Its only GNM-named source files are the driver stub sets.
- **FACT:** the SDK's `hello_dlfcn` sample demonstrates `dlopen`, `dlsym`, and
  `dlclose`; `hello_so` demonstrates shared-object linking/loading.
  [Dynamic-loading sample](https://github.com/ps5-payload-dev/sdk/blob/d2e2e585740362976a39fdd5ccf390f199a7bc37/samples/hello_dlfcn/main.c)
- **FACT:** the pinned payload CRT calls `__patch_init` before `main`;
  `crt/patch.c` writes process credential capability/attribute fields and
  syscall-address bounds through SDK kernel read/write primitives.
  [Pinned CRT startup](https://github.com/ps5-payload-dev/sdk/blob/d2e2e585740362976a39fdd5ccf390f199a7bc37/crt/crt.c)
  [Pinned patch code](https://github.com/ps5-payload-dev/sdk/blob/d2e2e585740362976a39fdd5ccf390f199a7bc37/crt/patch.c)
- **FACT:** the pinned rtld's SPRX path can call
  `sceKernelLoadStartModule`/`sceKernelStopUnloadModule`; the SPRX-specific
  `init` and `fini` callbacks are empty in SDK source, but the system calls'
  internal side effects are not established.
  [Pinned SPRX loader](https://github.com/ps5-payload-dev/sdk/blob/d2e2e585740362976a39fdd5ccf390f199a7bc37/crt/rtld_sprx.c)
- **FACT:** `crt/Makefile` partially links 12 source objects into `crt1.o`; the
  other six installed CRT-named files are empty archives at v0.41.
- **FACT:** the `prospero-clang` wrapper omits `crt1.o` for `-nostartfiles` and
  omits libc/kernel/Sce default libraries for `-nodefaultlibs`. An offline
  `-###` trace confirms both suppressions without producing an ELF.
- **FACT:** the SDK README points to external ELF-loader projects, but the exact
  loader used for firmware 9.60 and its caller source are not part of the SDK or
  the pinned local evidence set.
- **FACT:** unless otherwise marked, the SDK is GPLv3-or-later; FreeBSD headers
  retain their BSD licenses. [SDK README](https://github.com/ps5-payload-dev/sdk/blob/d2e2e585740362976a39fdd5ccf390f199a7bc37/README.md)

### PS5 SDL2 fork

- **FACT:** inspected commit
  `0baf4ac49382b537ba449901b5b6d0d189bb1fbb`, dated 2026-07-07.
  [Commit](https://github.com/ps5-payload-dev/SDL/commit/0baf4ac49382b537ba449901b5b6d0d189bb1fbb)
- **FACT:** `src/video/ps5` implements a CPU framebuffer/VideoOut path and an
  OSMesa context path. VideoOut registration and flip occur in the SDL backend,
  not in `chimera-gfx` Phase 0. [PS5 video](https://github.com/ps5-payload-dev/SDL/blob/0baf4ac49382b537ba449901b5b6d0d189bb1fbb/src/video/ps5/SDL_ps5video.c)
- **FACT:** that backend owns direct-memory allocation, buffer tiling,
  registration, flip submission, event waiting, and cleanup. Its public source
  declares opaque VideoOut structures with `junk` fields; those layouts are not
  copied into this project.
- **FACT:** SDL is Zlib-licensed at the pinned commit. The PacBrew recipe's
  `license=('LGPL')` metadata conflicts with upstream `LICENSE.txt`; this
  project follows the primary upstream license file.
- **FACT:** the native audio backend forces 48 kHz and uses AudioOut.
  [PS5 audio](https://github.com/ps5-payload-dev/SDL/blob/0baf4ac49382b537ba449901b5b6d0d189bb1fbb/src/audio/ps5/SDL_ps5audio.c)
- **FACT:** native PS5 source directories exist for joystick, keyboard/IME,
  filesystem, audio, video, and main; joystick code includes vibration and
  light-bar operations. [PS5 joystick](https://github.com/ps5-payload-dev/SDL/blob/0baf4ac49382b537ba449901b5b6d0d189bb1fbb/src/joystick/ps5/SDL_ps5joystick.c)

### PacBrew

- **FACT:** inspected commit
  `c2abcfcb60f569128abd0e8e70ad03a67bee5ea7`, dated 2026-07-07.
  [Repository](https://github.com/ps5-payload-dev/pacbrew-repo/tree/c2abcfcb60f569128abd0e8e70ad03a67bee5ea7)
- **FACT:** the SDL2 recipe enables `SDL_OPENGL` and `SDL_LOADSO` but follows an
  unpinned Git source with `sha256sums=('SKIP')`; this project therefore does
  not treat that recipe as reproducible pinning.
  [SDL2 recipe](https://github.com/ps5-payload-dev/pacbrew-repo/blob/c2abcfcb60f569128abd0e8e70ad03a67bee5ea7/SDL2/PKGBUILD)
- **FACT:** the Mesa 22.1.7 recipe enables OSMesa and gallium `swrast`, while
  Vulkan, EGL, GBM, GLX, and GLES are disabled.
  [Mesa recipe](https://github.com/ps5-payload-dev/pacbrew-repo/blob/c2abcfcb60f569128abd0e8e70ad03a67bee5ea7/mesa/PKGBUILD)
- **FACT:** package recipes exist for FBNeo, LakeSnes, Mednafen, DevilutionX,
  and EDuke32. Their presence proves port work, not native GPU acceleration.

### RetroArch

- **FACT:** inspected commit
  `32ee70cef5d4bdc32a4ca3b3b261209ce74b6e81`, dated 2026-07-16.
  [Commit](https://github.com/libretro/RetroArch/commit/32ee70cef5d4bdc32a4ca3b3b261209ce74b6e81)
- **FACT:** the tree contains an SDL2 video driver and dynamic-library support
  used for libretro cores. [SDL2 driver](https://github.com/libretro/RetroArch/blob/32ee70cef5d4bdc32a4ca3b3b261209ce74b6e81/gfx/drivers/sdl2_gfx.c)
- **FACT:** `Makefile.orbis`, `platform_orbis.c`, and an Orbis context driver are
  available as PS4 integration references.
- **INFERENCE:** those PS4 files are useful for frontend lifecycle and build
  concepts only. Their GPU assumptions must not be transferred to PS5.

### PS5 Linux

- **FACT:** inspected `ps5-linux-loader` commit
  `8e7dd40df6144bed6194d165d48aa9468a7e13f3`, dated 2026-07-10.
  [Repository](https://github.com/ps5-linux/ps5-linux-loader/tree/8e7dd40df6144bed6194d165d48aa9468a7e13f3)
- **FACT:** the loader targets a Linux kernel/initramfs boot flow and references
  patched Linux components.
- **INFERENCE:** Linux amdgpu/RADV progress demonstrates that the hardware can
  be driven under a custom Linux stack; it does not provide a native PS5
  userland ABI or a reusable driver implementation for this project.

## ABI evidence table

| Class | Area | Primary evidence | What the evidence supports | Policy |
|---|---|---|---|---|
| FACT | Export names | SDK `libSceGnmDriver.c` | names exist in the v0.41 stub set | resolve only |
| FACT | Target ISA | public SDK toolchain | compile target is x86-64 PS5 userland | does not prove a function ABI |
| INFERENCE | Runtime module name | stub filename plus SDK `.sprx` convention | `libSceGnmDriver.sprx` is a candidate | load only behind gates |
| UNKNOWN | GNM signatures | no pinned public header | no callable prototype is proven | never call |
| UNKNOWN | GNM structures | no pinned public definition | no layout is proven | never construct |
| UNKNOWN | Firmware stability | no public compatibility matrix | 9.60 is a build identifier, not known compatible firmware | 9.60 build only; never infer compatibility |
| FACT | SDK payload startup | pinned `crt/crt.c` and `crt/patch.c` | pre-main kernel process-state writes occur | execution blocked |
| FACT/UNKNOWN | SPRX loader lifecycle | pinned rtld source/system-module implementation boundary | load/start and stop/unload are requested; system internals unknown | offline audit only |
| UNKNOWN | Embedded-shader semantics | export names only | no identifier or binary contract | never call |
| UNKNOWN | Submission/sync semantics | export names only | no ownership or timeout contract | never call |
| FACT | SDL2 public API | pinned SDL headers and `LICENSE.txt` | application API and Zlib terms at that commit | Phase-1 candidate only |
| FACT | Pinned SDL implementation | pinned PS5 SDL source | exact source-level VideoOut sequence at that commit | indirect through SDL only |
| UNKNOWN | SDL runtime behavior | no approved observation | firmware compatibility, timeout, and cleanup on PS5 | do not execute |
| FACT/UNKNOWN | minimal startup | compiler can omit stock CRT; exact loader caller is absent | source-level omission only, not safe return | do not build an ELF |

The complete Phase-0 lookup subset and per-symbol evidence are in
`manifests/ps5_gnm_symbols.json`. Symbol presence never upgrades ABI confidence.

## Unknowns register

| ID | Unknown | Why it blocks progress | Evidence needed |
|---|---|---|---|
| U-001 | exact signatures for every candidate GNM export | a wrong call can corrupt memory immediately | acceptable public header/source or independently validated ABI evidence |
| U-002 | command-buffer and packet formats | cannot safely build GPU work | public, licensed format evidence plus review |
| U-003 | GPU-visible memory allocation and cache rules | resources may alias or be incoherent | proven userland allocation contract |
| U-004 | resource registration ownership/lifetime | cleanup and crash safety are unknown | proven signatures and lifecycle evidence |
| U-005 | queue, fence, and timeout semantics | a wait or queue action could hang | bounded synchronization contract |
| U-006 | VideoOut/GNM buffer compatibility | presentation ownership is unknown | separate, minimal Phase-1 evidence |
| U-007 | embedded shader identifiers and binary contract | cannot safely bind a shader | licensed public evidence and test plan |
| U-008 | runtime module name across firmware | even discovery may fail | approved hardware observation per firmware |
| U-009 | system-module initialization side effects | SDK call chain is known; firmware module internals are not public | acceptable public evidence plus separately approved observation |
| U-010 | supported firmware set | no hardware evidence exists | one manually approved probe at a time |
| U-011 | bounded SDL flip-event wait | safe timeout/cleanup cannot be guaranteed | licensed bounded-wait change or proven supervisor semantics |
| U-012 | SDL cleanup after forced process termination | recovery behavior is unknown | approved observation or public lifecycle evidence |
| U-013 | kernelwrite-free PS5 payload startup | SDK v0.41 CRT patches kernel process state before `main`; Phase 0.5 cannot prove a safe replacement | exact pinned loader caller plus complete entry/return/cleanup/crash audit |
| U-014 | loader changes before `_start` | incoming args already expose kernel access, but the creation path is absent | exact loader source and configuration used for firmware 9.60 |

Unknowns are closed only by updating this file, the relevant ADR, and the
firmware matrix with a primary source or an explicitly approved observation.

## Assumptions register

Assumptions are design choices, not compatibility claims.

| ID | Assumption | Scope | Falsification or review trigger |
|---|---|---|---|
| A-001 | `libSceGnmDriver.sprx` is a useful runtime candidate | discovery-only probe | approved lookup fails or a public source establishes another module |
| A-002 | Mock limits of 4096 pixels and 16 live resources are sufficient for lifecycle tests | host tests only | an adapter test requires a larger deterministic bound |
| A-003 | RGBA8 is enough to stabilize the initial public upload contract | mock and software-frame planning | RetroArch/SDL integration proves another minimum format is required |
| A-004 | The existing SDL CPU-framebuffer route is safer than duplicating its opaque VideoOut layout | first Phase-1 design | official public VideoOut headers and bounded lifecycle become available |
| A-005 | 1920x1080 and one fixed frame minimize first-test state | disabled Phase-1 candidate | exact firmware/display evidence requires a different supported mode |
| A-006 | A firmware-specific rebuild must receive a new approval because its digest changes | all hardware candidates | never relaxed; enforced artifact-provenance rule |