dolphin/Tools/PerformanceTrace/README.md

Diagnostic P1 : statut et exécution locale

Le protocole et les critères de décision sont dans docs/Wii_LLE_Performance_Diagnostic_Protocol.md. Tous les artefacts volumineux vont dans .starlet-profile (ignoré par Git), jamais dans la NAND source ni dans le profil utilisateur courant.

1. Construire le profil isolé avec ./Tools/PerformanceTrace/Build-P1.ps1. Après modification d'une option de compilation, -CleanBeforeBuild vérifie tous les objets. Le script répare le préfixe français /showIncludes si cette installation MSVC l'a mal décodé ; un objet avec #deps 0 invalide la build.

2. Vérifier les tests ciblés de Binaries/Tests/tests.exe et le décodeur avec ./Tools/PerformanceTrace/Build-Decoder.ps1 -OutputDirectory .starlet-profile/P1-tools.

3. Sur une session Windows sans droit de profilage noyau, valider d'abord le fournisseur dans une session ETW privée :

   ./Tools/PerformanceTrace/Capture-Private-P1.ps1 -OutputDirectory .starlet-profile/P1-private-NEW
   python Tools/PerformanceTrace/qualify_p1.py .starlet-profile/P1-private-NEW
   

   Le résultat attendu est local_provider_passed=true et full_collector_passed=false. Cette session ne contient aucun échantillon CPU, changement de thread ou attente disque. Le mode -NoTrace exécute exactement la même charge pour une comparaison locale alternée. Exemple avec quatre répertoires neufs, à exécuter dans cet ordre :

   ./Tools/PerformanceTrace/Capture-Private-P1.ps1 -OutputDirectory .starlet-profile/P1-off-1 -NoTrace
   ./Tools/PerformanceTrace/Capture-Private-P1.ps1 -OutputDirectory .starlet-profile/P1-on-1
   ./Tools/PerformanceTrace/Capture-Private-P1.ps1 -OutputDirectory .starlet-profile/P1-off-2 -NoTrace
   ./Tools/PerformanceTrace/Capture-Private-P1.ps1 -OutputDirectory .starlet-profile/P1-on-2
   python Tools/PerformanceTrace/compare_p1.py .starlet-profile/P1-off-1 .starlet-profile/P1-on-1 .starlet-profile/P1-off-2 .starlet-profile/P1-on-2 --output .starlet-profile/P1-private-overhead-NEW.json
   

   Ce comparateur conserve les quatre mesures et la dispersion ; il ne peut pas valider le budget de 2 % de la capture WPR complète.

4. Capture synthétique WPR complète dans une session administrateur, avec un nouveau chemin de sortie :

   ./Tools/PerformanceTrace/Capture-Local-P1.ps1 -OutputDirectory .starlet-profile/P1-local-NEW
   

   Ce programme exécute une boucle Thumb réelle, un sommeil hôte connu, 128 transactions de journal synthétique et 32 échanges ARP avec la passerelle locale libslirp. Le journal synthétique reste dans ce répertoire neuf. Aucun serveur externe n'est contacté par l'échange ARP.

5. Après la capture, décoder et qualifier hors ligne (sans droit administrateur) dans un nouveau répertoire :

   ./Tools/PerformanceTrace/Analyze-Local-P1.ps1 `
     -CaptureDirectory .starlet-profile/P1-local-NEW `
     -OutputDirectory .starlet-profile/P1-local-NEW-analysis
   

   Le lecteur TDH extrait les événements natifs ; Xperf décode les événements noyau classiques, résout les PDB locaux et les deux flux sont alignés par les QPC des marqueurs ou des snapshots périodiques. Le CSV, l'ETL et les données de profil peuvent contenir des noms de processus ou chemins : ils restent locaux et ignorés par Git. Le répertoire de sortie doit être neuf à chaque tentative.

6. Mesurer le surcoût WPR avec une seule commande administrateur et un nouveau répertoire. Elle automatise quatre paires alternées OFF/ON du même travail synthétique (huit lancements locaux, aucun démarrage Wii ni NAND utilisateur) :

   ./Tools/PerformanceTrace/Measure-P1-Overhead.ps1 -OutputDirectory .starlet-profile/P1-overhead-001
   

   comparison.json conserve les durées brutes, la dispersion des bases OFF, les écarts par paire et une borne supérieure de confiance. Le seuil de 2 % ne passe que si les données restent stables et les trois mesures ARM/mur/CPU satisfont ce seuil. Python est vérifié avant toute capture ; si un lot s'est interrompu uniquement au calcul final, -AnalyzeOnly relit les huit captures existantes sans en relancer aucune. -PythonExecutable permet de préciser le chemin de python.exe si le PowerShell administrateur n'a pas le même PATH. Un résultat négatif ou bruité n'autorise aucun diagnostic de vitesse Wii.

qualification.json détaille chaque gate. Une sonde locale réussie ne constitue pas encore une analyse de mise à jour Wii : le cas PPC, les piles hôte et le surcoût du collecteur restent à qualifier. La capture native n'est prévue qu'après ces vérifications. Le profil WPR comporte une session au nom unique et le script arrête seulement cette session.

Le 22 septembre, deux traces privées ont validé les 13 contrôles du fournisseur (P1-private-004, P1-private-006). Le jeton CodexSandboxUsers ne pouvait pas lancer WPR (0xc5585011), mais la capture synthétique administrateur P1-local-004 a réussi. Sous Windows PowerShell 5.1, le premier essai avait révélé ProcessStartInfo.ArgumentList nul et une résolution de chemin relatif depuis le répertoire de processus plutôt que celui affiché par cd ; les deux cas sont corrigés et testés.

L'analyse reproductible P1-local-004-reanalysis2 passe 13 contrôles du fournisseur et 3 contrôles système : 9 427 échantillons CPU, 694 changements de contexte, dix ancres QPC alignées à cinq ticks près, sommeil connu de 752 ms avec un switch Waiting. Les 112 événements classiques déclarés invalides par Xperf concernent une métadonnée ImageID hors du PID de la sonde ; zéro événement cible invalide et zéro perte ETW. Les symboles du PDB local résolvent les fonctions hôte. Cela valide la sonde, pas la capture native : coût du collecteur WPR, cas PPC et chemin critique Wii restent ouverts. Identification du GUID ImageID dans le code Microsoft PerfView.

Le lot P1-overhead-001 du 22 septembre a produit les huit captures complètes, mais son PowerShell administrateur ne trouvait pas Python lors de la comparaison. Les données conservées ont été comparées hors ligne, sans recapture : les bases OFF varient de 34,5 % pour la phase ARM et 26,8 % sur le temps total. Les écarts ARM par paire sont +9,7 %, +25,0 %, -0,5 % et +1,0 %. Le surcoût WPR ne peut donc pas être isolé de la variabilité de cette série et le budget de 2 % reste non qualifié. Le rapport brut est .starlet-profile/P1-overhead-001/comparison.json ; aucune mesure de vitesse Wii n'en est déduite. Les traces ON montrent cpptools.exe consommant environ 8–9 s de CPU par essai et des sous-processus Dell intermittents ; ces charges hôte sont une piste de contamination, pas une attribution causale chiffrée des écarts ON/OFF. Dans wpr-on-2, 76 768 événements ReadyThread système ont été enregistrés. Le profil conserve ces événements et leurs horodatages mais ne collecte plus leur pile, afin de réduire le coût potentiel de cette source système très fréquente ; le profil modifié doit être requalifié séparément.

Le lot P1-overhead-002, après cet allègement, n'a pas perdu d'événements mais garde 36,5 % d'étendue ARM entre bases OFF. Ses quatre écarts ON/OFF sont +4,6 %, -11,0 %, +10,2 % et -3,5 % ; leur moyenne proche de zéro ne qualifie pas le budget. L'analyse des échantillons ETW révèle un changement de placement CPU : part sur les processeurs logiques 0–3 de 78,7 %, 45,4 %, 28,9 %, 46,5 % pour des phases ARM de 7,59 s, 8,82 s, 10,33 s, 8,65 s. L'ETL identifie un Core i7-1255U et SMT sur 0–3 ; Intel indique 2 P-cores et 8 E-cores. Ce placement est fortement associé à la durée, sans prouver qu'il explique à lui seul tout l'écart. Le lancement Wii existant fixe déjà Dolphin sur ces processeurs ; la sonde synthétique, elle, n'était pas fixée.

Les captures de sonde acceptent maintenant -ProbeAffinityMask, enregistrent le masque réellement appliqué, et le comparateur refuse les masques différents. Quatre bases locales sans WPR avec -ProbeAffinityMask 15 ont fini leur phase ARM en 7,03, 6,65, 7,20 et 6,97 s (masque observé 15 à chaque fois). Le placement est contrôlé, mais une variabilité résiduelle de 8,3 % subsiste : aucun nouveau lot administrateur n'est demandé avant de traiter cette limite du protocole ou de passer à un diagnostic qualitatif explicitement borné.

Première capture d'une vraie mise à jour (exploratoire)

Prepare-Native-Update-P1.ps1 crée un profil NAND pré-mise-à-jour indépendant, vérifie les 31 fichiers et le journal, puis fige l'exécutable et son PDB. Il refuse tout nom déjà utilisé et ne lance pas Dolphin. L'expérience préparée ici est P1-trace-002 ; le profil courant .starlet_user3 et les résultats A–F ne sont pas modifiés. La capture ETW requiert un PowerShell administrateur. La préparation dépend d'un seed NAND local ignoré par Git et demande désormais un -PythonExecutable explicite ; elle n'est pas une procédure de création de NAND dans un clone neuf.

# Terminal administrateur : démarrer d'abord, puis laisser ouvert.
cd C:\Users\tpetkovic\Desktop\dolphin
.\Tools\PerformanceTrace\Capture-P1.ps1 -OutputDirectory .starlet-profile/P1-native-update-001 -Seconds 600

# Dès « Native collector armed », dans un autre PowerShell :
cd C:\Users\tpetkovic\Desktop\dolphin
.\Run-Wii-IOS-LLE.ps1 `
  -BuildDirectory .starlet_update_ab_20260913/build-P1-trace-002 `
  -UserDirectory .starlet_update_ab_20260913/P1-trace-002 `
  -Ethernet -PerformanceTrace

Noter le PID imprimé par le lanceur, lancer la mise à jour dans la Wii, puis laisser terminer la capture. Analyser ensuite l'ETL hors ligne dans un nouveau répertoire :

.\Tools\PerformanceTrace\Analyze-Local-P1.ps1 `
  -CaptureDirectory .starlet-profile/P1-native-update-001 `
  -OutputDirectory .starlet-profile/P1-native-update-001-analysis `
  -NativePID <PID_DOLPHIN> `
  -NativePDB .starlet_update_ab_20260913/build-P1-trace-002/pdb/DolphinNoGUI.pdb

Le rapport native-report.json reste exploratoire : perte ETW et alignement QPC sont contrôlés, mais piles, attentes critiques, NAT et surcoût de capture doivent encore être qualifiés avant d'attribuer le ralentissement ou d'annoncer un gain de FPS. La mise à jour nécessite une action Wii réelle et un réseau disponible ; ne pas essayer de la rejouer sur le même profil après succès.

Windows exige un droit de profilage pour le profil noyau ; un logger privé du processus fonctionne avec un compte peu privilégié. Sessions privées ETW, droits de StartTrace.

Décision après A/B natif du 23 septembre

Le rapport P1 contient les deux mises à jour NAND isolées et vérifiées. Le raccourci SRAM ciblé a été rejeté : sur ce passage, le témoin a terminé les mêmes seuils de journal plus vite et a été jugé plus fluide. Le raccourci a été retiré du source ; ses deux binaires et journaux figés restent locaux pour audit. Les outils de ce dossier servent au diagnostic, pas à justifier une modification matérielle sans test de conformité sur Wii réelle.