// test/oracle/oracle.hpp — harnais de validation croisee C++ / assembleur. // // METHODE (doc/methode-oracle.md) : // Toute routine critique existe en deux exemplaires : une reference C++ qui // marche, et une version assembleur qui va vite. Le harnais les execute sur // les MEMES entrees et compare les sorties OCTET PAR OCTET. Pas d epsilon, // pas de tolerance. La reference C++ n est jamais supprimee. // // AJOUTER UNE PAIRE : ecrire deux fonctions de signature RunFn, un tableau de // CaseSpec, et une ligne PROJ3_ORACLE_PAIR. Aucun fichier du harnais n est a // modifier. C est la condition pour qu il serve encore dans six mois. #pragma once #include "proj3/base/types.hpp" #include "proj3/mem/arena.hpp" #include "proj3/mem/system.hpp" namespace proj3::oracle { // Arenes du programme, publiees pour que les paires puissent s en servir sans // que la signature RunFn ait a les transporter. Positionne par le point // d entree avant run_all(). Une paire qui l utilise doit rembobiner ce qu elle // prend (mark/rewind_to) : le harnais ne le fait que pour SES tampons. extern mem::System* g_system; // Signature unique de toute routine testable. // in / in_len : entree en lecture seule // out / out_cap : sortie, deja remise a zero par le harnais // retour : nombre d octets ecrits (compare lui aussi) // // Tout passe par des octets. Une routine qui manipule des structures les // reinterprete depuis `in` : c est volontairement fruste, parce que c est ce // qui permet a UN harnais de comparer n importe quelle paire sans savoir de // quoi elle parle. using RunFn = usize (*)(const u8* in, usize in_len, u8* out, usize out_cap); struct CaseSpec { const char* label; usize in_len; // Graine du generateur pseudo-aleatoire. 0 = cas deterministe explicite : // l entree est remplie par un motif fixe (voir fill_deterministic). u64 seed; // Decalage applique a la base des tampons, en octets, pour forcer un // desalignement. Les routines NEON auront des chemins differents selon // l alignement : il faut pouvoir tester les deux. u8 in_align_offset; u8 out_align_offset; }; struct Pair { const char* name; RunFn ref; // nullptr autorise : la paire existe, la version assembleur n est pas // encore ecrite. Le harnais execute alors la reference seule (pour // verifier qu elle ne plante ni n alloue) et signale la paire comme // "reference figee, asm absent". C est ce qui permet d enregistrer une // routine AVANT d avoir son asm, comme demande au chantier 5. RunFn opt; const CaseSpec* cases; usize case_count; }; // --- Enregistrement -------------------------------------------------------- // // Deux mecanismes, un par cible, derriere la meme macro : // // Cible embarquee : les pointeurs de paires sont places dans une section ELF // nommee `proj3_pairs`. L editeur de liens synthetise automatiquement // __start_proj3_pairs / __stop_proj3_pairs pour toute section dont le nom // est un identifiant C valide. AUCUN constructeur statique n est // necessaire — c est indispensable ici, puisque asm/start.S ne parcourt // pas .init_array (cf. ADR-0001). // // Cible hote : le format PE de MinGW ne synthetise pas ces symboles. On // retombe sur un constructeur statique qui chaine la paire dans une liste. // L hote, lui, a un vrai demarrage C++ : c est sans risque. // // L asymetrie est laide mais elle est confinee a ces vingt lignes, et elle // evite d imposer un enregistrement manuel qui, lui, serait oublie. void register_pair(const Pair* p); struct Registrar { explicit Registrar(const Pair* p) { register_pair(p); } }; #if PROJ3_EMBEDDED #define PROJ3_ORACLE_PAIR(ident, name_str, ref_fn, opt_fn, cases_arr) \ static const ::proj3::oracle::Pair ident##_pair = { \ name_str, ref_fn, opt_fn, cases_arr, \ sizeof(cases_arr) / sizeof(cases_arr[0])}; \ __attribute__((used, section("proj3_pairs"))) static const ::proj3::oracle::Pair* \ const ident##_slot = &ident##_pair #else #define PROJ3_ORACLE_PAIR(ident, name_str, ref_fn, opt_fn, cases_arr) \ static const ::proj3::oracle::Pair ident##_pair = { \ name_str, ref_fn, opt_fn, cases_arr, \ sizeof(cases_arr) / sizeof(cases_arr[0])}; \ static const ::proj3::oracle::Registrar ident##_slot(&ident##_pair) #endif // --- Execution ------------------------------------------------------------- struct Report { u32 pairs_run = 0; u32 pairs_ref_only = 0; u32 cases_run = 0; u32 cases_failed = 0; }; // Execute toutes les paires enregistrees. `work` fournit les tampons. // Rend true si aucune divergence. bool run_all(mem::Arena& work, Report& out); // Execute UNE paire donnee, sans passer par l enregistrement. Sert au // self-test du harnais (prouver qu il rejette une implementation fausse). bool run_pair(const Pair& p, mem::Arena& work, Report& out, bool expect_failure); // Generateur pseudo-aleatoire reproductible : xorshift64*. // Choisi parce qu il tient en quatre lignes, n a aucun etat cache, et donne // exactement la meme suite sur AArch64 et sur x86-64 (arithmetique entiere // 64 bits non signee uniquement, aucun flottant). struct Rng { u64 state; explicit constexpr Rng(u64 seed) : state(seed == 0 ? 0x9E3779B97F4A7C15ull : seed) {} u64 next() { state ^= state >> 12; state ^= state << 25; state ^= state >> 27; return state * 0x2545F4914F6CDD1Dull; } }; } // namespace proj3::oracle