Fichiers
ui/doc/methode-oracle.md
T
2026-10-11 01:55:22 +02:00

173 lignes
7.1 KiB
Markdown

# 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.