Fichiers
ui/doc/convention-aarch64.md
2026-10-11 01:55:22 +02:00

Convention de registres AArch64 — reference normative du projet

Ce document fait autorite sur tout fichier .S du depot. Toute routine assembleur qui s en ecarte doit le declarer en commentaire d en-tete, avec la raison.

Cible : AArch64 (ARMv8-A, A64 uniquement, pas de Thumb, pas d AArch32), Linux, ABI LP64.


1. Rappel AAPCS64 (Procedure Call Standard for the Arm 64-bit Architecture)

1.1 Registres generaux

Registre Role AAPCS64 Sauvegarde
x0-x7 Arguments entiers/pointeurs 1 a 8, et valeurs de retour (x0, ou x0+x1 pour 128 bits) caller-saved
x8 Adresse du resultat indirect (XR) quand la valeur de retour est trop grosse pour les registres. Sous Linux c est aussi le registre du numero de syscall. caller-saved
x9-x15 Temporaires caller-saved
x16 (IP0), x17 (IP1) Registres d appel intra-procedure, utilisables par l editeur de liens pour les veneers. Ne jamais supposer qu ils survivent a un bl. caller-saved
x18 Registre de plateforme. Sous Linux ELF il est libre, mais d autres environnements (Windows, Darwin, certains SDK) le reservent. Regle du projet : x18 est interdit d usage. Cout nul, portabilite gagnee. reserve
x19-x28 Variables locales callee-saved
x29 (FP) Pointeur de trame callee-saved
x30 (LR) Registre de lien : adresse de retour deposee par bl/blr callee-saved (a empiler des qu on appelle soi-meme)
sp Pointeur de pile. Ce n est pas x31. special
xzr/wzr (encodes 31) Registre zero : lit 0, absorbe les ecritures special

w0-w30 sont les moities basses 32 bits. Ecrire dans wN met a zero les 32 bits hauts de xN. C est une source de bugs classique quand on manipule un int puis qu on l utilise comme offset 64 bits : il faut un sxtw explicite pour l extension de signe.

1.2 Pile

  • sp doit etre aligne sur 16 octets a chaque frontiere d appel public (bl, ret) et a chaque acces memoire qui l utilise comme base. Un sp desaligne provoque un SIGBUS sur AArch64 : ce n est pas une penalite de performance, c est un plantage.
  • La pile croit vers le bas. Prologue standard :
    stp     x29, x30, [sp, #-16]!   // empile FP+LR, decremente sp de 16
    mov     x29, sp
    // ... corps ...
    ldp     x29, x30, [sp], #16     // depile, reincremente sp
    ret
  • Il n existe pas de red zone en AAPCS64 : la memoire sous sp peut etre ecrasee a tout instant (signal, debogueur). Toute donnee temporaire doit etre au-dessus de sp apres decrement.
  • Reserver de la place se fait en un seul sub sp, sp, #N avec N multiple de 16.

1.3 Arguments qui ne tiennent pas dans les registres

Au-dela de 8 arguments entiers, les suivants passent sur la pile, alignes sur 8 octets, dans l ordre de declaration, a partir de [sp] au moment de l appel. Le projet n a aucune routine a plus de 8 arguments ; si le cas se presente, c est un signal de conception, pas un probleme d ABI a resoudre.

1.4 Registres vectoriels (NEON / SIMD, v0-v31)

Registre Role AAPCS64 Sauvegarde
v0-v7 Arguments flottants/vectoriels 1 a 8, valeurs de retour caller-saved
v8-v15 Variables locales — mais seuls les 64 bits BAS (d8-d15) sont callee-saved. Les 64 bits hauts sont caller-saved. partiellement callee-saved
v16-v31 Temporaires caller-saved

Le point v8-v15 est le piege classique : une routine qui utilise v8 en 128 bits complet doit sauvegarder d8, pas v8, pour respecter l ABI — et si elle veut preserver les 128 bits pour son propre compte, c est son affaire, pas celle de l appelant.

Regle du projet : dans une routine A64 exposee (.global), on n utilise pas du tout v8-v15. On dispose de 24 registres vectoriels caller-saved (v0-v7, v16-v31), ce qui suffit largement pour tous les noyaux de composition prevus, et cela supprime entierement la question de la sauvegarde/restauration vectorielle. Si un noyau futur demande plus de 24 registres vectoriels, c est que son ordonnancement est a revoir.

fpsr/fpcr : aucune routine du projet ne modifie le mode d arrondi ni les drapeaux d exception flottante. Le mode d arrondi est round-to-nearest-even, suppose etabli au demarrage et jamais touche. Cette hypothese est ce qui rend valide la comparaison octet-a-octet du harnais d oracle (cf. methode-oracle.md).


2. Conventions internes aux routines qui ne suivent pas l AAPCS64

Certaines routines de rendu sont des feuilles (elles n appellent personne) et sont appelees exclusivement depuis d autres routines assembleur du meme fichier. Pour celles-la seulement, on s autorise une convention allegee.

2.1 Classe "routine feuille interne" (suffixe __leaf, symbole local .L)

Contraintes :

  1. Elle n emet aucun bl/blr. Consequence : elle n a pas a empiler x30.
  2. Elle ne touche pas a sp du tout. Pas de trame, pas de spill. Si elle a besoin de spiller, elle n est pas une feuille : on la promeut en routine AAPCS64 normale.
  3. Registres qu elle peut ecraser librement : x0-x17 (sauf x18, interdit), v0-v7, v16-v31.
  4. Registres qu elle doit laisser intacts : x19-x30, sp, v8-v15. Autrement dit : la convention interne n autorise pas a casser plus que l AAPCS64 n autorise deja. Elle autorise seulement a omettre le prologue/epilogue.
  5. Elle documente en en-tete : ses entrees (registre par registre), ses sorties, et la liste exacte des registres qu elle detruit.

Ce choix est deliberement conservateur. Une convention exotique (x19 accumulateur global, par exemple) ferait gagner un registre et couterait une classe entiere de bugs non reproductibles a chaque insertion d appel. Le pilier 1 (determinisme) inclut le determinisme du debogage.

2.2 Registres a usage reserve global

Il n y en a aucun. Aucun registre ne porte de valeur vivante entre deux routines du projet. Pas de pointeur de contexte permanent en x28, pas de base de framebuffer en x27.

Raison : un registre reserve globalement est un etat cache. Il oblige chaque nouvelle routine a connaitre une convention non exprimee dans sa signature, et il rend tout appel vers du code externe (ou genere par le compilateur) potentiellement destructeur. Le gain — economiser un ldr par routine — est sans commune mesure avec le cout.

Cette decision est definitive. Si elle devait etre revue, ce serait par un ADR dedie, pas par un commentaire dans un .S.


3. Nommage des symboles et visibilite

3.1 Nommage

  • Tout symbole assembleur visible depuis le C++ est declare extern "C" cote C++ et prefixe proj3_ cote assembleur.
  • Forme : proj3_<module>_<action>, en minuscules, mots separes par _. Exemples : proj3_sys_write, proj3_fill_bytes_asm.
  • Les routines qui sont la version assembleur d une paire d oracle portent le suffixe _asm. La version C++ de reference porte le suffixe _ref. Une version volontairement fausse (test du harnais) porte _asm_broken.
  • Les symboles locaux a un fichier commencent par .L : l assembleur ne les emet pas dans la table des symboles, ils n apparaissent donc ni dans nm ni dans les traces.
  • Les etiquettes de boucle internes sont .L<routine>_<role> : .Lfill_bytes_loop, .Lfill_bytes_tail. Jamais 1: / 1b, illisible en revue.

3.2 Visibilite — boilerplate obligatoire

Toute routine exportee est declaree exactement ainsi :

    .text
    .balign 4
    .global proj3_exemple
    .hidden proj3_exemple          // pas d export dynamique : rien a interposer
    .type   proj3_exemple, %function
proj3_exemple:
    // ...
    ret
    .size   proj3_exemple, . - proj3_exemple
  • .balign 4 : toutes les instructions A64 font 4 octets ; l alignement explicite protege des sections concatenees a la main.
  • .hidden : le binaire est statique et sans libc, aucune interposition n a de sens. Cela evite au passage toute entree de PLT.
  • .type/.size : necessaires pour que llvm-objdump, perf et un debogueur retrouvent les bornes de la fonction. Un .size manquant donne des profils inexploitables — ce qui, sur un projet dont la these est la mesure de latence, est disqualifiant.

3.3 Sections

  • Code : .text.
  • Constantes en lecture seule : .section .rodata,"a",@progbits.
  • Aucune section .data ni .bss dans un fichier .S. Toute donnee mutable vit dans une arene (cf. chantier 3). Un .S qui declare de l etat mutable contourne le budget memoire explicite du pilier 2.
  • Aucun fichier .S n emet de section a la fois executable et inscriptible.
  • Chaque .S se termine par .section .note.GNU-stack,"",@progbits afin que l editeur de liens ne marque pas la pile executable.

4. Notes de portabilite entre les deux cibles materielles

  • Pixel 3a (sargo) : Snapdragon 670, coeurs Kryo 360 (Cortex-A75/A55), ARMv8.0-A avec extensions ARMv8.2 partielles. Ne pas supposer la presence de LSE (atomiques casal), de dotprod, ni de FP16 arithmetique.
  • Poco F5 Pro (mondrian) : SD 8+ Gen 1, ARMv8.4+, beaucoup plus riche.
  • Regle : le code assembleur ecrit ne suppose que la base ARMv8.0-A + NEON. Toute utilisation d une extension doit passer par une detection au runtime (lecture de AT_HWCAP dans l auxiliary vector) et un chemin de repli, sur le modele du repli memoire du chantier 3. Aucune extension n est utilisee a ce jour.