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

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 :

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