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

201 lignes
9.4 KiB
Markdown

# 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_<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 :
```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.