173 lignes
7.1 KiB
Markdown
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.
|