
J’adore Metal Gear Solid depuis que je suis gamin. Quand j’ai reçu une minuscule carte ESP32-S3, une question m’est restée en tête : un jeu PlayStation pouvait-il tourner sur quelque chose d’aussi petit ?

La carte est le Seeed Studio XIAO ESP32S3 Sense : un ESP32-S3 double cœur avec 8 Mo de PSRAM et 8 Mo de flash, sur un module de 21 × 17,8 mm. La version Sense ajoute une carte d’extension avec une caméra et un emplacement microSD, et c’est dans cet emplacement microSD que résident les données du jeu.
J’ai passé un bon moment à chercher. D’abord, j’ai cherché une version du jeu qui avait déjà été reconstruite en code C tournant sur PC, puis j’ai vérifié si toute cette logique pouvait tenir dans la flash de l’ESP32-S3 et sur une carte microSD. Il a fallu plusieurs tentatives, mais au final, ça a marché. Un jeu merveilleux tourne désormais sur une carte microcontrôleur qui coûte environ 15 USD.
Gameplay sur la console portable : regardez sur YouTube.
Dans cet article, je décris comment Metal Gear Solid (PlayStation, 1998) tourne sur l’ESP32-S3 en tant que portage natif. Le code source C du jeu, reconstruit par la décompilation mgs_reversing de la FoxdieTeam, est compilé directement en code machine Xtensa. Tout ce que le matériel PlayStation fournissait auparavant est remplacé par du logiciel :
- Le SDK.
- Le GPU.
- Le coprocesseur géométrique GTE.
- Le lecteur CD.
- L’interruption de blanking vertical.
- La manette.
L’article couvre le matériel, la couche de plateforme, le placement mémoire, la méthode de débogage, les bugs qui ont le plus compté, les performances, la console portable, et ce qui ne fonctionne pas encore.
Le code et les projets associés :
- Portage MGS : davidmonterocrespo24/mgs_reversing, branche
esp32-port. - Guide matériel de la console portable : HARDWARE.md.
- Fork de psyz : davidmonterocrespo24/psyz.
Vous avez besoin de votre propre disque. Le dépôt ne contient rien de dérivé du jeu, et port/extract_disc.py extrait les fichiers de votre propre image de disque.
Matériel

L’ESP32-S3 possède deux cœurs Xtensa à 240 MHz et 512 Ko de SRAM interne. Les deux cartes utilisées ici disposent également de 8 Mo de PSRAM, qui se trouve derrière le même cache que la flash.
| Waveshare ESP32-S3-Touch-LCD-2 | Console portable DIY (Seeed XIAO ESP32S3 Sense) | |
|---|---|---|
| Écran | ST7789, 320x240 | ILI9341, 320x240 natif |
| Flash | 16 Mo | 8 Mo |
| Données du jeu | microSD, ou un STAGE.DIR tronqué en flash | microSD (STAGE.DIR complet) |
| Entrée | clavier via port série (play.py) | joystick de nacelle de drone, échelle de résistances à 6 boutons, 2 boutons directs |
Mesurer l’écart avant d’écrire du code
Avant d’écrire le moindre code de portage, j’ai mesuré à quelle distance la décompilation se trouvait d’une compilation pour Xtensa :
- Les bibliothèques du moteur (libgv, libdg, libgcl, libhzd, libfs) se sont compilées presque immédiatement avec
xtensa-esp32s3-elf-gcc14.2 contre les en-têtes de psyz : 57 fichiers sur 58. - Aucune d’entre elles ne contient d’adresses absolues
0x800xxxxx. - Toute la sortie graphique passe par 11 appels libgpu (
DrawOTag,LoadImage,ClearOTagR, etc.). C’est exactement la couche que le rendu logiciel de psyz remplace.
J’ai laissé le seul fichier qui échouait, libdg/chanl.c, échouer volontairement. Le cast qui l’aurait fait taire aurait aussi silencieusement modifié le pas (voir la section sur la table d’ordonnancement ci-dessous).
Le reste a nécessité des passes mécaniques, chacune corrigeant toute une classe de problèmes :
-std=gnu17et-mlongcallssont tous deux obligatoires. Le gnu23 par défaut de GCC 14 rejette ce code, et lecall8de Xtensa n’atteint que +/-512 Ko.- psyz et MGS ont tous deux un
common.h, donc les chemins d’inclusion de MGS doivent venir en premier. - 12 expressions de cast en tant que lvalue, une extension de GCC 2.x, ont été réécrites.
- MGS remplace le
printfde la libc par son propre stub. Je l’ai renommémts_printf, et cela a ensuite causé l’un des bugs les plus trompeurs (voir « Le démarrage qui semblait bloqué »). - 346 adresses littérales de scratchpad (
0x1f8000xx) réparties sur 16 fichiers sont devenuesSCRPAD_ADDR + offset, soutenues par un tableau.
Le résultat fut 497 fichiers C sur 497 compilés pour Xtensa. L’ELF avait 0 référence non définie et 0 définition en double (text 987 073 B, bss 2 434 276 B). La mémoire propre du jeu est de 804 Kio (428 Kio de tas plus deux tampons de paquets de 188 Kio), ce qui tient confortablement dans la PSRAM.
----- END POST -----
Architecture
Le portage comporte trois couches entre le jeu et le SoC :
Les couches, du jeu jusqu’au matériel :
- Moteur MGS — C décompilé, compilé pour Xtensa
- psyz — SDK PlayStation et GTE en C, rasterizer logiciel
- Couche de plateforme — ordonnanceur mts sur FreeRTOS, tick vblank, CD virtuel, LCD, entrées
- ESP32-S3
psyz et le GTE
psyz, la réimplémentation du SDK PlayStation par Xeeynamo, modélisait déjà tout le fichier de registres du GTE et chaque opération du GTE en C, validée contre la suite de tests GTE de PCSX-Redux.
Ma première estimation était qu’il manquait 64 à 70 macros. Cette estimation était trop élevée. MGS embarque ses propres en-têtes d’asm inline MIPS (inline_n.h, inline_x.h), et -fsyntax-only ne vérifie pas les noms de registres. Une fois ces en-têtes redirigés vers psyz, le manque réel était de 41 macros. Je les ai ajoutées à psyz, en utilisant l’assembleur du jeu lui-même comme spécification des registres COP2 que chacune touche. J’ai ensuite reconstruit mes autres projets basés sur psyz contre le psyz modifié pour m’assurer que rien n’était cassé.
Quand vous créez un alias pour une macro GTE, vérifiez si chaque contrainte est une entrée ou une sortie. Par exemple, gte_read_opz a une sortie "=r", donc son alias doit prendre &x.
Le tag de table d’ordonnancement — un mot sur PSX, deux dans psyz
C’est la différence de disposition la plus importante, et c’est elle qui a causé le plus de bugs. Sur la PlayStation, chaque primitive commence par un tag de 32 bits — 24 bits d’adresse de la primitive suivante et 8 bits de longueur. Un pointeur hôte ne tient pas sur 24 bits, donc psyz utilise deux mots, tag et len. Chaque primitive grandit de 4 octets, et chaque champ après le tag se décale d’un mot.
MGS abuse aussi de l’octet de longueur. libdg effectue un tri radix en deux passes sur la profondeur 16 bits :
divide.crépartit selon l’octet bas et range l’octet haut dans la longueur du tag.sort.cré-répartit selon cet octet haut et écrit la longueur réelle.
Comme psyz sépare les deux champs, la traduction est exacte :
pack->tag = (hi << 24) | *ot; *ot = pack; /* PSX */
addPrim(ot, pack); setlen(pack, hi); /* psyz */
Retyper 42 déclarations locales et 100 paramètres en OT_TYPE* était la partie facile. La partie difficile était le code qui supposait la disposition compactée sans le dire :
DG_PrimInfosplaçait le premier vertex à +8 au lieu de +12.LinkModelToParentprécalculait les offsets de vertex parent comme*52 + 8au lieu de*56 + 12.- Les constructeurs de primitives décrits dans « L’écran blanc » ci-dessous.
Il y a aussi un facteur aggravant. Sur la console, addPrim() réécrivait tout le mot de tag à chaque insertion, donc une longueur oubliée ne pouvait jamais passer inaperçue. Dans psyz, une longueur qui n’a jamais été définie n’est simplement jamais écrite.
L’ordonnanceur de Konami dans FreeRTOS
MGS tourne sur l’ordonnanceur coopératif propre à Konami. La bannière de démarrage affiche encore Multi Task Scheduler for PSX ver2.02 Jul 11 1998. Il repose sur l’API de threads du BIOS (OpenTh/ChangeTh) et utilise l’interruption vblank pour réveiller les tâches dont les timers ont expiré.
Dans le portage, chaque thread mts est une tâche FreeRTOS, et une seule d’entre elles est exécutable à un instant donné. La conception finale :
- Toutes les tâches mts sont épinglées sur le cœur 0, avec le tick vblank en priorité 10, de sorte que le tick préempte le jeu comme le faisait l’interruption PSX. Le scanout LCD tourne sur le cœur 1. Croiser ces affectations causait des races qui ressuscitaient des tâches parquées en plein milieu de leur pile. Un log montrait deux copies de
Main()entrelacées ligne par ligne. - Une nouvelle tâche se suspend elle-même dans son trampoline.
xTaskCreatesuivi devTaskSuspendn’est pas atomique, et sur deux cœurs la tâche s’exécutait avant que son bloc de contrôle soit rempli. - Les sections critiques sont réelles. Chaque tâche a un flag absolu, sauvegardé et restauré à chaque commutation comme le registre de statut MIPS. C’est un flag plutôt qu’un compteur parce que le jeu appelle
ExitCriticalSectionsansEntercorrespondant. - Le tick n’exécute le callback mts que tant que la tâche idle (11) est active. Cette tâche est la boucle de console SIO de Konami, le seul code qui ne touche jamais à l’état de l’ordonnanceur. Sur la console, elle tournait avec les interruptions activées pour exactement cette raison. Le jeu passe par l’idle à chaque frame, donc la latence de réveil reste sous une frame. Ce changement a éliminé les blocages intermittents à la source, là où les versions antérieures basées sur des flags n’avaient fait que réduire la fenêtre de race.
mts_GetTcbEntry lisait aussi la table des tables du BIOS à l’adresse fixe 0x100 et écrivait à travers le résultat. En dehors d’une PSX, cette adresse contient des données aléatoires, donc il utilise maintenant une table TCB privée.
Le tick vblank et les deux horloges
port/esp32_vblank.c déclenche le callback VSync du jeu toutes les 16 ms. Cela nécessitait que VSyncCallback() soit implémenté dans psyz, où il ne stockait même pas le pointeur.
VSync(-1) doit renvoyer un compteur vblank libre. La première version renvoyait le nombre de frames présentées, qui cesse d’avancer quand rien ne dessine, donc aucun timer n’expirait jamais.
Le taux de rafraîchissement varie — 2 vblanks par frame dans un couloir, 4 à 5 dans une salle ouverte. À cause de cela, deux choses qui semblaient relever du vblank appartiennent en réalité à la frame du jeu :
- Les maintiens de touches série sont décrémentés dans
DG_ActFirst, juste aprèsGV_UpdatePadSystem, le seul point qui signifie « une frame a lu le pad ». Compter les vblanks à cet endroit faisait soit trop marcher Snake, soit relâchait les touches avant que le jeu ne les voie. - Le LCD n’envoie une frame que lorsqu’un numéro de séquence incrémenté dans
DG_SwapFramea changé, avec un fallback de 250 ms.
Placement mémoire
La SRAM interne est rare et rapide. La PSRAM est abondante et lente. Les lectures en flash désactivent le cache dont dépend aussi la PSRAM.
- La carte RAM du jeu dépend d’un seul define,
MEM_BOTTOM. Les deux arènes de paquets, le tas et le buffer de secteur de libfs en découlent par soustraction. Elle est relocalisée sur un tableau PSRAM statique (mgs_main_ram[0xC9000],EXT_RAM_BSS_ATTR). Elle doit être statique parce queRESIDENT_BOTTOMest utilisé comme initialiseur statique, ce qui exclutmalloc. - Le 1 Mo de VRAM PSX réside en PSRAM. Sans
EXT_RAM_BSS_ATTR, dram0 déborde d’environ 900 Ko. - Les piles de tâches ont fait des allers-retours.
- Des piles de 32 Ko en SRAM interne faisaient échouer silencieusement le quatrième
xTaskCreate(voir « Un interblocage de priorité qui était un malloc échoué »). - Les piles déplacées en PSRAM fonctionnaient jusqu’à ce qu’une tâche appelle
fopen. Le pilote flash désactive le cache, la tâche perd sa propre pile, et le SoC redémarre sans afficher de panic. - Les piles font maintenant 20 Ko en SRAM interne. Les high-water marks montrent cinq tâches utilisant environ 2 Ko et une utilisant 14 484 o.
- Des piles de 32 Ko en SRAM interne faisaient échouer silencieusement le quatrième
- Un stub avec le mauvais type finit en flash en lecture seule.
_spu_transferCallbackest un pointeur de fonction. Le déclarer comme fonction le plaçait dans.text, donc le premier= 0plantait. Je l’ai trouvé en exécutantnmsur un ELF fonctionnel basé sur psyz et sur celui-ci, en les comparant aveccomm, et en listant les symboles qui sontB/Dlà-bas etTici.
Une classe de bugs n’existe que sur cette carte mémoire — les tests de pointeurs basés sur le bit de signe. MGS distingue un pointeur de bloc de script d’un proc id 16 bits avec proc_id < 0. La RAM PSX est à 0x8xxxxxxx, qui est négatif en valeur signée. La PSRAM est à 0x3Cxxxxxx, qui est positif. Le résultat était PROC 3C1987D2 NOT FOUND, suivi d’un LoadProhibited à EXCVADDR 0x00000003. Une macro GCL_IS_BLOCK_PTR corrige le site qui était touché. D’autres sites avec le même motif nécessitent encore un audit.
Un CD virtuel sur FAT
libfs travaille en secteurs absolus. Il lit le répertoire ISO9660 une fois et ne réutilise plus jamais un nom de fichier. port/virtual_cd.c remplace le BIOS CD :
- Chaque fichier reçoit une plage synthétique de 1 000 000 de secteurs, donc un numéro de secteur se remappe vers (fichier, offset) avec une division.
CDBIOS_ReadRequestlivre les données secteur par secteur et appelle un callback après chaque secteur. Le callback peut réécrire la taille restante.FS_CdStageFileIniten dépend pour apprendre la taille de la tableSTAGE.DIRà partir de ses 4 premiers octets. Traiter la requête comme une simple copie d’octets et ignorer le callback faisait que chaque recherche de stage renvoyaitNOT FOUND.- La livraison doit être asynchrone. Le parseur et le « disque » sont des coroutines partageant une même fenêtre de buffer. Tout livrer d’un coup laissait le fichier 2 écraser le fichier 1 avant qu’il ne soit parsé.
ReadRequestne fait maintenant qu’enregistrer la requête, etReadSyncpompe les secteurs jusqu’à ce que le callback renvoie 2 (« buffer redirigé »).
Les données vivaient d’abord en PSRAM, ce qui limitait le jeu à une poignée de stages. La vraie solution était la microSD. La carte est un périphérique SPI, séparé de la flash XIP, donc la lire ne désactive pas le cache d’instructions. Les fichiers restent sur la carte et ne coûtent pas de PSRAM.
- Le
STAGE.DIRcomplet de 71 892 992 octets (les 96 stages) est lu à la demande. - Sur 93 fichiers de stage, 65 ont des tables d’acteurs entièrement symboliques. Les 28 autres contiennent encore des adresses MIPS brutes parce que leur code d’acteur n’est pas décompilé.
- Un générateur construit une table d’acteurs dédupliquée et une liste blanche — 56 stages et 149 classes d’acteurs. La commande de changement de stage du script vérifie la liste blanche pendant que le monde courant est encore intact.
La carte et le LCD partagent SPI2, et ESP-IDF n’arbitre pas entre eux. Une frame LCD représente 30 transferts asynchrones en file, donc une lecture de carte au milieu d’une frame déclenchait assert failed: spi_hal_iram.c:134 et provoquait une boucle de redémarrage. Le correctif est une propriété explicite du bus (Mgs_SpiBusTake/Give), vidant les transferts en cours avant de libérer le bus.
Méthode — mesurer, ne pas deviner
Environ un tiers des explications évidentes de ce projet se sont révélées fausses. Ce qui a fonctionné, c’était d’amener la carte à afficher un nombre permettant de trancher entre les hypothèses. Les leçons les plus utiles sont venues de sondes qui donnaient de mauvaises réponses :
- Un compteur que personne n’incrémente invente une conclusion.
[trap] scanning 63 triggers, 0 entered so fara failli devenir « le système de déclencheurs est mort ». Le compteur n’avait pas de++. Avec un vrai, les déclencheurs se sont activés dès la première seconde. - Une vérification tautologique donne une fausse confiance. L’audit du squelette comparait
|R·t|avec|t|. Ces valeurs sont égales pour n’importe quelle rotation, donc la vérification est restée au vert pendant des semaines alors que chaque squelette était déformé (voir « L’aliasing strict a supprimé une rotation »). - Vérifiez où un champ est écrit avant de l’interpréter.
eye_inv.tressemble à une position de caméra mais c’est un vecteur directionnel tourné. Le lire comme une position a produit une histoire détaillée et fausse sur une caméra qui s’envole. - Gardez une sonde large jusqu’à ce que les données la restreignent. J’ai filtré la sonde des primitives plein écran aux primitives non texturées, en partant de l’idée qu’un flash n’a pas de texture. Un cône de projecteur en a une.
- Séparez les compteurs par cause. « 65 % des coutures sont obsolètes » regroupait quatre causes dans un seul compteur, et la principale était des objets racines inoffensifs. Après la séparation, mon correctif s’est déclenché zéro fois, et je l’ai supprimé.
- Instrumentez les N écrivains. Quand
DG_UnDrawFrameCount = 0x7fff0000a noirci l’écran, je me suis trompé deux fois. En étiquetant les quatre écrivains avec"file:line",game/gamed.c:476a été identifié immédiatement. - Décodez les données avant de suspecter l’interpréteur. Le script du dock semblait exécuter une seule commande. Le décodage du bytecode retail a montré 19 nœuds, dont un seul affiche quelque chose (voir « Le dock vide était un script en deux passes »).
- Vérifiez que la sonde est bien dans le binaire. Un marqueur qui affichait « (nothing) » n’avait jamais été inséré, parce qu’un
str.replacescripté avait échoué silencieusement. Faites ungrepde la chaîne dans le.bin. - Utilisez les points de surveillance matériels pour les écrivains indésirables.
esp_cpu_set_watchpoint(0, addr, 4, STORE)a montré qu’environ 230 désynchronisations GPU venaient deDG_PcxRead4Bpp, un décodeur de texture dont le tampon de travail chevauchait des paquets actifs. - Méfiez-vous des améliorations soudaines. Quand la carte n’a pas pu être montée, la carte est passée à 9 étapes en flash, et les temps de chargement sont tombés de 693 à 21 vblanks. Cela ressemble à une accélération de 35x, mais cela signifie que la carte est absente. Vérifiez d’abord
microSD mountedettable_size 1152 -> 96 stages.
Exécuter chaque build sans flasher la carte
Cette méthode ne fonctionne que si essayer coûte peu, et après plusieurs heures d’essais et d’erreurs, flasher la carte après chaque modification ne coûtait pas peu : écrire l’image sur la XIAO en USB, attendre le redémarrage, lire le log série, recommencer. Pour exécuter et vérifier chaque build, j’ai donc utilisé velxio-cli, le client en ligne de commande de Velxio. Il prend le même .bin que produit ma chaîne de compilation, l’exécute sur l’ESP32-S3 simulé de Velxio pendant une durée simulée fixe et renvoie la sortie série : je pouvais lire les sondes ci-dessus sans toucher au matériel. La carte ne recevait une nouvelle image que lorsqu’un build le méritait.
# velxio.toml, next to the build: board = "xiao-esp32-s3", firmware = the merged .bin
velxio-cli run --timeout 5000 --timeout-exit-code 0 --serial-log-file serial.log .
L’installation et un premier lancement prennent quelques minutes : voir le démarrage rapide de velxio-cli.
Les bugs

L’aliasing strict a supprimé une rotation
- Symptôme : chaque personnage avait les bras détachés du torse, un genou plié vers l’arrière et les pieds pointant dans des directions différentes. Le monde, lui, allait bien.
- Impasses :
- Un « correctif » de
MulRotMatrixqui a empiré les choses et a été annulé. - Le pas du modèle, prouvé à 88 octets à partir des données de trois manières indépendantes.
- Des coutures obsolètes, mesurées à effet nul.
- Un dump figé de la pose de repos plaçait les 16 articulations à moins d’un millimètre des positions décodées depuis le disque, avec
det = 4096etd2 == wantsur chaque os.
- Un « correctif » de
- Pourquoi ces vérifications sont passées à côté : en pose de repos, chaque rotation est l’identité,
d2 == wantest une tautologie, etdetvérifie le bloc 3x3, qui était correct. - Ce qui l’a démasqué : les positions des articulations dans deux référentiels différents. Le décalage parent-enfant restait identique octet pour octet alors que le parent tournait de 19 degrés.
- Cause racine :
CompMatrixécrivait la translation via(VECTOR*)&tmp.t[0]par-dessus unlong[3]. GCC 14 à-O2a conclu que rien ne lisait ces écritures et a supprimé l’appel. Le désassemblage ne contenait aucune instruction de multiplication. Il calculaitm2->t = m0->t + m1->t. - Correctif : arithmétique en
long longsans punning de type, plus-fno-strict-aliasingpour tout le jeu. Un second cas identique existe danslibdg/display.c:318, donc le flag est la vraie protection. Un audit[rig]vérifie désormais chaque squelette en utilisant des ratios invariants d’échelle par rapport à l’os le plus long : 14 416 articulations auditées, 0 défectueuse.
L’écran blanc : cinq hypothèses fausses, trois causes réelles
- Symptôme : quand un ennemi repérait Snake, un voile blanc couvrait la scène. Le HUD restait visible au travers, et il y avait des flashs de couleur.
- Hypothèses écartées par la mesure :
- Un flash plein écran. La sonde a journalisé 0 ligne.
change camera -1comme erreur. C’est la sentinelle « pas de caméra fixe ici », et la traiter comme une erreur figeait la caméra derrière le joueur.- Une caméra emballée. C’était le
eye_inv.tmal lu ; la position réelle était stable. - Un débordement de la file de dessin. Un correctif de culling a réduit les modèles dessinés de 25 093 à 14 054 et le blanc est resté.
setlen(pack, z_idx >> 8)dansdivide.c.setlencaste enu_char, donc il ne peut pas produire des longueurs comme0x2E000000.
- Cause 1 :
SetDrawStpfaisait((u_long*)p)[1] = 0xE6000000 | stp. Dans psyz, le mot 1 estlen, et la commande appartient àcode[0]. Le lecteur voyait un paquet de plusieurs milliards de mots, le rejetait et reprenait au milieu d’une primitive, décodant les sommets comme des commandes. Cela se déclenchait au combat, parce que les flashs de canon et la fumée sont ce qui active la semi-transparence. psyz avait déjà corrigé la même erreur dans son propresetDrawTPage, mais personne n’avait relu le jumeau côté jeu. Après le correctif : 0 rejet, 0 désynchronisation. - Cause 2 :
DG_MakePrimn’initialisait jamais la longueur. C’est corrigé en un seul endroit en dérivantlen = psize/4 - 2et en vérifiant le résultat contre les macros psyz (FT4 donne 9, GT4 donne 12, TILE donne 3). - Cause 3, la règle matérielle manquante : une fois les primitives texturées incluses, la sonde a montré
[cover] code 3E abe 1 tex 1 box -1024,-1024..142,66, qui est la limite de saturation du GTE. Les polygones traversant l’arrière de la caméra y sont épinglés comme des quads couvrant tout l’écran. Le GPU PSX refuse tout polygone plus grand que 1023x511, et le jeu compte là-dessus. Notre rasteriseur les dessinait : 27,8 M de texels par 120 frames, environ trois écrans par frame, et 142 ms de rastérisation. Le test de taille s’exécute désormais danssoft_raster.inc.cavant le clipping, parce que le clipping réduirait le polygone à la taille de l’écran et masquerait la propriété même testée.
Le correctif de culling de l’hypothèse 4 était réel, même s’il n’était pas la cause. Le test de boîte englobante traitait une boîte qui traverse le plan proche comme une boîte entièrement derrière lui. Séparer les deux cas a fait passer kept-saturated de 16 090 à 4 947. Une tentative antérieure basée sur les coordonnées saturées sauvait 97 % de tout ce que le test d’écran rejetait (+40 % de rastérisation), parce qu’un grand mur lointain sature lui aussi. Demander directement sur Z (SZ <= H/2) donnait 1 440 au lieu de 15 000.
Square0 décalé de 12 bits : chaque distance /64
Snake faisait trois pas, heurtait un mur, rebondissait et ne progressait jamais. Le framerate était le premier suspect. Une observation l’a écarté : le monde bougeait bien et seul le joueur ne bougeait pas. Une sonde dans GM_ActControl a montré un pas de +4481 suivi d’un rebond de -14641.
Dans PSY-Q, le suffixe numérique est le décalage : Square0 ne décale pas et Square12 décale. Le Square0 du port décalait de 12, donc chaque longueur Square0 -> sum -> sqrt sortait /64. Cela cassait :
- Les déplacements et les collisions.
- La portée de vision des ennemis.
- Les balles.
- Le capteur infrarouge.
- L’atténuation de la lumière.
Retirer le décalage a rendu la trajectoire monotone.
Cinq opcodes GTE copiés depuis la mauvaise ligne
Snake était tombé hors du monde (Y = -3250), le déplacement était bloqué à 0,1 par frame, et le dock n’avait pas d’eau. Les Psyz_GteRtv0/Rtv1/Rtv2/Ll/Llv0 de psyz utilisaient des opcodes MVMVA de la mauvaise ligne du propre tableau inline_n.h de MGS. « Tourner ce vecteur » devenait « le tourner et ajouter la translation obsolète », et l’éclairage utilisait la matrice de rotation au lieu de la matrice de lumière.
Après le correctif :
- Un pas de
27,0maintenu. - Y = 250.
- Rotation fluide.
- Pixels texturés par frame passés de 23 500 à 107 877.
- L’eau est revenue aussi, parce qu’elle est conditionnée à la caméra à l’intérieur du volume d’eau.
Le dock vide était un script en deux passes
Le dock n’avait qu’une poignée de groupes d’objets, et le script semblait exécuter une seule commande. La vraie structure de s00a est if (var[5] < 6) { set up the Colonel's call } else { build the dock }, et le proc de l’appel est un restart. Le monde est construit à la seconde passe, et répondre au codec la déclenche.
J’avais moi-même masqué le codec pour éviter un crash, et cela désactivait chaque radio -c ... -p proc dans chaque stage. MENU_RadioDrainHeadless répond désormais à l’appel et dispatche son proc sans ouvrir l’écran codec. Les groupes d’objets sont passés de 480 à 3 240 par 120 frames, et la zone d’eau a été créée. La leçon : un stub temporaire a besoin de quelque chose qui vous force à y revenir.
Division par zéro : MIPS y survit, Xtensa redémarre
libhzd/near.c divise par une longueur 2D au carré qui peut être nulle dans des cas dégénérés. Le R3000 continue avec un résultat indéfini. Xtensa lève IntegerDivideByZero et la carte redémarre. HZD_DIV a été appliqué aux 7 divisions à diviseur calculé à l’exécution. Après cela, 80 s de marche dans les quatre directions, le motif qui plantait auparavant, ont donné 0 panique. Dans ce port, chaque division par un diviseur calculé a besoin d’une garde.
Le gel de 17,6 minutes
Le VSync de psyz tronquait son résultat à 16 bits dans tous les modes, mais VSync(-1) doit renvoyer le compteur de champs sur 32 bits. À 65 536 champs (17,6 minutes à 60 Hz), l’horloge mts passait de 64 800 à 1 064 alors qu’une tâche attendait 65 537, et elle attendait pour toujours. Le correctif renvoie le compteur complet pour mode < 0. Cela affecte tous les projets construits sur psyz. Les bugs qui dépendent du temps écoulé ne se manifestent jamais dans des tests de 60 secondes.
Le boot qui semblait bloqué
Pendant des heures, le boot semblait coincé. Le mts_printf de Konami était un stub vide sur PSX, et mon #define printf mts_printf envoyait toute la sortie du jeu dedans, donc le boot progressait en silence. Une fois que mts_printf a appelé vprintf, le log a montré que le jeu avait atteint memcard_init(). Avant de diagnostiquer un blocage, assurez-vous que la sortie va quelque part.
Un interblocage de priorité qui était un malloc échoué
Le démon de fichiers (tâche 10) n’obtenait jamais de temps CPU, et la trace ressemblait à un interblocage de priorité. Deux vrais correctifs (la sémantique de ChangeThFromISR et l’horloge VSync(-1)) n’ont rien changé. Puis une ligne a tout réglé : [thread] OpenTh: xTaskCreate failed.
J’avais augmenté les piles à 32 Ko, FreeRTOS les prend dans la SRAM interne, et la quatrième tâche ne rentrait pas. OpenTh renvoyait -1, et ChangeTh rejetait ce tid pour toujours. Sur ce SoC, vérifiez toujours la valeur de retour de xTaskCreate, même avec des mégaoctets de PSRAM libre.
Écran noir après l’ajout des données de cinématique
Copier DEMO.DAT, VOX.DAT et ZMOVIE.STR sur la carte a rendu l’écran noir : 720 frames, 0 panique, et zéro primitive envoyée.
Le code de changement de stage attend GM_StreamStatus() == -1. Le flux DEMO.DAT de la cinématique n’avançait jamais, parce que le CD virtuel sert les lectures par secteur mais pas le chemin de streaming continu en ring-buffer. Avant que les fichiers existent, le flux avait été rejeté tôt et tout continuait.
La gestion actuelle :
- Tous les flux d’entrée sont refusés dans
NewStreamControlen exécutant leur callback, avec un watchdog de 600 frames comme filet de sécurité. Cela coûte les cinématiques et les voix, et cela donne un jeu qui se joue. - L’entrée pad enregistrée d’une cinématique démarrait aussitôt et Snake partait tout seul. Cette lecture est désormais ignorée de la même manière que le jeu l’ignore sur START.
- La FMV est refusée aussi, parce que psyz n’a pas de décodeur MDEC.
Bugs plus petits
PSX_Wvalait 256, hérité du code que j’ai réutilisé. MGS rend 320 colonnes, donc un cinquième de l’image était perdu. Auditez chaque constante héritée.- Course au boot : le tick lisait le port série USB avant que le driver soit installé, causant
LoadProhibitedsur 2 boots mesurés sur 6. - Le dropper de frames de Konami : deux acteurs lisaient le flag de saut à des moments différents, donc les buffers étaient échangés sans être dessinés et l’écran scintillait. Les deux flags sont forcés à 0 sous
__psyz. Les scènes lourdes tournent désormais plus lentement au lieu de scintiller. - « Collision cassée » : les poussées de mur mesuraient environ 452 contre un rayon de 450, ce qui est exactement correct. À 8-10 fps, une correction de 450 unités ressemble juste à un saut.
Performances
Le temps de rastérisation est un compteur esp_timer dans le rastériseur, cumulé sur 120 images à la même position.
La première passe s’est faite dans s07a, une petite pièce. Le temps de rastérisation total est passé de 923 000 à 903 900, puis 794 000, puis 741 700 us (de 7,69 à 6,18 ms par image). Les trois étapes :
SOFT_RASTER_IRAMétait vide dans la build MGS, donc les boucles par pixel s’exécutaient depuis la flash. Il devrait êtreIRAM_ATTR. La correction a donné -2%.- PSRAM et flash à 120 MHz ont donné -12%. J’ai d’abord conclu que cette carte ne pouvait pas y arriver. L’erreur « FLASH and PSRAM Mode configuration are not supported » signifie seulement que
CONFIG_IDF_EXPERIMENTAL_FEATURES=yest manquant. VérifiezCONFIG_SPIRAM_SPEED 120dans lesdkconfig.hgénéré. - Le scanout tournait à 62,5 Hz pour un jeu à 30 fps. La moitié des pushes renvoyaient la même image, chacun lisant environ 120 Ko de PSRAM et évincant les textures du rastériseur sur l’autre cœur. Aligner sur le taux du jeu a donné -6,6%.
Le dock (s00a) est bien plus lourd. Un profil y a mesuré 46 400 pixels texturés et 71 680 pixels plats par image : 40,9 ms de rastérisation plus environ 25 ms de logique et de GTE, soit environ 15 fps. Le README donne actuellement environ 15 fps pour le dock avec des ennemis. Le document de statut donne 8 à 15 fps selon la scène, contre une cible de 30.
Un chemin rapide 32 bits pour les remplissages plats n’a gagné que 2%. Le coût est dans les pixels texturés, à environ 207 cycles chacun. Un jeu 2D tourne bien plus vite sur le même rastériseur : une tilemap parcourt les textures en ligne droite, et une seule ligne de cache de 64 octets sert 128 pixels. Dans les triangles pivotés de MGS, U et V changent tous les deux à chaque pixel, et presque chaque pixel est un défaut de cache. Le cache de données est déjà à son maximum de 64 Ko.
L’étape suivante consiste à déplacer les pages de textures chaudes vers la SRAM interne, ce que le document de statut estime 40 fois plus rapide. Cela nécessite les quelque 90 Ko piégés dans des piles mts surdimensionnées (24 Ko pour la grande tâche et 6 Ko pour le reste). Réduire les textures n’est pas une option, car les UV sont intégrés dans les modèles.
Le chargement est lent aussi : environ 11,5 s pour 1,1 Mo depuis la carte (environ 95 Ko/s).
- Une rafale de 128 au lieu de 16 secteurs n’a gagné que 7%.
- La carte est fiable à 20 MHz sur la carte Waveshare. À 40 MHz, elle donne des erreurs CRC.
- Sauter les appels
fseekredondants est en place mais pas encore mesuré.
Mise en route de la console portable

La console portable est construite à partir de :
- Un XIAO ESP32S3 Sense, dont la carte d’extension fournit le slot microSD.
- Un écran SPI ILI9341.
- Un joystick de manette de drone.
- 8 boutons : 6 sur une échelle de résistances sur une broche ADC, plus tir et visée sur leurs propres broches, car une échelle n’enregistre qu’un bouton à la fois.

Les 11 broches du XIAO sont utilisées. Le câblage est documenté dans le guide matériel. Notes de mise en route :
- La masse manquante. L’écran brillait en blanc et changeait de luminosité quand des données étaient envoyées, car il s’alimentait à travers les diodes de protection de ses entrées. Avant cela, les mesures avaient écarté le câblage, l’impulsion de reset, la tension d’alimentation et la configuration SPI. Un bug de ma part a aussi coûté deux tours : une édition scriptée censée insérer
lcd_bus_init()a échoué silencieusement, et l’écran a été re-soudé pour rien. - ILI9341, pas ILI9488. Le plan supposait un ILI9488 480x320, qui en SPI n’accepte que du RGB666 sur 3 octets. Un projet antérieur du même type avec le même écran a montré qu’il s’agit d’un ILI9341 en 320x240. C’était mieux que prévu : résolution native, pas de mise à l’échelle, 2 octets par pixel. L’ordre des couleurs a été vérifié avec trois bandes R/V/B étiquetées en même temps.
- RST sur une vraie broche. Avec RESET relié au 3V3 et seulement un reset logiciel, l’ILI9341 ne démarrait pas de manière fiable, donc RST a été déplacé vers D4. D4 était libre car le CS de la carte est GPIO21, interne à la carte Sense. Une recherche web avait donné de mauvaises broches SD. L’erreur était
ESP_ERR_INVALID_ARG, une erreur de configuration plutôt qu’une erreur de carte, ce qui a orienté vers la documentation officielle de Seeed. - Boutons et potentiomètres. Câblez les interrupteurs à 4 pattes sur les pattes diagonales, sinon un bouton se lit comme enfoncé en permanence. Pour les potentiomètres :
- Une lecture bloquée à 0 ou 4095 signifie que le fil est sur une patte extérieure.
- Une lecture bloquée à mi-échelle signifie que le potentiomètre n’a pas de 3V3/GND.
- Une plage étendue signifie que l’axe est sain.
- Calibration du stick. Le joystick repose à 2317, pas à 2048, et X va de 141 à 2888.
- Le centre est la lecture au repos au démarrage, et chaque moitié est mise à l’échelle par la course observée dans cette direction.
- La zone morte est de 60 comptes (environ 4x le bruit mesuré de +/-15), soustraite des deux côtés pour que le mouvement démarre en douceur.
- Chaque axe moyenne 8 lectures, et les deux axes sont inversés en logiciel.
- Un min/max accumulé depuis le démarrage est inutile ici, car une entrée flottante touche 0 et 4095 à la mise sous tension. Utilisez une fenêtre glissante.
- Les lectures ADC dans le tick vblank ont tout figé. 24 conversions par tick bloquaient le tick et toutes les tâches mts. L’avertissement était déjà écrit dans
esp_input.c. Une tâche sur le cœur 1 échantillonne maintenant toutes les 10 ms et publie trois entiers. printfsur USB natif bloque quand aucun hôte ne le draine (l’UART non). MGS imprime beaucoup, donc une impression bloquée arrêtait l’ordonnanceur coopératif.port/mgs_printf.hécrit avec un timeout nul.- Paires d’horloges. La PSRAM à 120 MHz avec la flash à 80 MHz n’est pas une paire MSPI supportée, et la défaillance ressemble à un bug de toolchain. Le XIAO tourne en 80/80 pour l’instant, et 120/120 est la prochaine chose à mesurer.
- SPI de l’écran. Avec des fils de liaison, l’écran est stable à 40 MHz. À 80 MHz, des bandes de l’image glissent latéralement.
MGS démarre maintenant sur la console portable, monte la carte, charge le dock et se joue sans paniques, à un taux d’images que le README décrit comme similaire à la carte Waveshare.
Ce qui ne fonctionne pas encore
- Les appels codec. Le groupe de visages de 417 792 octets se charge maintenant depuis une réserve PSRAM statique, car le pool du jeu refuse l’allocation. L’index de
RADIO.DATest toujours faux : le secteur de départ calculé est 31 392, et le fichier a 867 secteurs. La valeur d’entrée est mauvaise ; l’arithmétique est correcte. Activer le vrai écran codec provoque aussi une panique dans unprintf. - L’intro. Démarrer en passant par l’écran titre a donné 11 paniques. La dernière ligne avant la première était
this memcard is OK. La nage d’introduction et le briefing nécessitent la carte mémoire, le streaming CD et le codec. - L’ascenseur. Les sondes dans les deux constructeurs d’ascenseur restent silencieuses pendant toute une session, donc le script de scène ne le demande jamais. La raison probable, non encore prouvée, est une variable d’histoire qu’un appel codec fait avancer.
- Le streaming CD (cinématiques, voix), FMV (pas de MDEC), l’audio, et les sauvegardes sur carte mémoire.
- 28 scènes dont le code des acteurs est encore de l’assembleur MIPS.
- Les performances au-delà d’environ 15 fps.
Prochaines étapes
- Redimensionner correctement les piles mts et déplacer les pages de textures chaudes vers la SRAM interne.
- Mesurer les horloges mémoire 120/120 MHz sur le XIAO.
- Corriger l’index de
RADIO.DAT, puis vérifier si l’ascenseur suit. - Implémenter le streaming dans le CD virtuel, pour retrouver les cinématiques et les voix.
- Ajouter l’audio via un SPU logiciel.
- Retirer les sondes de débogage.
Conclusion
Une PlayStation tolère le type punning, la division par zéro, les lectures au-delà des tableaux et les pointeurs testés par signe. Un compilateur et un CPU modernes n’en tolèrent aucun. L’approche qui a fonctionné sur ce portage a été de concevoir chaque mesure de façon à ce qu’elle puisse échouer.