DEV Community: loach

PC Engine CD BIOS Devlog: Reaching BIOS API Entry Points in Local Retail Disc Traces

loach — Tue, 10 Nov 2026 03:25:12 +0000

I'm developing oss-pce-cd-bios, an open-source project aiming to replace the PC Engine / TurboGrafx-CD System Card firmware.

The previous update covered a multi-sector synthetic IPL loader running through a separate 256 KiB development image on a pinned Geargrafx core.

Since then, the most interesting result isn't a larger test count. Local traces of two commercial CDs now reach BIOS API entry points after the IPL, rather than stopping at the earlier media-layout mismatch.

To be precise: neither disc reached a title screen, and no retail-game compatibility is claimed. The observed calls still lead to unimplemented development stubs.

Getting beyond the pre-API blocker

The original diagnostic loader used a synthetic disc-layout assumption. On the locally held commercial CUE/BIN media, that assumption could place the IPL information-sector selection incorrectly, producing a PRE_API_BLOCKER_OBSERVED result before the BIOS interface could even be studied.

PR #728 introduced explicit opt-in local CUE discovery. The --commercial mode only considers local media under ./rom/; the public CI suite does not search for or consume private commercial images.

PR #730 then added a CUE-aware automatic loader configuration:

Parse the selected CUE text and derive the data track's INDEX 01 position using file-size metadata without reading the BIN payload.
Apply that position to a purpose-built PUBLIC diagnostic loader, with separate DEV behavior preserved.
Reject unsupported or ambiguous layouts and unsafe destination-overflow cases.
Keep names, absolute paths, media content, hashes, and private sector coordinates out of the public manifest and evidence.

The resulting local measurements, made with a pinned Geargrafx core in cold and warm configurations, were:

Loader	Two locally tested commercial discs
Previous synthetic-layout selection	`PRE_API_BLOCKER_OBSERVED`
Automatic DEV loader control	`PRE_API_BLOCKER_OBSERVED`
Automatic PUBLIC diagnostic loader	`API_ENTRY_CONFIRMED`

One disc reached a JSR into candidate slot $02; another reached a sequence of API calls followed by a stub halt. The observer checks the call/return sequence before classifying a result as confirmed.

This is an instrumentation milestone, not a functioning replacement BIOS. The commercial bytes stay local, and no private traces or game-derived content are published to the repository or CI.

Investigating CD_BASE without pretending the ABI is known

The candidate at slot $02 is being investigated as CD_BASE, but that identification and its precise ABI are not verified.

PR #731 builds a host-side discriminator for competing address-coordinate models: absolute LBA, track-relative, INDEX 00-relative, and other caller-adjusted interpretations.

PR #733 adds a sanitized observation catalogue and fail-closed schema, while PR #736 rejects unknown or unsupported host-side CD_BASE conditions.

None of these PRs execute the proprietary reference entry point. The candidate's register behavior, side effects, error contract, and LBA origin remain unresolved. A model that can distinguish hypotheses is not a measurement that proves one hypothesis correct.

Better refusal boundaries and stronger evidence gates

PR #734 improves the synthetic multi-sector loader by probing its final target sector before performing the first load-area write. Some end-of-media failures that previously occurred after partial copying are now rejected with zero copied bytes.

This is still a reachability probe, not a guarantee that all sectors belong to the intended data track. Other failure modes and the media track-length contract remain open.

Separately, the pinned-core ST/IRQ/MMIO diagnostic in PR #732 was merged after additional no-resume, instruction-fetch, and side-effect validation.

The E1–E3, E4–E5, and unified host judge work is also merged. These components exercise synthetic pre-block and device-access decisions, but their fixture-level PASS is not permission to execute reference firmware. The production gate remains blocked.

The development ROM now has 15 entries

Finally, PR #748 added a project-defined EX_JOYREP implementation at candidate slot $22. The DEV contract returns while preserving the tested CPU state, stack, and page registers; pinned Geargrafx regression tests and an intentionally broken mutant check the behavior.

As of the November 10 main snapshot (890c149):

Evidence axis	Current status
Project-owned DEV entry implementations	15/81
Remaining nonreturning stubs	66/81
Independently verified reference BIOS ABIs	0/81
Permitted reference BIOS JSR entries	0/81
Demonstrated retail-game title screens	0
Release eligibility	false

Upcoming work includes safely characterizing the first required CD-related API contracts, replacing one stub at a time, and refining IPL address-range handling. Work in open draft PRs, including wider LBA support, is not counted as a merged capability.

The project is still far from a distributable, compatible System Card. But reaching an observable BIOS call boundary on real local disc layouts provides a more concrete target for the next implementation step than merely improving synthetic boot tests.

Repository: https://github.com/mao2009/oss-pce-cd-bios

Implementation evidence: https://github.com/mao2009/oss-pce-cd-bios/blob/main/docs/status.md

This is an independent project, unaffiliated with NEC, Hudson Soft, Konami, or other rights holders. It does not distribute proprietary BIOS images, retail game data, or extracted commercial code.

PC Engine CD BIOS Devlog: A Multi-Sector IPL Loader Now Runs from a 256 KiB DEV Image

loach — Fri, 06 Nov 2026 03:16:38 +0000

I'm building oss-pce-cd-bios, an original, open-source replacement project for the PC Engine / TurboGrafx-CD System Card BIOS.

My previous update covered 14 development-only routines out of 81 candidate BIOS entry points, plus a synthetic CUE/BIN generator and an independent host-side oracle.

As of November 6, 2026, the number of DEV entry points is still 14/81. The meaningful progress this week is elsewhere: the project can load and execute a multi-sector, self-authored IPL through a separate 256 KiB development image on a pinned Geargrafx core.

This does not mean the firmware can boot commercial PC Engine CD games. The loader implements a project-specific development contract, not a verified System Card ABI.

From a one-sector payload to a multi-sector IPL

The first stage was PR #669. It added a DEV-only reset-to-execution path:

Start from RESET.
Read a selected synthetic CD sector with guest SCSI READ(6).
Validate a project-defined PCEX header on the guest.
Copy the payload to RAM at $3000 and execute it.

The test can keep the ROM byte-identical while changing the payload on disc, and observe a different result. That helps distinguish actual CD-sourced execution from a payload accidentally embedded in the ROM.

But this path only handled a single-sector payload.

PR #681 moves to a multi-sector synthetic IPL. The loader reads an information sector, validates metadata before writing to the destination, and then streams sectors through a staging area into RAM.

It handles memory page register (MPR) changes across 8 KiB windows, including test cases that cross $3FFF/$4000 and $5FFF/$6000. After copying, it reads the destination back and checks a project-defined 16-bit additive checksum before transferring control to the loaded entry point.

Malformed metadata and read failures must result in refusal rather than accidental execution. The checksum is explicitly a DEV extension, not an established commercial IPL standard, and it cannot catch every possible corruption.

Moving the same loader into the BIOS loading path

An important distinction: PR #681 originally ran on an 8 KiB HuCARD + synthetic CUE test path. That proved the guest-side multi-sector loader worked on a real pinned emulator core, but it did not prove that the image could be loaded as a System Card BIOS.

The follow-up, PR #683, packages the same loader into a separate 262,144-byte DEV image and runs it using Geargrafx's LoadBiosFromBuffer plus LoadMedia path.

The image builder checks its ROM layout, reset vector, and expected regions. The integration test checks a loader-identification CAP record so that an unexpected fallback to the HuCARD path cannot silently pass.

According to the merged PR evidence:

Test path	Synthetic scenarios	Cold/warm executions
8 KiB HuCARD + CUE (#681)	22	44
256 KiB DEV image via `LoadBiosFromBuffer` (#683)	22	44

Each path reports passing results for four positive scenarios, 15 rejection scenarios, two copy/read-failure scenarios, and one deliberately mutated-ROM readback-failure scenario.

Those are scenario executions reported for the respective changes, not 88 distinct commercial games or an independent hardware compatibility test. The readback fault is injected by changing test ROM behavior, not by simulating a real failing CD bus.

Also, the 256 KiB loader image is not the ordinary make dev-rom output promoted to a completed BIOS. It is a purpose-built development artifact used to exercise a specific boot path.

Testing the edges of HuC6280 behavior

There has also been less visible work on the surrounding verification infrastructure.

PR #610 rechecks instruction boundaries after MPR remapping. PR #614 adds a 51-case pinned-core block-transfer matrix, including lengths, page boundaries, aliases, prohibited destinations, and checks that preflight inspection doesn't mutate the MPR state.

On the observability side, PR #620 separates measured output-ring loss from capacity merely reported by the core. A value that cannot be measured reliably remains labelled NOT_MEASURED, rather than being turned into a precise-looking number.

These tests improve the evidence available to the project. They do not constitute a production-safe generic interception system or establish proprietary firmware ABI parity.

What is actually verified?

The current public status remains deliberately conservative:

Metric	November 6 status
Project-owned DEV entry implementations	14/81
Nonreturning stubs	67/81
Independently verified reference ABI contracts	0/81
Owner-approved `DEV_CALLABLE` entries	0
Permitted reference BIOS JSR entries	0/81
Demonstrated commercial BIOS-mediated boots	0
Firmware release eligibility	false

No callable System Card-compatible CD_RESET, CD_BASE, CD_READ, or CD_BOOT API has been independently verified. No retail game boot, second-emulator equivalence, or physical-hardware compatibility is established.

The next steps are to establish safe, independently checked reference calling contracts and build real caller-visible CD services on top of the now-testable loading path.

It's easy to make firmware progress sound impressive by counting routines or test cases. For this project, the more useful milestone is narrower: we can observe a multi-sector synthetic payload being read, mapped, checked, and executed along a specific development boot path—and describe precisely what that evidence does not prove.

Repository: https://github.com/mao2009/oss-pce-cd-bios

Dated implementation status: https://github.com/mao2009/oss-pce-cd-bios/blob/main/docs/status.md

DEV IPL boot notes: https://github.com/mao2009/oss-pce-cd-bios/blob/main/docs/dev-ipl-boot.md

This project is independent of NEC, Hudson Soft, Konami, and other rights holders. It does not distribute proprietary BIOS images, commercial game data, or extracted copyrighted code.

PC Engine CD BIOS Progress: 14 DEV Entries and a Synthetic Boot-Media Testbed

loach — Thu, 29 Oct 2026 03:15:03 +0000

I'm working on oss-pce-cd-bios, an open-source effort to create a redistributable replacement for the PC Engine / TurboGrafx-CD System Card BIOS.

In my October 22 update, the project had eight project-defined implementations connected to its 81 candidate entry points.

As of October 29, the main branch (94ef337) has 14 DEV implementations and 67 nonreturning stubs. That's real progress in original firmware code, but it is not 14 verified System Card APIs.

There is also a new synthetic disc testbed, with an important distinction: the new media checks run on the host; they do not demonstrate successful BIOS-mediated CD boot.

Six more development ROM entries

The 256 KiB development-only ROM gained six entries since the previous article:

Entry	DEV implementation	Scope
`EX_RND`	Random-number generation	Project-defined behavior
`MA_MUL16S`	Signed 16-bit multiplication	Original arithmetic routine and contract tests
`MA_SQRT`	Integer square root	Original integer routine
`MA_SIN`	Sine	Project-defined signed 16-bit Q15 representation
`MA_COS`	Cosine	Project-defined Q15 representation
`EX_SETWRT`	Set VDC MAWR	Development-only VRAM write-address setting

These are entries in a project-owned implementation manifest. All 81 readiness states remain NOT_READY, regardless of whether the entry has implementation code.

The recent MA_SIN / MA_COS work in PR #527 is an example of why the details matter. The two functions use a development-specific numeric representation, with tests for input coverage, sign and rounding rules, register preservation, and unwanted memory effects. A correct sine value by itself would not establish the caller-visible reference ABI.

The latest EX_SETWRT work in PR #524 reaches beyond arithmetic. It connects slot $3A to original code that sets the Video Display Controller's MAWR (the VRAM write-address register). Its verification includes host checks, observations with a pinned Geargrafx core, and negative/mutation cases.

Those checks provide evidence about the DEV contract and the measured emulator behavior. They are not evidence that the proprietary System Card's EX_SETWRT calling convention and side effects have been reproduced in full, much less that physical hardware has been validated.

Building synthetic boot media without borrowing game data

Another merged change, PR #556, adds:

tools/synthetic_boot_media.py: a generator for self-authored CUE/BIN media.
tools/synthetic_boot_oracle.py: an independent host-side parser and checker.
tests/host/test_synthetic_boot_media.py: regression cases for supported layouts and malformed inputs.

The supported V1/V2 layouts exercise an audio track followed by a MODE1/2352 data track, including a V2 pregap. The host oracle parses the generated media independently instead of importing the generator's answers.

That separation matters. Testing only a generator against its own assumptions can miss a shared mistake; a separately implemented checker gives us a better chance of rejecting an invalid layout.

The multi-file V2M format is still unsupported. As clarified in the follow-up specification update in PR #559, these are host-side media validation results, not successful CD boot observations on the actual Geargrafx CPU core.

The project previously demonstrated guest-side SCSI READ(6) and execution of a self-authored payload copied from CD to RAM. That was a DEV diagnostic, not a callable System Card CD_READ, CD_EXEC, or full BIOS boot implementation. The new synthetic media work does not change that boundary.

Measuring firmware progress without a misleading percentage

Here is the current evidence split:

Measurement	October 29 main
DEV ROM implementations	14/81
Remaining nonreturning stubs	67/81
Independently VERIFIED reference BIOS ABIs	0/81
Owner-approved `DEV_CALLABLE` entries	0
Verified BIOS-mediated CD boots	0
Release eligibility	false

The project explicitly keeps a reference-code execution gate closed. A development entry that runs under an original contract is not automatically compatible with an existing game, nor does static analysis authorize executing a proprietary reference ROM entry point.

The next work is to establish safely verified caller contracts, implement callable CD services such as CD_RESET and CD_READ, and boot a self-authored disc through actual BIOS services. Independent emulator comparison and physical-hardware verification remain future tasks.

There is no releasable replacement BIOS or demonstrated retail-game compatibility yet.

Going from eight to fourteen original entry points is useful. Keeping that progress separate from the zero verified reference ABIs is essential.

Repository: https://github.com/mao2009/oss-pce-cd-bios

Implementation status and evidence boundaries: https://github.com/mao2009/oss-pce-cd-bios/blob/main/docs/status.md

This project is independent of NEC, Hudson Soft, Konami, and other rights holders. It does not distribute proprietary BIOS images, commercial game images, or game-derived data.

PC Engine CD BIOS Progress: 8 DEV Entries, 0 Verified Compatible APIs

loach — Thu, 22 Oct 2026 03:26:53 +0000

I'm working on oss-pce-cd-bios, an effort to build an open-source replacement for the PC Engine / TurboGrafx-CD System Card BIOS.

My previous update focused on original HuC6280 routines and a synthetic CD-to-ADPCM DMA diagnostic. This update has a more visible milestone:

The development ROM now has eight implemented entry points out of 81 candidates, up from just one in the previous post.

That's genuine implementation progress. But it is not the same as eight compatible System Card services, and it doesn't mean any commercial CD game boots.

From standalone routines to actual DEV ROM entries

The current 256 KiB development-only image has project-owned implementations installed at these candidate jump-table slots:

Slot	Routine	Purpose
`$1E`	`EX_GETVER`	Development version response
`$3C`	`EX_BINBCD`	Numeric conversion
`$3D`	`EX_BCDBIN`	Numeric conversion
`$3F`	`MA_MUL8U`	Unsigned 8-bit multiplication
`$40`	`MA_MUL8S`	Signed 8-bit multiplication
`$41`	`MA_MUL16U`	Unsigned 16-bit multiplication
`$42`	`MA_DIV16S`	Signed 16-bit division
`$43`	`MA_DIV16U`	Unsigned 16-bit division

The remaining 73 slots are nonreturning stubs, not functional API implementations.

Previously, several math and conversion routines were tested only as independent components. They have now been wired into the development ROM's actual entry points and exercised under a project-defined calling convention with a pinned Geargrafx core.

The newest addition, MA_DIV16U in PR #480, checks quotient/remainder behavior, divide-by-zero handling, stack boundaries, caller interrupt/decimal flag combinations, and changes across the 8 KiB working RAM. Deliberately modified variants must be rejected for the expected reason rather than merely producing any failure.

The signed/unsigned arithmetic routines are original implementations, and their DEV-side contracts are being tested. They are not claims of compatibility with the proprietary reference System Card ABI.

Why 8/81 isn't a compatibility percentage

The project now tracks separate measurements instead of merging different kinds of evidence into one progress bar:

Measurement	Current main
Project-defined DEV ROM entries implemented	8/81
Remaining nonreturning stubs	73/81
Reference BIOS ABIs independently VERIFIED	0/81
Owner-approved DEV_CALLABLE entries	0
Reference BIOS JSR executions permitted by the current gate	0/81
Verified BIOS-mediated CD program boots	0

This distinction is important. An entry can execute and return according to our development contract without proving that a game can call it using the original System Card's parameters, registers, flags, memory layout, or error behavior.

In other words, the source code has advanced much faster than compatibility certification. The latter remains intentionally conservative.

The current status ledger documents these independent axes.

Learning about the reference BIOS without executing it

The static ABI investigation in PR #472 added a local-only auditor and evidence ledger for seven reference BIOS entry points.

Instead of jumping directly into proprietary firmware code, the audit records narrowly scoped static properties: control-flow shape, memory writes, bank-register operations, and hazards that would make an execution experiment unsafe.

One important observation is that some reference math entry points are dispatchers that change memory page registers. An apparently simple multiplication API can therefore carry hardware-visible side effects that an independent arithmetic routine does not reproduce.

A static safety classification is not permission to run the reference code. The project still blocks all 81 reference JSR entry points. No proprietary BIOS bytes, extracted code, or commercial game content were published with this work.

A guard can detect trouble too late

Another revealing experiment is PR #481, which tested a synthetic HuC6280 caller/stack contract on a pinned, unmodified Geargrafx core.

With the expected WRAM stack mapping, the test caller returned and its measured CPU state was preserved. With the stack mapped to I/O instead, the CPU's JSR and subsequent stack pushes changed VDC state before the guard detected the invalid mapping.

This demonstrates a subtle failure of the “check, then refuse” approach: checking after a side-effecting instruction cannot undo the side effect that already happened.

The result doesn't prove a production-safe guard exists. Nor is the experiment a complete I/O bus trace or a real-hardware result. It provides a reproducible counterexample that the eventual safety design must address.

What's next?

As of October 22, 2026, the goal is still a genuinely compatible and redistributable System Card implementation—not merely a development ROM with increasingly many working routines.

The immediate work is to verify caller-visible ABI contracts safely, establish testable CD services such as CD_RESET and CD_READ, and eventually boot a self-authored disc through actual BIOS services. Comparison against a second emulator and physical hardware will be needed before broader compatibility claims.

No retail game boot has been demonstrated. The reference ABI has zero VERIFIED entries. The release gate remains blocked (release_eligible: false).

Going from one to eight implemented DEV entries is meaningful progress. Keeping that separate from “eight compatible BIOS APIs” is just as important.

Repository: https://github.com/mao2009/oss-pce-cd-bios

This is an independent project, unaffiliated with NEC, Hudson Soft, Konami, or other rights holders. It does not distribute proprietary BIOS images, commercial game images, or game-derived content.

PC Engine CD BIOS Progress: Tested HuC6280 Routines and ADPCM DMA

loach — Wed, 21 Oct 2026 03:48:30 +0000

I'm building oss-pce-cd-bios, an open-source project aiming for a redistributable replacement for the PC Engine / TurboGrafx-CD System Card BIOS.

In the previous update, I described reading sectors from a self-authored CD image and executing a small synthetic HuC6280 payload from RAM. Those were isolated diagnostic experiments—not CD game boot.

Since then, the focus has moved toward implementing original low-level routines and testing their actual effects in a pinned emulator core. The results are useful, but it's important to keep the boundary between a tested routine and a compatible BIOS service explicit.

Seven original routines exercised in the actual CPU core

One tangible change is a set of independent HuC6280 assembly routines. The current opt-in real-core test target covers seven:

EX_BINBCD and EX_BCDBIN (numeric conversions)
MA_MUL8S and MA_MUL8U (8-bit multiplication)
MA_MUL16U (16-by-16-bit unsigned multiplication)
MA_DIV16U and MA_DIV16S (16-bit division)

These aren't just Python models: the test harnesses execute original guest instructions with a pinned Geargrafx core and check outcomes and relevant CPU state. For example, the unsigned 16-bit division work exercises edge cases and 65,536 generated operand pairs while checking quotient/remainder invariants, register/stack behavior, and deliberately broken variants.

An additional EX_RND implementation provides an original 16-bit LFSR-based random-number routine with its own tests.

None of these standalone routines has been promoted to a caller-compatible System Card API. Their local contracts are not automatically the reference BIOS calling conventions. In particular, they are not connected to the development ROM's API jump table.

The real-core integration change records the seven-routine target; the division implementation is a concrete example.

Moving a synthetic CD sector through ADPCM DMA

The earlier CD read experiment transferred sector data into ordinary guest RAM. A newer experiment exercises a different hardware path.

A self-authored HuC6280 guest issues SCSI READ(6) through the emulated CD interface and arms ADPCM DMA via register $180B, moving data into ADPCM RAM starting at $0100. The host probe observes the resulting device state and memory; it does not perform the transfer by directly calling a host-side ADPCM write method.

The test includes both a successful transfer and a negative case where DMA is not armed. It also stores the raw observations, rechecks them against the source/build hashes and known toolchain/core versions, and verifies that twelve selected manipulations of the evidence are rejected.

That extra evidence work matters: if a result can't be reproduced or its recorded inputs can't be bound to what actually ran, a green status is much less informative.

The ADPCM DMA experiment was merged on October 21.

But the boundary remains clear: this is a device-layer transfer diagnostic. It does not implement the System Card AD_TRANS service, establish its ABI, or make the BIOS bootable.

Observing CD status and subcode-Q without claiming BIOS compatibility

Two more lines of investigation now have real-core observations.

For the CD status work, a test distinguishes a synthetic disc from no media and checks how cases such as an unrecognised disc and selection timeout are classified. For subcode-Q, the project decodes an observed $DD response and checks track/time/status information at a particular synthetic-disc location.

The real-core subcode-Q result is deliberately narrow: track 2 at LBA 66, with playing, paused, and stopped states. Other track boundaries have host-side synthetic tests, but those cases have not all been measured in the actual emulator core.

These investigations provide building blocks for future CD_STAT and CD_SUBQ work. They do not mean their reference System Card entry points have been executed or reproduced.

See the CD status diagnostic and subcode-Q diagnostic.

Making the test boundary harder to misunderstand

The default test workflow has also been clarified:

make test            # build and host-side checks
make test-real-core  # required Geargrafx integration checks
make routine-real-core  # opt-in standalone routine checks

The required CI path still runs the real-core checks; they weren't removed to make the host suite greener. The separate standalone-routine target remains opt-in rather than a required CI gate. Missing prerequisites and tests that haven't run must not be reported as passing observations.

Another diagnostic now checks all 8 KiB of working RAM around a synthetic ROM-to-RAM handoff, rejecting unexpected modifications. It does not read code from a CD or demonstrate the actual CD_EXEC API.

So how many BIOS APIs actually work?

The honest answer is still small.

The development ROM has 81 candidate API slots, and exactly one is callable as a development-only service: EX_GETVER. The other 80 slots remain nonreturning stubs. Adding independently tested arithmetic routines does not change that number.

The reference System Card ABI remains unverified. Callable CD_RESET, CD_READ, and CD_EXEC services, BIOS-mediated homebrew CD boot, commercial-game compatibility, and a releasable firmware image are still missing. The release gate remains blocked.

The distinction is the central point of this update:

A tested HuC6280 routine isn't necessarily a compatible BIOS API. A demonstrated DMA path isn't AD_TRANS. An observed CD status response isn't a finished CD_STAT service.

Still, these experiments move the project from preparing diagnostic scaffolding toward original, measured building blocks. That's the progress I want to report—without claiming a usable replacement BIOS before the evidence supports one.

If you're interested in HuC6280 assembly, firmware replacement, CD-ROM² devices, or emulator-driven verification, technical feedback is welcome.

Repository: https://github.com/mao2009/oss-pce-cd-bios

This is an independent project, unaffiliated with NEC, Hudson Soft, Konami, or other rights holders. It does not distribute proprietary BIOS images, commercial game images, or game-derived data.

Building an Open-Source PC Engine CD BIOS: From Reading Sectors to Running Code from RAM

loach — Fri, 16 Oct 2026 04:21:00 +0000

I'm working on oss-pce-cd-bios, an open-source effort to create a redistributable replacement for the PC Engine / TurboGrafx-CD System Card BIOS.

The initial long-term target is behavior compatible with Super System Card 3.0, using original code and third-party OSS only where its licensing and suitability have been reviewed.

The project does not have a usable replacement BIOS yet. No commercial CD title has been shown booting with it. But the development experiments have progressed from building diagnostic ROMs to reading a synthetic CD sector and executing code loaded from it.

Here's what has been established so far—and what hasn't.

Getting useful evidence from the real emulator core

The PC Engine uses a HuC6280 CPU, bank-switched memory, and a separate CD-ROM interface. A replacement System Card needs more than a ROM file with the expected size: it needs correct startup behavior, bank mapping, calling conventions, and device interactions.

I'm using a pinned build of Geargrafx as the first instrumented execution environment.

The repository now builds original diagnostic ROMs and checks actual CPU execution, including program-counter transitions, MPR (memory page register) state, stack behavior, and working RAM. There are also deliberately broken ROM variants that must fail the same checks.

The 256 KiB development image includes a scaffold for 81 candidate System Card API slots. Those entries are placeholders that stop rather than return success. None of those 81 services is implemented as a compatible BIOS API yet.

Diagnostic API scaffold and its limits

Reading 2,048 bytes from a synthetic CD

The next step was an independent, development-only HuC6280 program that drives the emulated CD-ROM² controller.

It sends a SCSI READ(6) command through the CD interface registers and transfers a MODE1 data sector to guest RAM. The verifier checks all 2,048 user-data bytes against a separately generated reference. A three-sector, 6,144-byte case is covered too.

This runs through guest HuC6280 instructions in the actual Geargrafx core, rather than copying the expected data into RAM from the host side. Cold- and warm-reset cases are checked, along with negative scenarios such as invalid addresses, damaged disc data, and interrupted transfers.

This is an important low-level milestone, but it is not the System Card CD_READ API. Its calling convention, return behavior, interrupts, retries, and compatibility with real hardware remain separate work.

CD sector-read diagnostic

A new milestone: load code from CD and execute it in RAM

The most recent experiment connects a few of these pieces into one traceable sequence.

A small, independently assembled 28-byte HuC6280 program is embedded in sector 5 of an entirely synthetic CUE/BIN image. The development ROM then:

Synthetic CD sector (LBA 5)
             |
       SCSI READ(6)
             |
   2,048 bytes into RAM
             |
   Validate payload header
             |
     Copy code to $3000
             |
      Jump to RAM code
             |
   Write observable markers
             |
 Return to diagnostic ROM
             |
       Confirm halt

The test checks the order of the actual execution checkpoints, the bytes copied into RAM, and the marker values written by the downloaded code. It also confirms the return to the diagnostic ROM and the final halt over 64 instructions.

Corrupting the payload checksum, header, or entry offset must prevent execution. Other negative tests ensure that simply reaching an expected-looking result cannot substitute for the correct execution path.

This is a custom load-and-execute experiment, not CD game boot. It does not implement the System Card boot process or prove that any existing game can run.

Load-and-execute implementation and evidence

The less visible work matters too

A few supporting pieces have landed alongside the ROM experiments:

Disc inspection: CUE/BIN and TOC diagnostic tools check track boundaries, INDEX 00/01, pregaps, LBA/MSF calculations, and malformed inputs using synthetic fixtures.
Bus-reset observation: a separate Geargrafx experiment measures two reset pulses through $1804 and verifies the bus is free afterward. This is not proof of the System Card CD_RESET service.
Evidence and isolation: an isolated trace harness distinguishes PASS, FAIL, BLOCKED, and SKIP instead of treating missing prerequisites as success.
Source provenance: an automated guard checks for suspicious binary or proprietary material in changes. It reduces risk but is not a legal guarantee; adopting third-party code still requires human review.

The current main-branch diagnostic CI has passed for the latest load-and-execute work. Reproducing and checking the scope of those results is part of the project, not an afterthought.

Where this goes next

A useful homebrew-CD boot path is still ahead, followed by validated System Card entry points, error handling, interrupts, and comparison against an independent emulator and eventually real hardware.

I want to keep the evidence labels precise:

A ROM that loads is not a BIOS that boots. A sector that reads is not an implemented CD_READ service. A 28-byte test program running from RAM is not commercial game compatibility.

Still, being able to follow bytes from a self-authored disc, through the guest CD interface, into RAM, and then watch the guest CPU execute those bytes is genuine progress.

If you work on HuC6280 assembly, CD-ROM² emulation, firmware replacement, or reproducible compatibility tests, I'd welcome technical feedback.

GitHub: https://github.com/mao2009/oss-pce-cd-bios

This project is independent of NEC, Hudson Soft, Konami, and other rights holders. It does not distribute proprietary BIOS images, commercial games, or game-derived disc data.

PSXRecompStudio Progress: Persona's Opening, a Recompiler Demo, and a Runtime Mystery

loach — Fri, 16 Oct 2026 04:01:23 +0000

I'm building PSXRecompStudio, an open-source research project exploring static recompilation of PlayStation 1 software.

The long-term goal is to help authorized rights holders turn existing PS1 games into maintainable, rebuildable ports, even when their original source code and build tools are no longer available.

This is still research-stage work, not a way to recompile and play a complete commercial game today. But over the past few weeks, several parts of the project have become much easier to demonstrate and measure.

Seeing Persona's opening for the first time

One of the most encouraging milestones was getting visible opening imagery from Megami Ibunroku Persona (Revelations: Persona) through the OpenBIOS interpreter execution path.

I added screenshots captured at specific VBlank intervals rather than trying to reconstruct an earlier frame from the final state of video memory. The resulting captures show the ATLUS logo and opening text referencing Zhuangzi's butterfly dream.

That matters because the project had spent a long time making progress that was mostly visible in CPU traces, BIOS calls, and test output. Seeing recognizable frames is a different kind of feedback.

The qualification is important: this is interpreter execution, not a successfully recompiled version of Persona. Reaching the title screen, playing the game, and matching this behavior in the generated native host remain unproven.

How the VBlank capture was implemented (PR #754)

A tiny PS1 executable can go all the way through recompilation

There is also now a reproducible showcase for the actual recompilation pipeline.

Using the released v0.0.0-alpha.2 CLI, a script generates an original five-instruction PS-X EXE, then follows this path:

Synthetic PS-X EXE
       |
       v
MIPS analysis and lowering
       |
       v
Generated host code
       |
       v
Native artifact build
       |
       v
Execute and inspect output

The demo prints P to the terminal. Real console captures document the result on Windows, and an equivalent released-binary run was verified on Linux.

Five instructions do not demonstrate compatibility with an entire commercial game. They do demonstrate that analysis, code generation, building, and execution can work together end to end for a controlled input.

Demo verification and screenshots (PR #781)

The hard part: two execution paths, different results

The biggest open problem is less photogenic.

The interpreter can advance through Persona's opening, but the standalone AOT + interpreter-fallback runtime still produces a black screen in the investigated scenario.

AOT means ahead-of-time compilation: known PS1 instructions are translated into host code before execution. When the generated host encounters a path it cannot handle, an interpreter can take over.

I am comparing the two execution paths instead of assuming the GPU renderer is responsible.

At one shared checkpoint, the recorded CPU state, RAM, VRAM, GPU state, captured device registers, and guest-cycle count match. That is equality at one checkpoint, not a claim that all preceding execution was identical. Their subsequent instruction paths diverge, and the root cause has not yet been identified.

One useful outcome of this investigation was finding a misleading diagnostic: a run stopped by an explicit request could be reported as if it had exhausted its instruction budget. The diagnostic was corrected, but the underlying rendering divergence is still open.

Investigation and measured limits (draft PR #787)

A concrete runtime optimization

On October 16, I merged a smaller, measurable change to the generated-host runtime.

The runtime was spending a lot of time exchanging synchronous messages between generated code and the host. In particular, a guest-time report was often sent immediately before an MMIO access.

Combining that time report with the MMIO request into one message reduced IPC round trips per guest instruction from 0.106 to 0.071, approximately 33% fewer in the measured setup.

A separate throughput measurement had a higher median, but considerable host noise, so I'm treating the round-trip reduction as the more reliable result.

This improves communication overhead; it does not establish that Persona now boots further or that the black-screen divergence is fixed.

IPC optimization and measurements (PR #796)

Tests should say what they actually tested

Another recent change was deliberately unglamorous: integration tests requiring real CHD files now skip explicitly when their input is unavailable, instead of silently returning and appearing to pass.

With a lawful local fixture present, the relevant tests can run normally. Without it, the test report distinguishes missing evidence from successful execution.

I want the project's status reports to keep three things separate: what a synthetic input proves, what a locally supplied real disc proves, and what has not been verified.

Real-ROM test reporting fix (PR #791)

What's next?

The immediate priority is to identify the first meaningful behavioral difference between interpreter and generated-host execution, then extend the runtime only with evidence for the missing behavior.

There is still substantial work ahead in BIOS and device behavior, recompiler coverage, runtime integration, and independent validation. A working demo and recognizable screenshots are milestones, not compatibility guarantees.

But I'm happy to have moved from “the traces are changing” to a project with visible frames, a reproducible native-code demo, a precise unsolved divergence, and measurements that can guide performance work.

If you work on emulators, recompilers, MIPS, or retro-game preservation, I'd be interested in technical feedback—especially on differential execution testing.

Repository: https://github.com/mao2009/PSXRecompStudio

The project does not distribute commercial game images, BIOS files, or copyrighted game data. Persona screenshots document interoperability research; the game and its imagery belong to their respective rights holders. PSXRecompStudio is unaffiliated with ATLUS.

Implementing 'You Can't' for AI Coding Agents

loach — Thu, 08 Oct 2026 03:28:21 +0000

AI coding agents are getting better at writing software. I use them in my own open-source projects, too.

But there's a distinction I keep coming back to:

Teaching an AI what it shouldn't do is not the same as enforcing what its code is allowed to do.

We ask agents not to break architectural boundaries, introduce side effects, or add unapproved dependencies. Those instructions are useful, but instructions are not guarantees.

Prompts aren't enforcement

Imagine an agent generates this code inside a Domain layer:

namespace MyApp.Domain;

public class OrderService
{
    private readonly Infrastructure.OrderRepository _repository;
}

If the referenced type exists, the C# compiler will not normally know that the dependency violates your architecture.

The code may work, compile, and still be unacceptable.

A README or AGENTS.md communicates a rule. It does not independently enforce it.

Move the decision outside the agent

The workflow I want looks like this:

AI agent or human writes code
             |
             v
      Compiler + Analyzers
             |
      Policy satisfied?
         /       \
       Yes        No
        |          |
   Candidate     Diagnostic
   for merge       |
                   v
                Revise code

The agent can propose a solution. An independent tool decides whether the proposal satisfies the project's checkable constraints.

For C# projects, Roslyn Analyzers let us report diagnostics during compilation. Configured as errors, those diagnostics can make a violating build fail.

This gives AI agents immediate, deterministic feedback rather than another natural-language reminder.

Three open-source projects exploring the approach

ArchitectureAnalyzer: Compile the architecture contract

ArchitectureAnalyzer uses a JSON architecture contract and Roslyn diagnostics to check rules such as layer dependencies, forbidden APIs, and dependency graph constraints.

An architecture document records intent. A machine-checkable contract helps detect drift between that intent and the codebase.

PureSharp: Enforce specific code-level contracts

PureSharp introduces functional-programming-oriented checks for C#.

For example:

[PureMethod]
public static int Add(int a, int b) => a + b;

It detects selected side effects within its documented purity contract. It also checks conventions for immutable local variables and FluentIf termination.

var _value = Calculate();
// _value = 100; // Diagnosed reassignment

This is not a whole-program mathematical proof of purity. It's enforcement of explicitly defined, mechanically checkable properties.

PolicySharp: Allow by policy, deny by default

PolicySharp takes an allowlist-oriented approach.

A denylist catches violations someone remembered to enumerate. A new API or dependency may not appear on that list.

A default-deny policy instead follows this model:

Explicitly allowed    -> ALLOW
Explicitly denied     -> DENY
Unknown or ambiguous  -> DENY

For example, a policy can describe which namespaces a Domain scope is allowed to depend on:

{
  "version": 1,
  "mode": "default-deny",
  "scopes": [
    {
      "id": "domain",
      "match": { "namespace": "MyApp.Domain.**" },
      "allow": {
        "namespaces": [
          "System",
          "MyApp.Domain.**"
        ]
      }
    }
  ]
}

This illustrates the policy model; precise enforcement coverage depends on the implemented version.

What if the agent changes the rules?

There's an obvious bypass:

The agent introduces a prohibited dependency.
An analyzer reports an error.
The agent edits the policy or project configuration.
The build passes.

That's why an analyzer alone isn't enough.

The authority to modify application code should be separate from the authority to weaken the constraints. Policy files, project files, and analyzer references may need independent approvals and CI checks.

Static analysis also has limits. It cannot enforce properties it does not analyze, and a build gate only matters when the project actually runs it.

Freedom to propose is not permission to merge

I don't want to constrain every implementation choice an AI makes.

I want to distinguish freedom to propose a solution from permission to accept the resulting change.

Within the approved boundaries, the agent can explore different approaches. If a boundary needs to change, that should become an explicit design decision instead of a workaround silently introduced during implementation.

Conclusion

Prompts communicate intent.

Analyzers enforce checkable rules.

CI validates changes.

Approval processes protect the rules themselves.

Instead of expecting AI to remember everything it must never do, we can create development environments that reliably detect prohibited changes before accepting them.

That is the direction I'm exploring with ArchitectureAnalyzer, PureSharp, and PolicySharp.

The goal isn't less capable AI. It's more predictable, maintainable AI-assisted software development.

Publishing .NET Packages to NuGet.org with an API Key

loach — Thu, 10 Sep 2026 12:00:55 +0000

Publishing a .NET library manually is fine once or twice, but it becomes tedious when releases are frequent or automated through CI/CD.

The standard solution is to push packages to NuGet.org with dotnet nuget push and an API key.

This article covers the basic flow and the most important security consideration: never commit the API key into the repository.

Prerequisites

You need:

a .NET project
a generated .nupkg file
a NuGet.org account

For example, your package might look like this:

./bin/Release/YourPackage.1.0.0.nupkg

Create a NuGet API key

When creating a new key, configure at least:

a recognizable key name
an expiration period
the Push scope
an optional package pattern if you want to restrict which packages the key can publish

The generated key should be treated like a password.

Do not put it in source code, scripts committed to Git, or Markdown examples containing a real value.

Push a package

The basic command is:

dotnet nuget push <PACKAGE_FILE> \
  --api-key <YOUR_API_KEY> \
  --source https://api.nuget.org/v3/index.json

For example:

dotnet nuget push ./bin/Release/YourPackage.1.0.0.nupkg \
  --api-key YOUR_API_KEY_HERE \
  --source https://api.nuget.org/v3/index.json

A useful option for CI is --skip-duplicate:

dotnet nuget push ./bin/Release/*.nupkg \
  --api-key "$NUGET_API_KEY" \
  --source https://api.nuget.org/v3/index.json \
  --skip-duplicate

This avoids failing a rerun just because the same package version was already published.

Store the key in GitHub Actions Secrets

For GitHub Actions, store the key as a repository secret, for example:

NUGET_API_KEY

Then reference it from the workflow:

- name: Publish package
  env:
    NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
  run: |
    dotnet nuget push ./bin/Release/*.nupkg \
      --api-key "$NUGET_API_KEY" \
      --source https://api.nuget.org/v3/index.json \
      --skip-duplicate

The API key stays outside the repository while still being available to the CI job.

Prefer narrow credentials

If the publishing key only needs to release one package family, restrict it to that package pattern where possible.

A narrow key reduces the impact if it is ever exposed.

The same principle applies to other CI credentials: give automation only the permissions it actually needs.

Closing thoughts

The mechanics of publishing a NuGet package are simple. The part worth designing carefully is credential handling.

A solid release flow usually looks like this:

build
  ↓
pack
  ↓
secret injected by CI
  ↓
dotnet nuget push

Keeping the credential out of the repository makes the process both automatable and reasonably safe.

PureSharp: Bringing Functional Safety to C# with Roslyn Analyzers

loach — Thu, 10 Sep 2026 11:55:44 +0000

C# is a very flexible language, but that flexibility also makes it easy for side effects and mutable state to spread through a codebase.

I built PureSharp to bring a few functional-programming ideas into everyday C# development and make them enforceable at compile time.

GitHub: https://github.com/mao2009/PureSharp

NuGet: https://www.nuget.org/packages/loach.PureSharp

What PureSharp tries to enforce

PureSharp focuses on three ideas:

Purity: methods explicitly marked as pure should not perform side effects.
Immutability: local variables can opt into a "do not reassign" convention.
Safer control flow: fluent conditional expressions should terminate explicitly.

The key point is that these rules are not just documentation. Roslyn analyzers report violations while you write and build the code.

Declaring a pure method

A method can be marked with [PureMethod]:

using PureSharp.Core;

public class Calculator
{
    [PureMethod]
    public int Add(int a, int b)
    {
        return a + b;
    }
}

Inside such a method, PureSharp can report operations that violate the declared purity contract, such as accessing mutable static state, calling methods that are not known to be pure, or performing I/O.

The goal is not to claim that every C# method can be proven mathematically pure. The goal is more practical: if a developer explicitly says "this method should be pure," the analyzer should help keep it that way.

Opt-in immutability for local variables

C# does not have a general-purpose const-style feature for local variables initialized at runtime.

PureSharp uses a naming convention: local variables beginning with _ are treated as non-reassignable.

public void ProcessData()
{
    int _result = CalculateValue();

    // Reported by the analyzer:
    // _result = 100;
}

This turns a simple convention into something the compiler can enforce.

The analyzer can also require immediate initialization and can suggest the immutable convention for locals that are never reassigned.

Fluent conditional expressions

PureSharp also provides Fluent.If, which makes it possible to use conditional branching as an expression:

int status = Fluent.If(score >= 80, () => 1)
    .ElseIf(score >= 60, () => 2)
    .Else(0);

The analyzer checks that a fluent chain is properly terminated with .Else().

The motivation is simple: if the construct is intended to produce a value, all paths should be explicit.

Why Roslyn analyzers?

These rules could be described in a style guide, but a style guide is only useful when someone remembers to enforce it.

Roslyn analyzers make the feedback immediate:

violations appear in the IDE
dotnet build can fail on violations
CI does not need a separate custom validator
rules stay close to the normal C# development workflow

That makes them especially useful for conventions that are easy to understand but tedious to police in code review.

Installation

Install the package from NuGet:

dotnet add package loach.PureSharp

After that, the analyzer participates in normal builds.

What I learned from building it

The interesting part of a tool like PureSharp is not the syntax of a single diagnostic. It is deciding where static analysis can give useful guarantees without pretending to understand more than it actually can.

C# remains an imperative, object-oriented language with many escape hatches. PureSharp is therefore intentionally opt-in: developers declare the rules they want, and the analyzer checks those declarations as far as static analysis reasonably allows.

That balance is what makes Roslyn analyzers attractive for this kind of developer tooling.

PureSharp is open source here:

https://github.com/mao2009/PureSharp

Using Ctrl+Enter to Submit in OpenCode and Enter for New Lines

loach — Thu, 10 Sep 2026 11:55:33 +0000

Another OpenCode behavior I wanted to change was message submission.

By default, pressing Enter submits the current prompt. If you are used to chat tools where Enter inserts a new line and Ctrl + Enter sends, this makes accidental submissions easy.

My preferred setup is:

Enter: insert a new line
Ctrl + Enter: submit the prompt

OpenCode configuration

Edit your OpenCode configuration file and update the keybindings:

{
  "keybinds": {
    "app_exit": "ctrl+d,<leader>q",
    "input_submit": "ctrl+return",
    "input_newline": "shift+return,return,alt+return,ctrl+j"
  }
}

This tells OpenCode to treat normal Enter-style keys as new lines and reserve Ctrl + Enter for submission.

The terminal may need configuration too

There is one important detail: some terminals do not send a distinct key sequence for Ctrl + Enter by default.

In that case, OpenCode cannot distinguish it from plain Enter.

For Windows Terminal, you can define a custom sequence:

"actions": [
  {
    "command": {
      "action": "sendInput",
      "input": "\u001b[13;5u"
    },
    "id": "User.sendInput.CtrlEnterCustom"
  }
]

Then bind Ctrl + Enter to that action in the terminal settings.

The exact terminal configuration can vary, but the principle is the same: the terminal must send a distinguishable sequence before OpenCode can bind it separately.

Why this improves the workflow

Long prompts often contain code blocks, lists, and multiple paragraphs.

Making Enter safe for editing removes the pressure to finish the whole prompt on one line and reduces accidental sends.

It also makes OpenCode behave more like many chat and editor-oriented interfaces.

Closing thoughts

Keybindings are a small detail, but AI coding tools are used interactively for long periods. Small interaction problems become surprisingly expensive when repeated all day.

For me, separating newline and submit made OpenCode much more comfortable to use.

Preventing Accidental OpenCode Exits with Ctrl+C

loach — Thu, 10 Sep 2026 11:50:23 +0000

OpenCode is powerful, but one default behavior kept getting in my way: pressing Ctrl + C could close the application itself.

If you spend a lot of time in terminals, Ctrl + C is muscle memory. You press it to interrupt a command, stop a long-running process, or simply because your hands move before you think.

Losing the whole OpenCode session because of that is frustrating.

The fix is simple: move the application exit action to a different keybinding.

Change the exit keybinding

Open your OpenCode configuration file and customize the keybindings.

For example:

{
  "keybinds": {
    "app_exit": "ctrl+d,<leader>q"
  }
}

With this configuration, Ctrl + C is no longer the application-exit shortcut.

You can then use Ctrl + D or the leader-based shortcut to exit intentionally.

Why this small change matters

AI coding agents often stay open for long sessions with valuable context.

A keybinding that is common for interruption in terminal workflows should not unexpectedly destroy that session.

Separating "interrupt what is happening" from "close the entire application" makes the interface much harder to use incorrectly.

Closing thoughts

This is a tiny configuration change, but it removed one of the most annoying sources of accidental session loss for me.

If you use OpenCode inside a terminal and frequently hit Ctrl + C out of habit, remapping app_exit is worth doing early.