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