L'API du Neo6502

Tout ce que le 65C02 demande au RP2040 — écran, son, fichiers, clavier, horloge — passe par une petite boîte aux lettres en $FF00. Voici son mode d'emploi, fonction par fonction, pour le firmware officiel et pour Trinity, avec des exemples exécutés et vérifiés.

Télécharger la spécification (YAML)

Deux processeurs, une boîte aux lettres

Le Neo6502 d'Olimex associe un vrai W65C02S, qui exécute les programmes, et un RP2040, qui fait tout le reste : sortie vidéo DVI, son, clavier et souris USB, fichiers sur clé USB, horloge. Le 65C02 dispose de 64 Ko de RAM ; pour obtenir un service du RP2040, il écrit une demande dans une zone de 16 octets en $FF00, la boîte aux lettres. Le firmware du RP2040 la lit, rend le service, puis y dépose la réponse.

Un appel, en quatre temps

1. Attendre que $FF00 vaille 0 (la boîte aux lettres est libre).
2. Écrire les paramètres en $FF04 et suivantes.
3. Écrire la fonction en $FF01, puis le groupe en $FF00 : l'appel part.
4. Attendre que $FF00 revienne à 0, puis lire $FF02 (erreur) et les résultats.

C'est exactement ce que font la routine WaitMessage du noyau ($FFF4), la bibliothèque C de llvm-mos et l'unité neo6502 de Mad Pascal. Le noyau offre aussi quelques points d'entrée prêts à l'emploi : WriteCharacter ($FFF1), ReadCharacter ($FFEE), ReadLine ($FFEB), SendMessage ($FFF7)… Trinity y ajoute les tâches et les sémaphores ($FFC1 à $FFDC).

Conventions

• Les nombres de 16 et 32 bits sont rangés octet de poids faible d'abord (P0, puis P1…).
• Une chaîne est précédée de sa longueur (un octet), sans zéro final ; un paramètre de type adresse en indique l'emplacement dans la RAM du 65C02.
• Quand le firmware renvoie une chaîne dans un tampon, le premier octet du tampon doit contenir, avant l'appel, la longueur maximale acceptée ; le firmware y écrit ensuite la longueur réelle (vérifié dans DSPSetStdString).
• Un appel qui échoue met une valeur non nulle en $FF02.

Dans chaque langage

• C (llvm-mos) : #include <neo/api.h> donne des fonctions toutes prêtes (neo_system_timer()…) ; pour les autres, la structure ControlPort de neo6502.h donne accès direct à la boîte aux lettres. Compilation : mos-neo6502-clang -Os -o prog.neo prog.c.
• Mad Pascal : l'unité neo6502 fournit des routines (NeoGetTimer…), NeoSendMessage(groupe, fonction) et NeoWaitMessage. Compilation : mp prog.pas -target:neo, puis l'assembleur MADS. writeln passe lui-même par la boîte aux lettres : lisez NeoMessage.error ou un résultat dans une variable avant de l'afficher.
• NeoBASIC : une cinquantaine de fonctions ont un mot-clé (time(), key(), locale…). Pour les autres, on écrit dans la boîte aux lettres avec poke. Attention : NeoBASIC utilise lui-même la boîte aux lettres, par exemple pour print. Il faut écrire paramètres, fonction et groupe sur une même ligne, et lire les résultats dans des variables juste après l'attente, avant tout affichage et tout calcul — sinon on lit la réponse d'un autre appel. *, / et les fonctions mathématiques passent eux aussi par la boîte aux lettres (groupe 4) : dans peek($ff04) + 256 * peek($ff05) + 65536 * peek($ff06), le dernier peek lit une valeur déjà écrasée.
• Assembleur 65C02 : on écrit directement en $FF00–$FF0B et l'on appelle WaitMessage ; les exemples s'assemblent avec 64tass et se chargent en $0800.

Firmware officiel et Trinity

Le firmware officiel est celui de Paul Robson ; Trinity est le firmware alternatif du collectif, qui s'appuie sur lui. Chaque fonction porte une étiquette : Officiel (identique dans les deux), Modifié par Trinity ou Trinity (n'existe que dans Trinity). La fonction 1,11 donne la version du firmware en cours.

Comment les exemples sont vérifiés

Chaque exemple publié a été compilé puis exécuté dans l'émulateur Phosphoneo, avec le firmware Trinity. Un banc de test vérifie dans le journal des appels que le programme appelle bien la fonction documentée, sans erreur, puis compare ce qu'il affiche à ce qui est attendu ; la sortie observée est reproduite sous chaque exemple, sauf quand elle dépend d'un matériel branché sur la carte (entrées-sorties UEXT) : l'émulateur n'y rend que des valeurs factices. Un exemple qui n'a pas passé ce banc n'est pas publié.

Ce qu'on ne dit pas : les exemples tournent sous Trinity ; ceux des fonctions officielles n'ont pas été rejoués sur le firmware officiel. Sur la carte, quelques fonctions se comportent autrement que dans l'émulateur (port série, modem, flash) : leur fiche le précise.

Les groupes