Premier commit

Cette révision appartient à :
Théo Gastinel a révisé 2026-10-11 01:55:22 +02:00
révision 536792a769
62 fichiers modifiés
+6766

Aucun fichier ne correspond à votre recherche

+109
Voir le fichier
@@ -0,0 +1,109 @@
# ADR-0001 — Socle de compilation : C++20 bride, absence de libc, double cible
- Statut : accepte
- Date : 2026-09-05
- Portee : chantier 1 (structure du depot, chaine de compilation)
## Contexte
Le projet vise un environnement graphique deterministe sur AArch64/Linux, avec
trois piliers : determinisme de latence, budget memoire explicite, acces direct
justifie. Aucune ligne de code fonctionnel n existe encore. Il faut fixer le
socle avant d ecrire quoi que ce soit, sinon les choix se prendront par defaut
et par accident.
## Decision
### 1. C++20, bride
Compile avec `-std=c++20 -nostdlib -fno-exceptions -fno-rtti
-fno-threadsafe-statics -Wall -Wextra -O2`.
- `-fno-exceptions` : une exception est un chemin de sortie de latence non
bornee (deroulement de pile, tables `.eh_frame`, allocation du bloc
d exception). Incompatible avec le pilier 1.
- `-fno-rtti` : `dynamic_cast` et `typeid` impliquent une comparaison de
chaines ou une marche de hierarchie a l execution. Le projet n a aucun
polymorphisme dynamique prevu.
- `-fno-threadsafe-statics` : sans cette option, chaque variable statique
locale non triviale genere un appel a `__cxa_guard_acquire` — donc une
dependance libc et un branchement supplementaire a chaque acces. Le projet
n a pas d initialisation statique dynamique (cf. ADR-0003 sur les arenes).
- `-O2` et non `-O3` : `-O3` active un deroulage et une vectorisation
agressifs dont le gain est incertain et le cout en taille de code (donc en
pression sur le cache d instructions, donc en variance) est reel. Le projet
optimisera par des noyaux assembleur explicites, pas par des drapeaux.
- `-Wall -Wextra` avec zero warning tolere. Aucun `-Werror` en local pour ne
pas bloquer un debogage, mais la regle est contractuelle.
Ce qui reste autorise du C++ : `constexpr`, templates, `<type_traits>` et les
autres en-tetes purement compile-time. Aucun conteneur, aucun `std::string`,
aucun flux.
### 2. Aucune libc, point d entree maison
Le binaire final est lie avec `-nostdlib -nostartfiles -static -Wl,-e,_start`.
`_start` est ecrit en assembleur (`asm/start.S`), appelle une fonction C++
unique, puis termine le processus par `exit_group` via `svc #0`.
Raison : le pilier 3. Une libc apporte un initialiseur (`__libc_start_main`),
un allocateur (`malloc`), des tampons de flux, des gestionnaires TLS et une
resolution de symboles dynamique — toutes choses dont le projet ne veut ni le
comportement memoire ni la variance. Le cout assume est qu il faut ecrire
soi-meme tout ce dont on a besoin : les wrappers syscall (chantier 2), les
routines memoire, les conversions numeriques.
Consequence non evidente, notee ici pour memoire : sans `crt1.o`, il n y a
**aucun appel aux constructeurs statiques** (`.init_array`). Le projet ne doit
donc dependre d aucune initialisation statique non triviale, ou bien
`_start` devra parcourir `.init_array` explicitement. Le choix actuel est le
premier : pas d initialisation statique dynamique du tout.
### 3. Double cible, asymetrique
- **Cible embarquee** `aarch64-linux`, freestanding : le produit.
- **Cible hote**, la machine de developpement : l outillage seul (harnais
d oracle du chantier 4, generateurs de references).
**La cible hote a le droit d utiliser la libc de l hote.** Elle ne produit
jamais de binaire livre. Cette asymetrie est deliberee : le harnais doit
pouvoir s executer sans telephone, sans affichage et sans emulateur, sinon il
ne sera pas execute.
La frontiere est materialisee dans `CMakeLists.txt` par la liste
`proj3_portable_sources`. Ces unites de compilation sont freestanding par
construction et compilees a l identique par les deux cibles ; ce sont les
seules partagees. Tout le reste est specifique a une cible et le nom du
fichier le dit (`page_source_linux.cpp` / `page_source_host.cpp`).
Risque accepte et surveille : une divergence de comportement flottant ou
d endianness entre hote x86-64 et cible AArch64 rendrait la comparaison du
harnais trompeuse. Les hypotheses correspondantes sont listees dans
`doc/methode-oracle.md` (mode d arrondi IEEE identique, little-endian des deux
cotes, pas de x87 80 bits car x86-64 utilise SSE2 pour `float`/`double`).
## Alternatives ecartees
- **Utiliser une libc minimale (musl, picolibc).** Aurait fait gagner du temps
au demarrage. Ecartee : elle reintroduit `malloc` et un initialiseur qu il
faudrait ensuite neutraliser un par un, et elle brouille la frontiere que
l ADR cherche precisement a etablir.
- **Cible unique aarch64, tests sous qemu-user.** Ecartee : ajoute une
dependance d emulation au chemin de test le plus frequent. Le harnais doit
etre trivial a lancer, sinon il pourrit.
- **Meson ou Makefile a la main.** Ecarte : CMake+Ninja donne la
cross-compilation par fichier de toolchain et un graphe de dependances
correct sans travail supplementaire. Aucun besoin exotique ici.
## Consequences
- Il faut ecrire des wrappers syscall avant tout code utile (chantier 2).
- Il faut ecrire un allocateur avant tout code de rendu (chantier 3).
- Toute tentation d appeler `memcpy` doit etre traitee : `-ffreestanding`
autorise le compilateur a **generer** des appels a `memcpy`/`memset`/
`memmove`/`memcmp` meme sans libc. Le projet doit fournir ces quatre
symboles lui-meme. C est note comme dette a traiter au moment ou un lien
echoue dessus ; a ce jour aucun appel n a ete genere (verifie par
`llvm-nm -u` sur le binaire, qui ne liste aucun symbole indefini).
- L absence de `-Werror` repose sur la discipline. Si elle se relache, on
l ajoutera.
+84
Voir le fichier
@@ -0,0 +1,84 @@
# ADR-0002 — Wrappers syscall en assembleur plutot qu en asm inline C++
- Statut : accepte
- Date : 2026-09-05
- Portee : chantier 2
## Contexte
Sans libc, il faut emettre `svc #0` soi-meme. Deux facons de le faire :
1. **Assembleur pur**, dans un `.S` : une routine par appel, assemblee telle
quelle, appelee par `bl`.
2. **Assembleur inline** dans une fonction C++ `static inline`, avec des
contraintes de registres et une liste de clobbers.
L asm inline est la solution la plus repandue — c est ce que fait musl, et ce
que font la plupart des noyaux unikernel. Elle merite donc une justification
explicite d etre ecartee.
## Decision
**Assembleur pur, dans `asm/syscall.S`.**
## Ce que ca coute
- **Un appel de fonction par syscall.** L asm inline se serait fondu dans
l appelant : pas de `bl`, pas de `ret`, et le compilateur aurait pu ordonner
les instructions autour du `svc`. On paie donc environ deux instructions et
une prediction de branchement par appel. Sur un `svc` qui coute plusieurs
centaines de cycles de transition en mode noyau, c est du bruit — mais c est
un cout reel, et il faut le nommer.
- **Aucune propagation de constantes a travers le wrapper.** Le compilateur ne
voit qu un appel opaque : il ne peut pas savoir que `sys::write(2, s, n)`
utilise toujours le meme descripteur, ni eliminer un appel mort.
- **Deux endroits a tenir a jour** pour ajouter un appel : le `.S` et le `.hpp`.
## Ce que ca apporte
1. **Le contrat de registres est verifiable a l oeil.** Une routine de trois
instructions est lisible dans un desassemblage et se compare directement a
`arch/arm64/kernel/entry.S`. Une contrainte inline `"r"(x)` avec une liste
de clobbers est un contrat entre nous et l optimiseur, et ce contrat est
silencieux quand il est faux.
2. **Pas de dependance au comportement de l optimiseur.** L asm inline peut
etre duplique, deplace, ou sorti d une boucle par le compilateur s il juge
le bloc pur. Il faut alors `volatile` et une liste de clobbers `"memory"`
exacte, sous peine de bugs qui n apparaissent qu a `-O2` et pas a `-O0`.
C est exactement le genre de non-determinisme que le pilier 1 rejette.
3. **Cout constant, mesurable, identique a chaque site d appel.** Avec l asm
inline, le code genere autour du `svc` depend du contexte : le cout du
wrapper varie d un appel a l autre. Ici il est le meme partout.
4. **Alignement de pile garanti par construction.** Aucun wrapper ne touche a
`sp` ni n empile `x30`. Il n y a donc rien a verifier : la contrainte des
16 octets de l AAPCS64 est respectee parce qu il n existe pas de code pour
la violer.
5. **Une macro assure l uniformite.** `PROJ3_SYSCALL_DIRECT` emet les quatorze
wrappers directs a l identique. Il est structurellement impossible que l un
d eux ait un prologue ou une transformation qui traine.
## Consequences
- Les numeros d appel sont dans `src/proj3/sys/syscall_nr.hpp`, inclus par le
`.S` (qui est preprocesse). Ils ne sont jamais ecrits en dur dans le corps
d une routine.
- La valeur de retour n est pas transformee dans le wrapper (cf.
`doc/convention-syscall.md`, option C). Le `.S` se limite a
`mov x8, #N` puis `svc #0` puis `ret`.
- `open` est le seul wrapper qui remanie ses arguments : la table generique
AArch64 n a pas de `__NR_open`, seulement `openat`. Il decale les quatre
arguments et injecte `AT_FDCWD`. C est documente dans le fichier, et c est
pour cela qu il n utilise pas la macro.
- Si un jour le cout de l appel devenait mesurable sur un chemin chaud — ce qui
demanderait un syscall dans une boucle serree, situation que le projet
cherche a eviter par ailleurs — la reponse serait de supprimer le syscall,
pas de l inliner.
## Alternatives ecartees
- **`asm volatile` inline avec contraintes.** Ecartee pour les raisons 1, 2 et
3 ci-dessus.
- **Une seule routine generique `syscall(nr, a, b, c, d, e, f)`.** Ecartee :
elle oblige a decaler sept arguments a chaque appel, elle perd le typage des
arguments, et elle rend le desassemblage illisible (tous les appels se
ressemblent).
+93
Voir le fichier
@@ -0,0 +1,93 @@
# ADR-0003 — Arene lineaire plutot qu allocateur generaliste
- Statut : accepte
- Date : 2026-09-05
- Portee : chantier 3
## Contexte
Le projet doit fournir de la memoire au rasterizer, a l atlas de glyphes, au
scanout et aux tampons d entree. La solution reflexe serait un allocateur
generaliste — un `malloc` maison : listes libres par classe de taille, ou
allocateur de dalles.
## Decision
**Un allocateur d arene lineaire (bump allocator), sans liberation
individuelle, sur des arenes de taille fixe decidees a la compilation.**
## Justification par les piliers
### Pilier 1 — determinisme de latence
Un allocateur generaliste a un cout d allocation **variable et non borne** : il
depend de l etat de fragmentation, donc de tout l historique du programme. Deux
executions identiques n ont pas la meme latence. Pire, le cout du pire cas
(fusion de blocs adjacents, parcours d une liste libre longue) arrive rarement
— donc au plus mauvais moment, et de facon irreproductible.
Une arene alloue en **une addition et un masque**. Le cout est constant, connu,
et identique a la millionieme allocation comme a la premiere. Il n y a pas de
fragmentation parce qu il n y a pas de trous.
### Pilier 2 — budget memoire explicite
Un allocateur generaliste rend la question « combien ce programme
consomme-t-il ? » difficile a repondre : le pic depend de l ordre des
allocations. Avec des arenes de taille `constexpr`, la reponse est dans
`mem/layout.hpp` et elle est verifiee a la compilation.
Surtout : un allocateur generaliste **peut echouer tard**. Une arene, elle,
echoue **fort et tout de suite**, avec le nom de l arene et le calcul a
corriger.
### Pilier 3 — acces direct justifie
Un allocateur generaliste est une couche d abstraction de plusieurs centaines
de lignes, avec ses propres invariants et ses propres bugs. Une arene, c est un
pointeur et une capacite. Il n y a rien a justifier parce qu il n y a presque
rien.
## Ce que ca coute — honnetement
1. **Aucune liberation individuelle.** Un objet a duree de vie courte au milieu
d objets a duree de vie longue occupe sa place jusqu au prochain `reset()`
de son arene. Il faut donc **penser les durees de vie par lot**, et c est
une discipline reelle : elle se voit dans la conception, pas seulement dans
l implementation.
2. **Le decoupage doit etre juste.** Cinq arenes signifient cinq calculs qui
peuvent etre faux. Un allocateur generaliste aurait absorbe un mauvais
dimensionnement au prix de la latence. Ici, un mauvais dimensionnement
plante. C est voulu : `Arena::peak()` existe pour confronter le calcul a la
realite.
3. **Pas de reutilisation entre arenes.** Si l atlas est plein alors que la
geometrie est vide, on ne peut pas emprunter. Une arene unique partagee
eviterait cela, mais rendrait toute analyse d occupation impossible. On
prefere savoir.
4. **`mark()` / `rewind_to()` est un couteau.** Rembobiner invalide tout ce qui
a ete alloue apres la marque, sans que rien ne le signale. Un pointeur garde
au-dela d un rewind est un usage-apres-liberation classique. Le projet
confine ce motif au harnais et au rasterizer, ou la portee est locale et
visible en entier.
## Alternatives ecartees
- **Allocateur de dalles (slab) par type.** Aurait donne un cout constant lui
aussi, et permis la liberation individuelle. Ecarte : il faut une liste libre
par type, donc de l etat mutable par type, et le dimensionnement de chaque
dalle pose exactement le meme probleme que celui des arenes — avec plus de
code.
- **Allocateur de pile unique pour tout le programme.** C est une arene, avec
une seule arene. Ecarte parce qu on perd la ventilation par usage, donc la
capacite de dire quelle partie du programme consomme quoi.
- **Un vrai `malloc`.** Ecarte : cf. pilier 1.
## Consequences
- Le rasterizer porte de Gastinel Write ne peut plus faire croitre un
`std::vector` d aretes : il a un plafond (`kMaxEdges`) et un depassement est
un echec explicite. C est un changement de comportement par rapport a
l original, documente dans `render/rasterizer.hpp`.
- Le garde-fou `operator new` (cf. `doc/memoire.md`) est le complement
indispensable de cette decision : sans lui, une allocation cachee
reintroduirait par la fenetre ce que l arene interdit par la porte.
+92
Voir le fichier
@@ -0,0 +1,92 @@
# ADR-0004 — Portage du rasterizer de Gastinel Write
- Statut : accepte
- Date : 2026-09-05
- Portee : chantier 5
## Contexte
Gastinel Write contient un parser TTF maison et un rasterizer scanline nonzero
winding, valides glyphe par glyphe sur Windows. Les reecrire serait du travail
perdu et introduirait des bugs dans du code qui n en a plus.
## Decision
**On porte, on ne reecrit pas.** L algorithme est conserve pas a pas ; ce qui
change est l environnement, pas le calcul.
Changements effectues, et rien d autre :
| ce qui change | pourquoi | ou |
|---|---|---|
| `std::vector` / `std::string` vers arenes | pilier 2 ; le garde-fou tuerait le processus sinon | partout |
| lecture de fichier retiree de `TtfFont` | `fopen` est de la libc ; l appelant fournit un tampon | `font/ttf.hpp` |
| `std::sort` vers heapsort maison | cout pire cas borne (pilier 1) | `base/sort.hpp` |
| `std::hypot` vers calcul naif en `double` | pas de libm | `base/math.hpp` |
| `std::floor` / `ceil` / `lround` vers equivalents maison | pas de libm | `base/math.hpp` |
| composition separee de la rasterization | rend les noyaux NEON possibles | `render/compose.hpp` |
| plafond d aretes au lieu d un vector qui pousse | une allocation en plein rendu est interdite | `render/rasterizer.hpp` |
## La separation couverture / composition
C est le seul changement de **structure**, et il est delibere.
Dans Write, la rasterization et l ecriture dans le DIB Win32 etaient voisines,
et le format BGRA du DIB s etait infiltre dans le raisonnement. Ici :
- `render/rasterizer.cpp` produit de la **couverture** : une valeur par pixel,
aucune notion de couleur ni de format ;
- `render/compose.cpp` — et lui seul — connait le format de destination
(XRGB8888, celui d un plan DRM).
Sans cette separation, un futur noyau NEON de composition obligerait a toucher
au rasterizer, donc a invalider sa validation.
## La dette technique heritee est CONSERVEE
Le rasterizer de Write assume explicitement : **pas de crenage, pas
d antialiasing (couverture binaire), pas de hinting**. Ces choix sont
documentes et volontaires cote Write.
**Ils ne sont pas corriges dans ce chantier.** L avis du portage figure dans le
rapport de chantier, pas dans le code, et aucun de ces trois points n a ete
modifie.
## Hypotheses qui changent en quittant x86 Windows
- **Endianness.** Le format TrueType est big-endian et le parser le lit octet
par octet : il est insensible a l endianness de la machine, hier comme
aujourd hui. En revanche la **composition** manipule des `u32` de pixel et
suppose le little-endian ; l hypothese est verifiee par `static_assert` sur
`__BYTE_ORDER__` dans `base/types.hpp` et rappelee dans `render/compose.hpp`.
- **Alignement.** x86-64 tolere les acces desalignes ; AArch64 les tolere pour
les acces ordinaires mais **pas** pour ceux qui utilisent `sp` comme base, et
les futurs noyaux NEON auront des chemins distincts selon l alignement.
`compose_coverage` verifie donc explicitement l alignement 4 octets du
framebuffer au lieu de le supposer.
- **Pile.** Le code d origine allouait des tableaux temporaires par `vector`.
Le portage ne les a pas transformes en tableaux de pile : `GlyphBuilder`
porte les tampons de travail (points, drapeaux, fins de contours) dans une
arene, parce qu une pile sans libc n a pas de page de garde automatique.
## Verification
Le portage n est pas « plausible », il est **verifie** :
`tools/write_reference_dump.cpp` compile les sources **originales** de Write
(`font/ttf.cpp` et `render/rasterizer.cpp`, qui ne dependent d aucune API
Windows) et vide leurs sorties dans un format texte.
`test/test_raster_golden.cpp` compare, octet par octet, la sortie du code porte
a cette reference.
C est ce qui transforme la divergence potentielle de `std::hypot` d un risque
en un fait mesure.
## Alternatives ecartees
- **Reecrire depuis la specification TrueType.** Ecarte : c est refaire le
travail de validation glyphe par glyphe deja fait.
- **Garder `std::vector` et n interdire l allocation qu apres l init.** Ecarte :
la frontiere « apres l init » n est pas verifiable mecaniquement, alors que
« jamais » l est, par le garde-fou.
- **Porter aussi la composition telle quelle depuis le backend GDI.** Ecarte :
cf. la separation ci-dessus.
+200
Voir le fichier
@@ -0,0 +1,200 @@
# 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.
+152
Voir le fichier
@@ -0,0 +1,152 @@
# Convention de remontee d erreur syscall — decision definitive
Statut : **arrete**. Une seule convention dans tout le projet. Tout code qui
appelle un wrapper syscall suit celle-ci, sans exception ni variante locale.
---
## 1. Le probleme
Le noyau Linux ne dispose pas d `errno`. Sur AArch64, `svc #0` place dans `x0`
soit le resultat de l appel, soit **l oppose du code d erreur**. Un resultat
est une erreur si et seulement si :
```
-4095 <= x0 <= -1
```
La borne `-4095` n est pas decorative : `MAX_ERRNO` vaut 4095 dans le noyau
(`include/linux/err.h`), et c est exactement ce que fait la macro
`IS_ERR_VALUE`. Certains appels retournent legitimement des valeurs negatives
hors de cette plage — `lseek` sur un fichier de plus de 8 exaoctets, `mmap`
retournant une adresse dont le bit 63 est a 1 sur une configuration a 64 bits
d espace utilisateur. Un test approximatif du genre `if (ret < 0)` est donc
**faux**, pas seulement imprecis.
C est la libc qui, normalement, traduit cela en `-1` + `errno`. Sans libc,
il faut choisir.
---
## 2. Options envisagees
### Option A — Valeur sentinelle plus etat global (mimer errno)
Le wrapper retourne `-1` en cas d echec et depose le code dans une variable
globale `proj3_last_errno`.
| Pilier | Evaluation |
|---|---|
| 1. Determinisme de latence | Neutre en soi, mais impose une variable globale mutable. Des qu on aura plus d un fil d execution ou un gestionnaire de signal, il faut du stockage par contexte : c est le chemin qui mene a `__errno_location()`, donc a un appel indirect non inlinable sur le chemin chaud. |
| 2. Budget memoire explicite | Une section `.data`/`.bss` mutable hors arene. Contredit directement la regle "toute donnee mutable vit dans une arene" (`convention-aarch64.md` 3.3). |
| 3. Acces direct justifie | C est reconstruire la couche libc qu on a explicitement decide de ne pas avoir. Abstraction non justifiee. |
Verdict : **rejetee**. Elle detruit l information (deux appels, le second
ecrase le code du premier) et introduit un etat global cache.
### Option B — Structure de retour `{ valeur, code_erreur }`
Le wrapper retourne un agregat de deux `i64`.
| Pilier | Evaluation |
|---|---|
| 1. Determinisme de latence | Un agregat de 16 octets rentre dans `x0`+`x1` en AAPCS64, donc pas de retour indirect ni de trafic memoire. Cout nul en theorie. En pratique, cela oblige chaque wrapper assembleur a produire deux registres, donc a tester la plage d erreur **dans** le wrapper : une comparaison et un `csel` par appel, meme quand l appelant ignore l erreur. |
| 2. Budget memoire | Rien a allouer. Correct. |
| 3. Acces direct | La valeur brute rendue par le noyau est deja porteuse des deux informations. Les scinder puis les recombiner cote appelant est du travail ajoute pour rien. |
Verdict : **rejetee**, mais de peu. Le seul reproche serieux est le travail
inconditionnel dans le wrapper alors que la meme information est disponible
gratuitement.
### Option C — Valeur brute du noyau, encapsulee dans un type a cout nul
Le wrapper retourne exactement ce que `svc #0` a mis dans `x0`, tel quel. Cote
C++, ce `i64` est enveloppe dans une structure d un seul membre,
`proj3::sys::Result`, dont toutes les methodes sont `constexpr` et inlinees :
`is_err()`, `err()`, `value()`, `ptr()`, `fd()`.
| Pilier | Evaluation |
|---|---|
| 1. Determinisme de latence | Le wrapper assembleur ne fait **rien** apres le `svc` : `svc #0 ; ret`. Cout strictement minimal et constant. Le test de plage n est paye que par l appelant qui le demande. |
| 2. Budget memoire | Aucun etat, aucune allocation, aucune section mutable. |
| 3. Acces direct | Zero couche : la valeur traversee est celle du noyau, bit pour bit. La structure n existe qu au niveau du type, pas a l execution (`sizeof == 8`, trivialement copiable, passee en registre). |
Verdict : **retenue.**
---
## 3. Convention retenue
### 3.1 Cote assembleur
Chaque wrapper est de la forme :
```asm
proj3_sys_<nom>:
mov x8, #PROJ3_NR_<nom>
svc #0
ret
```
Aucune transformation. La valeur de retour est le `x0` du noyau.
Consequence directe : **aucun wrapper n a de prologue, ne touche a `sp`, ni
n empile `x30`.** L alignement de pile est preserve trivialement.
### 3.2 Cote C++
```cpp
namespace proj3::sys {
// Valeur de retour brute d un appel systeme Linux.
// sizeof == 8, trivialement copiable : passee et rendue en registre.
struct Result {
i64 raw;
// Plage d erreur exacte du noyau : [-4095, -1]. Ni approximative,
// ni "raw < 0".
constexpr bool is_err() const { return raw < 0 && raw >= -4095; }
constexpr bool is_ok() const { return !is_err(); }
// Code errno positif. Precondition : is_err().
constexpr i32 err() const { return static_cast<i32>(-raw); }
// Valeur utile. Precondition : is_ok().
constexpr i64 value() const { return raw; }
constexpr i32 fd() const { return static_cast<i32>(raw); }
void* ptr() const { return reinterpret_cast<void*>(raw); }
};
}
```
### 3.3 Regles d usage — obligatoires
1. **Toute valeur `Result` est testee avec `is_err()` avant tout usage de
`value()`, `fd()` ou `ptr()`.** Il n existe pas de conversion implicite vers
un entier ou un booleen : le type ne se laisse pas utiliser par accident.
2. **Ignorer un `Result` est explicite.** Le type est marque
`[[nodiscard]]` ; l ignorer demande d ecrire `(void)`. Le seul cas ou c est
legitime est `close()` en chemin de sortie.
3. **Aucun code du projet ne stocke un `errno`.** Un code d erreur est traite
la ou il apparait : soit il est recuperable et le chemin de repli est pris
sur place (c est le cas du repli `MAP_HUGETLB` -> THP -> `mmap` simple),
soit il ne l est pas et on appelle `panic()` avec le nom de l appel et le
code. Rien n est mis de cote pour plus tard.
4. **`EINTR` n est jamais reessaye en boucle silencieuse.** Une boucle de
retry est une latence non bornee, donc une violation du pilier 1. Le projet
n installe aucun gestionnaire de signal ; si `EINTR` apparait, c est un
evenement inattendu et il doit remonter.
5. Les constantes `errno` utilisees sont definies dans
`src/proj3/sys/errno.hpp`, avec leur source. On ne definit que celles qu on
teste effectivement.
### 3.4 Ce que cette convention coute
- L appelant doit se souvenir que `mmap` peut legitimement rendre un pointeur
dont la valeur signee est negative hors plage d erreur. `is_err()` gere ce
cas correctement, mais un appelant qui ecrirait `if (r.raw < 0)` a la main
aurait tort. C est le seul piege, et il est nomme ici.
- Il n y a pas de message d erreur lisible associe a un code. On imprime le
numero. Une table `errno -> chaine` couterait plusieurs kilooctets de
`.rodata` pour du confort de debogage ; si elle devient necessaire, elle sera
conditionnee a un build de debogage, par un ADR.
+187
Voir le fichier
@@ -0,0 +1,187 @@
# Memoire — trois modes de pages, cinq arenes, un garde-fou
## 1. Les trois modes, et ce qu ils valent
L acquisition des pages (`src/proj3/mem/page_source_linux.cpp`) essaie trois
chemins **dans l ordre**, au demarrage, **dans un seul binaire** :
| ordre | appel | mode retenu |
|---|---|---|
| 1 | `mmap(MAP_HUGETLB \| MAP_HUGE_2MB)` | `HugeMode::Hugetlb2MB` |
| 2 | `mmap` classique puis `madvise(MADV_HUGEPAGE)` | `HugeMode::TransparentHuge` |
| 3 | `mmap` classique seul | `HugeMode::PlainPages` |
C est exactement l esprit du repli OpenGL/GDI de Gastinel Write : detection au
runtime, un seul binaire, aucune question a l utilisateur, et le mode
effectivement retenu est journalise et interrogeable par le programme.
### Ils n ont PAS les memes proprietes de determinisme
C est le point central, pas une note de bas de page.
**`Hugetlb2MB`** — les pages viennent du pool hugetlbfs, reservees d avance.
Elles ne sont ni deplacees, ni fusionnees, ni recuperees, ni scindees. Une
entree de TLB couvre 2 Mo. **Les mesures de latence faites dans ce mode sont
valides.**
**`TransparentHuge`** — le noyau *peut* promouvoir la region en huge pages, ou
pas. Il le fait par un fil de fond, `khugepaged`, dont l ordonnancement nous
echappe totalement. Une promotion — ou une scission — peut se produire
**pendant** une mesure. **Toute mesure de latence faite dans ce mode porte une
barre d erreur inconnue** et doit etre annotee comme telle. Le mode est
utilisable, le chiffre qui en sort ne l est pas sans reserve.
**`PlainPages`** — pages de 4 Ko. Comportement previsible, mais couvrir les
9,6 Mo de scanout demande environ 2342 entrees de TLB, ce qui depasse la TLB
de second niveau d un Cortex-A75. Les manques de TLB deviennent alors une
source de variance mesurable. **Le mode est correct, pas rapide.**
**`HostEmulated`** — cible hote uniquement, memoire fournie par `malloc`.
Aucune garantie d aucune sorte. Ce mode existe pour que le harnais tourne sur
la machine de dev, et pour qu il soit **impossible** de confondre un chiffre
obtenu sur un x86 de bureau avec un chiffre obtenu sur le telephone.
### Savoir lequel est actif
```cpp
#include "proj3/mem/page_source.hpp"
proj3::mem::HugeMode m = proj3::mem::active_mode();
const char* nom = proj3::mem::huge_mode_name(m); // "HUGETLB-2MB", ...
bool mesurable = proj3::mem::mode_is_deterministic(m); // true pour Hugetlb2MB seul
proj3::mem::log_active_mode(); // journalise + avertit
```
`log_active_mode()` ecrit sur la sortie d erreur, au demarrage, quelque chose
comme :
```
proj3: memoire : mode retenu = PAGES-4K
proj3: memoire : ATTENTION, pages NON garanties.
proj3: memoire : toute mesure de latence faite dans ce mode
proj3: memoire : porte une barre d erreur inconnue.
```
### Attention : `MAP_HUGETLB` n est pas suppose disponible
Sa presence sur le noyau stock du Pixel 3a **n a pas ete verifiee
materiellement**. Sur un noyau Android par defaut, `nr_hugepages` vaut zero et
le pool est vide : le chemin 1 echouera avec `ENOMEM`. C est precisement
pourquoi le repli existe et pourquoi il est teste des le premier demarrage.
`MAP_HUGE_2MB` est passe explicitement. Sans lui, `MAP_HUGETLB` utilise la
taille de huge page par defaut du systeme, qui peut valoir 512 Mo sur certaines
configurations arm64 — l appel echouerait alors pour une raison difficile a
diagnostiquer.
## 2. Les cinq arenes
Un **seul** `mmap` est fait, puis decoupe. Raison : le repli huge pages ne vaut
que sur une region contigue. Cinq `mmap` separes auraient cinq modes
potentiellement differents, et la question « quel mode est actif ? » n aurait
plus de reponse unique.
Toutes les tailles sont dans `src/proj3/mem/layout.hpp`, en `constexpr`, avec
leur calcul. Dimensionnement **Pixel 3a : 4 Go de RAM, 1080x2220**.
| arene | taille | calcul |
|---|---:|---|
| `scanout` | 19 185 664 | `1080*2220*4 = 9 590 400` par tampon, arrondi a la page (9 592 832), **deux** tampons. Double buffering, pas triple : un troisieme tampon ajoute une image entiere de latence, ce que le projet combat. |
| `geometrie` | 2 097 152 | Une arete = 20 octets. Pire cas raisonne : ~600 points de contour, chaque quadratique subdivisee au plus 64 fois -> 38 400 aretes = 768 000 octets. 2 Mo laisse la place d y ajouter un trace d interface dans la meme passe. |
| `atlas` | 2 097 152 | Couverture 8 bits. Trois corps (16/24/32 px), cellule `(corps+2)^2` : 324 + 676 + 1156 = 2156 octets par glyphe. 256 glyphes (Latin-1 + ponctuation) = 551 936 octets. Facteur 3,8 de marge pour un quatrieme corps ou une graisse. |
| `entree` | 131 072 | Evenement normalise = 32 octets. Ecran tactile : ~200 evt/s par contact, 10 contacts = 2000 evt/s. 4096 emplacements = plus de deux secondes de rafale. |
| `scratch` | 2 097 152 | Remis a zero a chaque image. Majorant des intersections de balayage : 38 400 croisements de 8 octets = 307 200 octets, plus les tampons de composition par tuiles. |
**Total decoupe : 25 608 192 octets.** Le bloc demande au noyau est arrondi au
multiple superieur de 2 Mo — `MAP_HUGETLB` exige une longueur multiple de la
taille de huge page — soit **27 262 976 octets (26 Mo)**. Le reliquat de
1 654 784 octets n est pas perdu : il est expose comme `kReserveBytes`.
Soit **0,63 % des 4 Go du Pixel 3a**.
### Comportement
- Allocation = avance de pointeur, avec alignement calcule **sur l offset** et
non sur l adresse. La base d une arene etant alignee sur 2 Mo, cela revient
au meme — mais cela rend le comportement rigoureusement identique entre
l hote et la cible, ce qui compte pour le harnais d oracle.
- **Pas de liberation individuelle.** Un `reset()` global par arene, un
`mark()` / `rewind_to()` pour les usages en pile.
- **Un debordement est une panique**, jamais un agrandissement. Le message
donne le nom de l arene, la taille demandee, l alignement, l occupation et la
capacite :
```
proj3: PANIQUE: debordement d arene 'geometrie' : demande=4194304 align=8 occupe=0 capacite=2097152
Un debordement d arene est un defaut de conception, pas un cas
a gerer : corriger le calcul dans mem/layout.hpp.
```
- `Arena::peak()` donne la plus haute occupation atteinte. C est la seule
metrique qui permette de dire si une taille de `layout.hpp` est juste ou
fantaisiste. Cout : une comparaison par allocation.
## 3. Le garde-fou
`src/proj3/mem/new_guard.cpp` redefinit `operator new`, `operator new[]`,
`operator delete`, `operator delete[]`, ainsi que leurs formes dimensionnees et
alignees. Toutes tuent le processus immediatement :
```
proj3: ALLOCATION INTERDITE: operator new[] taille=64
Le projet n alloue rien apres l init. Tout passe par une arene
(mem/arena.hpp). Poser un point d arret sur operator new et
remonter la pile pour trouver l appelant.
```
Code de sortie **71**, distinct du **70** de `panic()`, pour qu un script sache
que c est une allocation et pas autre chose.
**Ce que le garde-fou n attrape pas**, et il faut le savoir :
- `malloc` / `calloc` / `realloc` / `free` appeles directement. Ce sont des
fonctions C, sans rapport avec `operator new`. Sur la cible embarquee la
question ne se pose pas (le lien echouerait). Sur l hote,
`page_source_host.cpp` les utilise deliberement.
- les allocations faites par le noyau (pile, `mmap`) ;
- les VLA et `alloca`, qui prennent sur la pile.
Le perimetre est donc exactement : **aucun `new` C++ nulle part**. C est ce
qu on veut verifier.
**Il est en bibliotheque separee** (`proj3_newguard`) et n est lie qu aux
executables qui pretendent ne rien allouer. Le lier partout casserait tout
outil utilisant la STL de l hote — ce qui est le comportement recherche, mais
doit etre choisi executable par executable.
Preuve qu il fonctionne : `test/test_new_guard.cpp`, declare `WILL_FAIL TRUE`
dans CTest. Le test est reussi si et seulement si le processus meurt.
## 4. A REVERIFIER lors du passage a la cible 12 Go (Poco F5 Pro)
Cette section est le point de reprise. Rien de ce qui suit n est fait.
1. **La resolution change.** Le Poco F5 Pro est en 1440x3200. Le calcul du
scanout devient `1440*3200*4 = 18 432 000` par tampon, soit **36 Mo pour
deux** au lieu de 19 Mo. `kScreenWidth` / `kScreenHeight` doivent devenir
des parametres, pas des constantes — et la question « constexpr ou lu depuis
DRM ? » se posera : une taille lue au runtime interdit le dimensionnement
`constexpr` des arenes, ce qui est un changement d architecture, pas un
ajustement.
2. **La taille de page peut differer.** Certains noyaux arm64 recents sont
compiles en pages de 16 Ko. `kPageSize` doit alors changer ; `kHugePageSize`
passerait de 2 Mo (PMD sur 4K) a 32 Mo (PMD sur 16K), ce qui invaliderait
`MAP_HUGE_2MB`.
3. **`MAP_HUGETLB` a peut-etre plus de chances d aboutir** sur un noyau plus
recent — ou pas. A verifier materiellement, pas a supposer. Si le mode 1
devient disponible sur une cible et pas sur l autre, les mesures des deux
cibles ne sont **pas comparables entre elles**.
4. **Les tailles d atlas et de geometrie ne doivent PAS etre augmentees
mecaniquement.** Elles sont dimensionnees par un raisonnement (nombre de
glyphes, nombre d aretes), pas par un pourcentage de la RAM. Plus de RAM ne
justifie pas plus d atlas ; une densite de pixels plus elevee, qui impose des
corps plus grands, oui — et il faudra refaire le calcul, pas le doubler.
5. **`kArenaTotal < RAM/64` deviendra trivialement vrai** et cessera d etre un
garde-fou utile. Le remplacer par une borne absolue reflechie.
6. **Le pic reel doit etre releve avant de retoucher quoi que ce soit.**
`Arena::peak()` existe pour cela. Redimensionner sans avoir regarde les pics
sur la cible actuelle serait du reglage a l aveugle.
+172
Voir le fichier
@@ -0,0 +1,172 @@
# Methode de l oracle — validation croisee C++ / assembleur
## 1. La regle
Toute routine critique du projet existe en **deux exemplaires** :
- une **version de reference en C++**, ecrite d abord, lisible, evidemment
correcte, jamais optimisee ;
- une **version assembleur**, ecrite ensuite, rapide, et suspecte jusqu a
preuve du contraire.
Le harnais execute les deux sur les memes entrees et compare les sorties
**octet par octet**. Pas d epsilon, pas de tolerance, pas de "presque".
## 2. La regle qui compte vraiment
> **La version C++ de reference n est JAMAIS supprimee.**
Meme quand la version assembleur est validee. Meme quand elle tourne depuis
deux ans sans incident. Meme quand la version C++ n est plus compilee en
production.
Raisons, dans l ordre d importance :
1. **Sans reference, il n y a plus d oracle.** Le jour ou l assembleur se met
a produire un resultat different apres un changement de compilateur, de
modele de CPU ou de flag, il n y a plus rien a quoi le comparer. On aurait
un bug et aucun moyen de dire ou.
2. **La reference est la specification.** Elle dit ce que la routine doit
faire, dans un langage que quelqu un peut lire dans cinq ans. Le commentaire
d en-tete d une routine NEON, non.
3. **Elle est le chemin de repli.** Un portage vers une architecture sans notre
assembleur (un simulateur, une machine de dev, une future cible) reste
possible tant qu elle existe.
La selection production/reference est un choix de compilation, jamais une
suppression de code.
## 3. Ce que le harnais garantit, et ce qu il ne garantit pas
Garanti :
- egalite exacte des octets de sortie ;
- egalite exacte de la longueur rendue ;
- absence de debordement du tampon de sortie, y compris d **un seul octet**
(zone de garde de 32 octets remplie de `0xA5`, verifiee apres chaque appel) ;
- absence d allocation dynamique, quand l executable est lie a
`proj3_newguard` — c est le cas de `proj3_oracle`.
Non garanti, et il faut le savoir :
- **la performance**. Ce harnais valide la correction, rien d autre. La mesure
de latence est un chantier distinct, plus tard, avec son propre outillage.
- **la couverture**. Le harnais teste ce qu on lui donne. Les cas explicites
sont ecrits a la main, le reste est aleatoire reproductible.
## 4. Ajouter une paire
Trois choses a ecrire, aucune modification du harnais :
```cpp
#include "oracle.hpp"
namespace proj3::oracle {
// 1. la reference C++
usize ma_routine_ref(const u8* in, usize in_len, u8* out, usize out_cap) { ... }
// 2. les cas
const CaseSpec kMesCas[] = {
{"vide", 0, 0, 0, 0},
{"16 octets", 16, 0, 0, 0},
{"desaligne +1/+3", 256, 0, 1, 3},
{"aleatoire", 4096, 0xDEADBEEFCAFEBABEull, 0, 0},
};
// 3. l enregistrement
PROJ3_ORACLE_PAIR(ma_routine, "mon::module::ma_routine",
&ma_routine_ref, &proj3_ma_routine_asm, kMesCas);
}
```
`opt` peut valoir `nullptr` : la paire est alors enregistree comme
**reference figee**, la reference est executee seule (ce qui verifie deja
qu elle ne plante pas, ne deborde pas et n alloue pas), et le harnais l affiche
comme telle. C est ainsi qu on enregistre une routine **avant** d avoir ecrit
son assembleur — ce que fait `pairs_render.cpp` pour tout le pipeline de
rendu du chantier 5.
Le champ `CaseSpec` :
| champ | role |
|---|---|
| `label` | affiche en cas d echec ; ecrire de quoi identifier le cas |
| `in_len` | taille de l entree, qui vaut aussi capacite de la sortie |
| `seed` | 0 = motif deterministe ; sinon graine du xorshift64* |
| `in_align_offset` | decalage en octets de la base d entree |
| `out_align_offset` | decalage en octets de la base de sortie |
Les tampons viennent d une arene dont la base est alignee sur 2 Mo : un
decalage de *k* octets donne donc une adresse congrue a *k* modulo 16, ce qui
est exactement le levier dont un chemin NEON a besoin pour etre teste des deux
cotes.
## 5. Le diagnostic
En cas de divergence, le harnais affiche :
```
ECHEC fill_bytes (VERSION FAUSSE) / 16 (128 bits pile)
octet divergent
rejouer ce cas : graine=0 in_len=16 align_in=+0 align_out=+0
longueurs : reference=16 optimisee=16
premier octet divergent a l offset 15 : attendu=0x5b obtenu=0x0
attendu [0..16) : 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b
obtenu [0..16) : 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 5b 00
```
Tout est la pour rejouer exactement le cas : la graine, la longueur, les deux
alignements. Le contexte de 16 octets de part et d autre permet de distinguer
d un coup d oeil un decalage d une valeur fausse.
## 6. Validation du harnais lui-meme
`proj3_oracle_selftest` execute deux passes sur la meme paire de
demonstration :
1. la version assembleur **correcte** doit etre acceptee ;
2. la version assembleur **volontairement fausse** (un octet de moins ecrit,
longueur rendue correcte — le genre de bug qu un test indulgent laisse
passer) doit etre **rejetee**.
Le test rend 0 seulement si les deux attentes sont satisfaites.
> Un harnais qui ne sait pas detecter une erreur connue ne vaut rien. C est
> pour cela que la version fausse existe et qu elle reste dans le depot.
## 7. Ou tourne quoi — limite assumee
| executable | cible | ce qu il compare |
|---|---|---|
| `proj3_oracle` | hote | reference C++ contre asm **x86-64**, pour la paire de demonstration seulement. Les autres paires sont en reference figee. |
| `proj3_oracle_selftest` | hote | la meme paire, correcte puis fausse |
| `proj3_oracle_target` | AArch64 | reference C++ contre asm **AArch64**, toutes paires |
La machine de developpement ne peut pas executer de l AArch64. Pour que la
preuve « le harnais sait rejeter une erreur » puisse etre faite **sur la
machine de dev**, la paire de demonstration est ecrite deux fois :
`asm/demo_fill_aarch64.S` et `asm/host/demo_fill_x86_64.S`.
**Ce doublon ne sera pas etendu.** Les vraies routines optimisees seront
ecrites en AArch64 seulement ; leur comparaison se fera sur la cible, avec
`proj3_oracle_target`. Sur l hote elles apparaitront comme « reference figee,
version assembleur absente ». C est une limite de la double cible, pas un
oubli.
## 8. Hypotheses numeriques
La comparaison octet-a-octet entre l hote et la cible n a de sens que si les
deux calculent rigoureusement pareil. Ce qui est suppose, et pourquoi c est
vrai :
| hypothese | justification |
|---|---|
| `float` = IEEE-754 binary32, `double` = binary64 | vrai sur AArch64 et x86-64 |
| mode d arrondi round-to-nearest-even | valeur par defaut, et aucune routine du projet ne touche `fpcr` ni `mxcsr` (regle inscrite dans `convention-aarch64.md` 1.4) |
| pas de precision excedentaire | x86-64 calcule en SSE2, pas en x87 80 bits ; AArch64 n a pas de format etendu |
| `sqrt` correctement arrondi | `fsqrt` (A64) et `sqrtsd` (SSE2) le sont, par la norme |
| pas de `-ffast-math` | seul `-fno-math-errno` est utilise, et il ne change aucune valeur : il supprime uniquement la mise a jour d `errno`, dont le projet n a pas |
| little-endian des deux cotes | `static_assert` sur `__BYTE_ORDER__` dans `base/types.hpp` |
Si l une de ces hypotheses tombait, le harnais deviendrait un generateur de
faux positifs. Elles sont donc listees ici, et non enfouies dans un
commentaire.