7.1 KiB
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 :
- 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.
- 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.
- 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 deproj3_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 :
#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 :
- la version assembleur correcte doit etre acceptee ;
- 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.