Premier commit
Cette révision appartient à :
révision
536792a769
62 fichiers modifiés
+6766
Aucun fichier ne correspond à votre recherche
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Référencer dans un nouveau ticket
Bloquer un utilisateur