Fichiers
ui/test/oracle/oracle.hpp
T
2026-10-11 01:55:22 +02:00

135 lignes
5.6 KiB
C++

// 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