The Neo6502 API

Everything the 65C02 asks of the RP2040 — screen, sound, files, keyboard, clock — goes through a small mailbox at $FF00. Here is how to use it, function by function, for the official firmware and for Trinity, with examples that were run and verified.

Download the specification (YAML)

Two processors, one mailbox

Olimex's Neo6502 pairs a real W65C02S, which runs the programs, with an RP2040, which does everything else: DVI video, sound, USB keyboard and mouse, files on a USB stick, clock. The 65C02 has 64 KB of RAM; to get a service from the RP2040, it writes a request into a 16-byte area at $FF00, the mailbox. The RP2040 firmware reads it, performs the service, then leaves the answer there.

A call, in four steps

1. Wait until $FF00 is 0 (the mailbox is free).
2. Write the parameters at $FF04 onwards.
3. Write the function at $FF01, then the group at $FF00: the call starts.
4. Wait until $FF00 is back to 0, then read $FF02 (error) and the results.

This is exactly what the kernel routine WaitMessage ($FFF4), the llvm-mos C library and the Mad Pascal neo6502 unit do. The kernel also offers a few ready-made entry points: WriteCharacter ($FFF1), ReadCharacter ($FFEE), ReadLine ($FFEB), SendMessage ($FFF7)… Trinity adds tasks and semaphores ($FFC1 to $FFDC).

Conventions

• 16 and 32-bit numbers are stored low byte first (P0, then P1…).
• A string is length-prefixed (one byte), with no final zero; an address parameter gives its location in 65C02 RAM.
• When the firmware returns a string into a buffer, the first byte of the buffer must hold, before the call, the maximum length accepted; the firmware then writes the actual length there (checked in DSPSetStdString).
• A failing call puts a non-zero value at $FF02.

In each language

• C (llvm-mos): #include <neo/api.h> gives ready-made functions (neo_system_timer()…); for the others, the ControlPort structure of neo6502.h gives direct access to the mailbox. Build: mos-neo6502-clang -Os -o prog.neo prog.c.
• Mad Pascal: the neo6502 unit provides routines (NeoGetTimer…), NeoSendMessage(group, function) and NeoWaitMessage. Build: mp prog.pas -target:neo, then the MADS assembler. writeln itself goes through the mailbox: read NeoMessage.error or a result into a variable before printing it.
• NeoBASIC: about fifty functions have a keyword (time(), key(), locale…). For the others, write to the mailbox with poke. Beware: NeoBASIC itself uses the mailbox, for instance for print. Write parameters, function and group on one line, and read the results into variables right after the wait, before any output and any computation — otherwise you read the answer of another call. *, / and the maths functions also go through the mailbox (group 4): in peek($ff04) + 256 * peek($ff05) + 65536 * peek($ff06), the last peek reads a value already overwritten.
• 65C02 assembly: write directly to $FF00–$FF0B and call WaitMessage; the examples assemble with 64tass and load at $0800.

Official firmware and Trinity

The official firmware is Paul Robson's; Trinity is the collective's alternative firmware, built on it. Each function carries a label: Official (identical in both), Changed by Trinity or Trinity (only exists in Trinity). Function 1,11 gives the running firmware version.

How the examples are verified

Every published example was compiled then run in the Phosphoneo emulator, with the Trinity firmware. A test bench checks in the call log that the program does call the documented function, without error, then compares what it prints with what is expected; the observed output is shown under each example, except when it depends on hardware plugged into the board (UEXT I/O): the emulator only returns dummy values there. An example that did not pass this bench is not published. Code comments and messages in the examples are in French.

What we do not claim: the examples run under Trinity; those of the official functions were not replayed on the official firmware. On the board, a few functions behave differently than in the emulator (serial port, modem, flash): their entry says so.

The groups