Clean Room and Validation

Clean-room method and validation status

What this reference describes

This wiki documents SpiritBoot's public export ABI, the current open-source implementation, internal operations needed to explain it, and independently observed compatibility cases. Its source baseline is SpiritBoot 27149596, using Roswell 1569e2e8 plus the ordered firmware patches. The source and build, not an archived “optimized” BIOS filename, determine which repairs exist.

The export inventory describes all slots, including data and unsupported functions. An exported or mapped symbol is not evidence that the full contract is implemented. A wrapper can translate the Xbox ABI, narrow the supported information classes, return a fixed value, or still raise a bugcheck. Each entry must identify that distinction.

Clean-room boundary

Permitted inputs for this documentation and implementation are the public ABI, open-source kernel code, public format descriptions, independently authored fixtures, and externally observed behavior. Commercial BIOS implementation expression is not copied, translated, or used as an implementation template. The later operator-authorized memory and size investigation includes private instruction decoding to establish numeric entry-walk coverage, section extents and backing; it does not publish or transfer those instruction bodies into SpiritBoot implementation work. The older public-call investigations below remain behavior-based. Numeric walk metadata is not a behavioral implementation specification and is not a certification of personnel-separated clean-room development.

For a commercial reference, use the same externally authored operation and compare observable results: return status, IOSB information, file bytes, persistent metadata, and game progression. Debugging SpiritBoot's own open-source kernel is a separate activity. A commercial game issuing a sequence of API operations is evidence of an input sequence, not evidence of how the commercial kernel implements those operations.

Evidence levels

Level	What it establishes	What it does not establish
Export definition	Ordinal, public name, calling convention and decorated argument bytes/data identity	Full parameter types or correct behavior
Source/body tracing	Current implementation route, checks, state changes, synchronization	Native correctness under every interleaving
Production-body host fixture	Behavior of maintained function bodies in controlled cases	Real driver/device/queue integration
Native API guest	Real ABI path and selected emulator/device behavior	All title workloads or performance
Matched title run	Specific progression/rendering/input behavior on that setup	All saves, all memory sizes, long play, universal compatibility
Reopen/disk-byte oracle	Persistent data produced by that operation	Every failed/partial operation path
Matched uninstrumented campaign	Performance for that workload/configuration and sample coverage	General FPS benefit in unrelated workloads

Build CI confirms build/test health. A test count is not an FPS measurement. A menu screenshot is not proof of exact output bytes. Host CPU sampling is not automatically frame-critical elapsed time.

Recorded compatibility cases

Case	Established observation	Remaining boundary
FATX overwrite/reextend	The matched Complex reference preserves prior bytes after overwrite resets EOF and later EOF reextension; ordinary-open control and final disk-byte verification agree	Do not generalize to explicit allocation shrink, delete or every create disposition
Forza menu/save setup	Current Spirit release reproduces scoreboard/replay/profile errors; matched Complex run on the same original HDD/config reaches new profile and main menu	Candidate persistence and longer play require separate checks
Forza false “disk full”	Public API trace returns disk-full on directory creation with ample free space; source probe identifies directory scan/pin failure before allocation	The underlying second-block failure is not qualified as actual capacity exhaustion
Zero unused FATX slots	Production fixture passes five cases; native candidate reaches main menu/race loading and persists profile/replay/scoreboard files in reused slots, matching reference placement	Draft behavior is not released; subsequent reopen lists the profile but selection fails as damaged. Persistence is not usable-save qualification

Raw user HDDs, EEPROMs, proprietary BIOS images, executable identities, game images, memory dumps, and private screenshots are not copied into the wiki. Public source revisions, dedicated issues/PRs and the behavioral conclusions are sufficient for this reference.

ABI checks

The export generator reads xboxkrnl.exe.def and ordinals.map. The public inventory contains 371 ordinal entries: 337 functions and 34 data exports. A decorated argument-byte count specifies ABI argument size. For fastcall, register arguments mean that number is not simply the number of stack bytes popped. A cdecl entry with no decoration is not evidence of a zero-argument prototype; variadic APIs require their verified declaration.

Unmapped function exports use named, correct-arity stubs that call KeBugCheckEx(0xE0000002, ordinal, 0, 0, 0). Unmapped data slots use generated storage, initially zero or an explicit map initializer. These mechanisms preserve diagnosability/shape; they do not implement the missing service.

Qualification matrix to maintain

Every new call repair should select relevant rows rather than claiming a universal pass:

• Correct public ordinal and calling convention; preserved nonvolatile registers and stack cleanup.
• Null/optional outputs, invalid information class, invalid length/range and overflow.
• User/kernel handle translation, access checks, object references and close behavior.
• Immediate success/failure versus STATUS_PENDING; final IOSB and exact transferred bytes.
• Event/APC/cancellation ordering, one completion per request and thread exit.
• IRQL and wait legality; lock dropped around I/O; exception cleanup.
• Repeated call, resource reuse, allocation failure, partial I/O and permanent device error.
• 64/128 MiB ROM layout matched to emulator memory, relocation and DMA stability.
• New boot, warm reset, ordinary save/load and emulator snapshot restore as separate cases.
• Cache hit/miss, cluster/cache-block crossing, malformed/cyclic chain and disk persistence.
• Native title regression and performance when the changed path actually runs.

Unknown or unqualified cases remain explicit. The documentation should narrow uncertainty, not convert a plausible implementation into an invented compatibility guarantee.

Profiling and future acceleration

Execution counts identify hot guest addresses; they are not duration measurements. Kernel timers distinguish inclusive time, exclusive work and waits, but can perturb execution. External host profiles can reveal emulator work caused by guest operations without attributing all that work to the guest PC.

A proposed host acceleration must define input stability, output ownership, guest-visible ordering, register/memory effects, error behavior and an original-path fallback. Pinning physical pages alone does not make their contents immutable. A synchronous bulk operation can use host SIMD/workers while retaining single-CPU guest semantics; arbitrary concurrent guest-thread execution is a different contract.

Use separately gated diagnostic builds for discovery and ordinary release builds for final performance claims. Keep each compatibility fix and optimization separately attributable and revertible.