Skip to content
Phosphoneowiki
Contents

Phosphoneo for beginners

An emulator is a program that pretends to be a machine. This one pretends to be a Neo6502, a small retro board, so that programs can be tried without the board.

The board and its double

The Neo6502 is an 80 × 55 mm board that pairs a real 65C02 processor (the kind found in 1980s 8-bit computers) with an RP2040 microcontroller. The 65C02 runs programs; the RP2040 does everything else: it draws on screen, plays sounds, reads files and the keyboard. That part is called the firmware.

Phosphoneo reproduces this whole in a PC program. You give it a Neo6502 program; it runs it as the board would, and you see the screen in a window, or record what it displays.

Phosphoneo: what runs, and what surrounds itA .neo or .bas program is loaded into the 65C02 processor's 64 KB of RAM. When it writes to address $FF00, it calls the firmware API: the code of firmware/common, linked as is into the emulator, which handles the screen, sound, files, keyboard and mouse. On the right, the host: an SDL window, a browser, or nothing, with screenshots, video and logs. At the bottom, a single clock counts the cycles.Program.neo · .bas · binaryloaded into RAM65C02one bus access per cyclechecked on 2,540,000 cases64 KB RAMand graphics memoryFirmware APIfirmware/common, linked as isconsole, drawing, spritessound, 4 channelsfiles, storagekeyboard, mouse, gamepadUSB serial (modem)$FF00HostSDL2 windowbrowser (WebAssembly)no displayscreenshots, video, WAVlogs, trace, gdbClock: 6.25 MHz · one frame = 109,226 cycles (60 Hz) · 100 Hz timer counted in emulated cycles
What Phosphoneo contains: the processor, its memory, the firmware API, and the host around them.

Why not just use the board?

Because a trial on the board means plugging it in, copying the program, and watching the screen by eye. With Phosphoneo, a trial fits in one command line, gives the same result every time, and fits into a test script. You can make it type on the keyboard, move the gamepad, take a photo of the screen at the cycle you want, or film a game.

Three words to know

  • Cycle: the processor’s heartbeat. Phosphoneo counts time in cycles: 6,250,000 cycles make one second of machine time. This is what makes its trials repeatable.
  • Firmware: the RP2040’s program. Phosphoneo does not imitate it: it runs its code.
  • Reference screenshot: an image taken by the emulator and kept as proof. If a change alters a single pixel, a test sees it.

What next?

The first launch shows the three basic commands; the options detail every setting; the recipes combine several options for specific needs.

Sources in the repository : README.md, docs/ARCHITECTURE.md.