# 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 : ```asm 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__`, 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_` : `.Lfill_bytes_loop`, `.Lfill_bytes_tail`. Jamais `1:` / `1b`, illisible en revue. ### 3.2 Visibilite — boilerplate obligatoire Toute routine exportee est declaree exactement ainsi : ```asm .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.