Référence de l'API

Fichier généré par tools/gen_api.py depuis api/definition.py : ne pas modifier à la main.

Principe de l’appel

La 6502 prépare un bloc de paramètres dans sa propre mémoire (jamais en page zéro), écrit l’adresse du bloc dans la porte $FFF8 (octet bas) puis $FFF9 (octet haut, ce qui déclenche l’appel), puis attend que le noyau remette $FFF9 à 0. Les résultats et le code d’erreur sont alors dans le bloc.

        .include "lib/e65.inc"

        lda #<bloc
        ldx #>bloc
        jsr e65_porte          ; ou la macro #E65_APPEL bloc
        lda bloc+E65_ERREUR    ; 0 = succès

bloc:   .byte E65_SVC_ECRAN, E65_ECRAN_TEXTE, 0
        .word $0400            ; page de texte
        .byte $1F              ; blanc sur bleu

Règles : seuls $FFF8–$FFFF sont réservés (porte et vecteurs) ; l’appel est synchrone ; FICHIERS EXECUTER ne revient pas en cas de succès.

Pendant l’appel

La 6502 n’est pas gelée : elle boucle sur $FFF9, et son horloge continue. Ses interruptions IRQ et NMI restent donc servies pendant un appel long (fichier, clé USB). Coût mesuré d’un appel complet (SYSTEME PING, programme LATENCE.E65) : ≈ 5 µs, soit 36 cycles à 7,26 MHz, dont environ 30 pour les instructions de la 6502 elle-même. Pire cas non mesuré : jusqu’à quelques millisecondes si l’appel tombe pendant une scrutation USB.

Interruptions

Pas d’appel système dans un gestionnaire d’interruption. Entre l’écriture de $FFF8 et celle de $FFF9, une interruption qui ferait son propre appel écraserait l’octet bas de l’appel en cours. Si un gestionnaire doit malgré tout appeler le noyau, le programme principal encadre ses appels par PHP / SEI … PLP.

Multitâche et préemption

Ctrl+Tab donne l’écran et le clavier au processus suivant, quel que soit le programme au premier plan (la touche n’est pas transmise).

Jusqu’à 8 processus peuvent tourner ensemble, chacun avec ses 64 Kio (ADR-0015, ADR-0018 : seules ses pages non nulles occupent de la mémoire quand il attend). Un programme peut céder la main (e65_ceder) ; sinon le noyau le préempte toutes les 10 ms par une NMI (ADR-0016), sans rien lui demander. Pendant ces quelques microsecondes, il emprunte les 16 octets $FFE8–$FFF7 et le vecteur NMI, puis les rend ; à la reprise, les 8 octets sous la pile sont écrasés, comme par toute interruption. Un programme qui pilote lui-même la NMI n’est pas compatible.

Numérotation, versions et découverte

• Version de l’API : 1 (E65_VERSION_API). Elle change quand un numéro, un paramètre ou un format change de façon incompatible ; un ajout (nouvelle fonction, nouveau service) ne la change pas.
• Plages de numéros de services : 0–15 noyau, 16–127 pilotes de périphériques, 128–255 extensions. Les fonctions sont numérotées à l’intérieur de leur service.
• Découverte : SYSTEME INFO rend la version du noyau, celle de l’API et le masque des services présents. Un service présent peut répondre ERR_NON_PRET (périphérique absent).
• Octets réservés par le système dans la mémoire de la 6502 : 8.

Codes d’erreur

Services

• 0 SYSTEME
• 1 ECRAN
• 2 CLAVIER
• 3 STOCKAGE
• 4 FICHIERS
• 5 GRAPHIQUE
• 6 SON

0 · SYSTEME

Services de base et de diagnostic.

SYSTEME PING — service 0, fonction 0

Ne fait rien ; rend toujours OK. Sert à vérifier que le noyau répond.

Aucun paramètre.

SYSTEME TRACE — service 0, fonction 1

Diagnostic : rend 8 octets visibles depuis le PC (tools/sonde.py).

SYSTEME BATTEMENT — service 0, fonction 2

Signe de vie : incrémente un compteur de l’état du noyau.

Aucun paramètre.

SYSTEME INFO — service 0, fonction 3

Découverte : un programme peut vérifier la version et les services disponibles avant de s’en servir.

SYSTEME TEMPS — service 0, fonction 4

Horloge : mesures de durée par la 6502. Erreur NON_PRET si la plate-forme ne fournit pas d’horloge.

SYSTEME HIBERNER — service 0, fonction 5

Écrit l’état complet de la machine (en-tête de 512 octets : écran, clavier ; puis les 64 Kio de mémoire 6502) dans un fichier. Utiliser la routine e65_hiberner de libe65, qui sauvegarde aussi les registres Y, P et S (non visibles sur le bus). Reprise : FICHIERS EXECUTER sur le fichier .HIB (par exemple en tapant son nom dans le shell) ; la routine revient alors à son appelant avec A = $FF.

SYSTEME LANCER — service 0, fonction 6

Charge un programme (ou reprend un fichier d’hibernation .HIB) dans un espace mémoire libre (64 Kio complets, séparés de ceux de l’appelant) sans l’exécuter tout de suite : il démarrera, par son vecteur RESET, la première fois que l’appelant cédera la main. L’appelant garde l’écran et le clavier. ERR_OCCUPE si les 8 processus sont pris ou si la réserve de pages ne suffit pas (ADR-0018).

SYSTEME CEDER — service 0, fonction 7

Passe la main au processus suivant, sans attendre la préemption (≈ 10 ms). Utiliser la routine e65_ceder de libe65, qui sauvegarde Y, P et S ; elle revient avec A = $FF quand le processus retrouve la main, avec A = $00 tout de suite s’il n’y a pas d’autre processus. La mémoire du processus est intacte (rien n’est copié : la 6502 change simplement d’espace mémoire).

SYSTEME PROCESSUS — service 0, fonction 8

État du multitâche.

SYSTEME PREMIER_PLAN — service 0, fonction 9

Donne l’écran et le clavier à un processus : l’écran affiche aussitôt sa page de texte, et les touches vont dans sa file. Les autres processus continuent de tourner et d’écrire dans leur propre page, sans rien afficher.

SYSTEME TERMINER — service 0, fonction 10

Termine le processus appelant et libère son espace ; ne revient pas. S’il avait le premier plan, celui-ci passe au processus suivant. ERR_OCCUPE s’il est le seul processus. La routine libe65 e65_quitter enchaîne TERMINER puis, s’il est le dernier, l’exécution de SHELL.E65.

Aucun paramètre.

SYSTEME DORMIR — service 0, fonction 13

Comme CEDER, mais le processus n’est plus choisi jusqu’à son réveil : une touche pour lui (il est au premier plan) ou la fin du délai. Une touche réveille aussitôt, sans attendre la fin de la tranche de temps (ADR-0019). Revient tout de suite (A = $00) si aucun autre processus n’est éveillé ou si une touche l’attend déjà. Utiliser la routine e65_dormir (A, X = délai).

SYSTEME NOM — service 0, fonction 11

Nom du programme qui tourne dans un espace (celui du fichier lancé, exécuté ou repris). ERR_PARAMETRE si l’espace est libre.

SYSTEME TUER — service 0, fonction 12

Termine un autre processus et libère son espace ; s’il avait le premier plan, celui-ci revient à l’appelant. Pour se terminer soi-même : TERMINER.

1 · ECRAN

Écran 640 × 480 (logique 320 × 240). Les pages de texte et d’attributs restent dans la mémoire de la 6502 et sont lues directement par le pilote vidéo, à chaque image (« zéro copie ») : il suffit d’y écrire.

ECRAN MIRE — service 1, fonction 0

Affiche la mire de diagnostic (barres et rampes de couleur).

Aucun paramètre.

ECRAN TEXTE — service 1, fonction 1

Écran texte 40 × 30, une seule couleur de texte et de fond. Erreur PARAMETRE si la page dépasse $FFF7.

ECRAN TEXTE_COULEUR — service 1, fonction 2

Écran texte 40 × 30 avec une couleur de texte et de fond par caractère.

ECRAN GRAPHIQUE — service 1, fonction 3

Affiche le graphisme (service GRAPHIQUE, ADR-0025) : 320 × 240, deux plans et 128 lutins. Prend le graphisme comme le service GRAPHIQUE (OCCUPE s’il appartient à un autre processus, NON_PRET si la machine n’en a pas). Revenir au texte : TEXTE ou TEXTE_COULEUR (le graphisme reste au processus).

Aucun paramètre.

ECRAN HERCULES — service 1, fonction 4

Mode Hercules (E10-S8) : 720 × 350 en 1 bit par pixel, monochrome, au centre de l’écran (720 × 480). L’image est lue directement dans la mémoire du programme, sans copie : il dessine par de simples écritures. Ligne y à image + 90 × y ; bit 7 de chaque octet = pixel de gauche ; bit à 1 = encre.

ECRAN HERCULES_TEXTE — service 1, fonction 5

Texte 80 × 25 du mode Hercules, en cellules de 9 × 14 pixels, lu sans copie dans la mémoire du programme (comme TEXTE). Attribut d’un caractère : bit 0 inverse, bit 1 souligné, bit 2 clignotant. Caractères $00 à $7F (bit 7 ignoré ; $00 à $1F : vides). Police 9 × 14 dessinée pour Eliott65.

2 · CLAVIER

Clavier USB (pilote hôte maison). Codes : ASCII, 13 Entrée, 8 retour arrière, 9 tabulation, 27 Échap, $7F Suppr, $81 haut, $82 bas, $83 gauche, $84 droite, Ctrl-A à Ctrl-Z = 1 à 26.

CLAVIER ZONE — service 2, fonction 0

Déclare une file clavier dans la mémoire de la 6502 : [0] tête (écrite par le noyau), [1] queue (écrite par la 6502), [2..17] 16 caractères. La 6502 lit ensuite son clavier sans aucun appel : une touche est en attente quand queue ≠ tête ; après lecture, queue = (queue + 1) & 15. La file est vidée par l’appel.

CLAVIER LIRE — service 2, fonction 1

Lecture classique, pour les programmes qui n’ont pas déclaré de zone.

CLAVIER DISPOSITION — service 2, fonction 2

Choisit la disposition du clavier.

3 · STOCKAGE

Clé USB vue comme une suite de blocs de 512 octets. Les blocs sont lus et écrits directement à l’adresse choisie dans la mémoire de la 6502.

STOCKAGE INFO — service 3, fonction 0

Capacité de la clé. Erreur NON_PRET tant qu’elle n’est pas prête.

STOCKAGE LIRE — service 3, fonction 1

Lit un bloc.

STOCKAGE ECRIRE — service 3, fonction 2

Écrit un bloc. Attention : écriture brute, sans système de fichiers.

4 · FICHIERS

Système de fichiers de la clé ou de la disquette : FAT12, FAT16 ou FAT32 (lecture et écriture ; type détecté automatiquement). Les noms sont des chaînes ASCII terminées par 0 ; chemins avec « / », insensibles à la casse, nom court 8.3 ou nom long (64 caractères au plus).

FICHIERS LISTER — service 4, fonction 0

Une entrée du répertoire racine, en nom court. Erreur FIN après la dernière.

FICHIERS LIRE — service 4, fonction 1

Charge un fichier (ou son début) directement en mémoire 6502.

FICHIERS EXECUTER — service 4, fonction 2

Charge et lance un programme .E65. En cas de succès, l’appel ne revient pas : la 6502 est suspendue, le programme est chargé à sa place, puis elle redémarre dessus (l’écran repasse en mire, la file clavier est oubliée). En cas d’erreur (FORMAT, ABSENT…), le programme appelant continue.

FICHIERS LISTER_LONG — service 4, fonction 3

Une entrée du répertoire racine, avec son nom long.

FICHIERS ECRIRE — service 4, fonction 4

Crée le fichier, ou remplace son contenu s’il existe (nom court ou long). Ordre d’écriture prudent : données, table FAT, entrée de répertoire, puis libération de l’ancien contenu. Erreurs : PARAMETRE (nom non 8.3 pour une création, ou répertoire), PLEIN, ABSENT (répertoire parent).

FICHIERS SUPPRIMER — service 4, fonction 5

Supprime le fichier, ses entrées de nom long, et libère ses clusters.

5 · GRAPHIQUE

Graphisme 320 × 240 (ADR-0025) : mémoire vidéo de 32 Kio, palette de 256 couleurs (RVB 4:4:4, 0x0RVB), deux plans (tuiles ou image, 1 à 8 bits par pixel) et 128 lutins. Un seul processus à la fois le détient : son premier appel le prend s’il est libre (palette par défaut, plans éteints, lutins cachés, mémoire vidéo à 0), sinon OCCUPE. Il est rendu quand ce processus se termine, est tué ou exécute un autre programme ; l’hibernation ne le sauve pas. Cartes, images et dessins peuvent aussi être dans la mémoire du programme, lue à chaque image sans copie (sources du PLAN, bit 6 des attributs d’un lutin, TABLE_LUTINS) : il suffit d’y écrire. Formats : voir ADR-0025.

GRAPHIQUE ECRIRE — service 5, fonction 0

Copie de la mémoire 6502 vers la mémoire vidéo.

GRAPHIQUE LIRE — service 5, fonction 1

Copie de la mémoire vidéo vers la mémoire 6502.

GRAPHIQUE CHARGER — service 5, fonction 2

Charge un fichier de la clé directement en mémoire vidéo, sans passer par la mémoire de la 6502.

GRAPHIQUE PALETTE — service 5, fonction 3

Change des couleurs de la palette. La couleur 0 est celle du fond.

GRAPHIQUE PLAN — service 5, fonction 4

Configure un plan. Entrée de carte : bits 0–9 tuile, bit 10 miroir horizontal, bit 11 miroir vertical, bits 12–15 banque de palette.

GRAPHIQUE DEFILER — service 5, fonction 5

Change seulement le défilement d’un plan.

GRAPHIQUE LUTIN — service 5, fonction 6

Configure un lutin. Le bit 7 de la forme et des attributs est réservé (PARAMETRE).

GRAPHIQUE TABLE_LUTINS — service 5, fonction 7

Table « fantôme » : relue au début de chaque image, elle remplace les lutins. Dans la mémoire 6502, le programme déplace ses lutins par de simples écritures, sans appel au noyau.

GRAPHIQUE TRAME — service 5, fonction 8

Pour se caler sur l’affichage : attendre que le numéro change, puis modifier l’image (moins de déchirures).

GRAPHIQUE REMPLIR — service 5, fonction 9

Remplit une zone de la mémoire vidéo.

GRAPHIQUE LIGNES — service 5, fonction 10

Table lue à chaque ligne (effets à la manière du HDMA de la SNES, sans copie) : le défilement de la ligne y remplace celui du plan (vagues, parallaxe) ; la banque de la ligne y remplace la banque d’un plan image, ou s’ajoute (modulo 16) à celle de chaque case d’un plan de tuiles. Une image en 16 couleurs peut ainsi montrer jusqu’à 256 couleurs (16 par ligne). Sans effet sous 8 bits par pixel. Le programme modifie la table quand il veut.

GRAPHIQUE MEMOIRE — service 5, fonction 11

Étend la mémoire vidéo à 64 Kio en empruntant 8 cases libres de la réserve des processus (mises à zéro ; adresses $8000 à $FFFF), ou la ramène à 32 Kio en les rendant. OCCUPE s’il n’y a pas 8 cases libres. Tant qu’elles sont empruntées, elles manquent aux processus en attente (LANCER ou une commutation peuvent être refusés). Elles sont rendues aussi quand le graphisme est rendu. À 32 Kio, une adresse de $8000 à $FFFF se replie sur $0000 à $7FFF.

6 · SON

Haut-parleur de la carte (transducteur magnétique sur GPIO20, signal carré par PWM ; le plus fort vers 2,7 kHz, sa résonance). Rien ne bloque : la note ou la mélodie se joue pendant que le programme continue. Une seule à la fois : un nouvel appel remplace la précédente, quel que soit le processus. Le son s’arrête quand son processus se termine, est tué ou exécute un autre programme. NON_PRET sur une plate-forme sans haut-parleur. Fréquences : 0 (silence) ou 20 à 20 000 Hz.

SON NOTE — service 6, fonction 0

Joue une note et rend la main aussitôt.

SON ETAT — service 6, fonction 1

Pour attendre la fin d’un son, ou suivre une mélodie.

SON MELODIE — service 6, fonction 2

Joue une suite de notes en arrière-plan. Les notes sont lues une à une dans la mémoire du programme, sans copie : il peut changer la suite pendant qu’elle joue (musique générée, tempo). Une note de fréquence invalide arrête la mélodie.

Mis à jour le 15 octobre 2026.