Retour

Metal Gear Solid tourne nativement sur l'ESP32-S3

La console portable XIAO ESP32S3 faisant tourner Metal Gear Solid sur son dock, avec le radar dans le coin supérieur droit

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 ?

Le Seeed Studio XIAO ESP32S3 Sense : 21 × 17,8 × 15 mm avec sa carte caméra attachée (photo : Seeed Studio)

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 :

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 :

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

Jouer à Metal Gear Solid sur la console portable au dock

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-2Console portable DIY (Seeed XIAO ESP32S3 Sense)
ÉcranST7789, 320x240ILI9341, 320x240 natif
Flash16 Mo8 Mo
Données du jeumicroSD, ou un STAGE.DIR tronqué en flashmicroSD (STAGE.DIR complet)
Entréeclavier 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 :

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 :

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 trois couches du portage et les deux cœurs — toutes les tâches mts et le tick vblank sur le cœur 0, le scanout LCD sur le cœur 1, et le LCD et la microSD partageant SPI2

Les couches, du jeu jusqu’au matériel :

  1. Moteur MGS — C décompilé, compilé pour Xtensa
  2. psyz — SDK PlayStation et GTE en C, rasterizer logiciel
  3. Couche de plateforme — ordonnanceur mts sur FreeRTOS, tick vblank, CD virtuel, LCD, entrées
  4. 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 :

  1. divide.c répartit selon l’octet bas et range l’octet haut dans la longueur du tag.
  2. sort.c ré-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 :

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 :

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 :

Placement mémoire

Où tout réside — piles de tâches et boucles chaudes en SRAM interne, la carte RAM du jeu et le 1 Mo de VRAM en PSRAM, le firmware en flash, et STAGE.DIR sur la microSD

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.

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

Le CD virtuel — libfs demande un secteur absolu, virtual_cd.c le transforme en un fichier et un offset sur la microSD et renvoie un secteur à la fois

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 :

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.

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 :

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

En jeu sur la console portable, avec le radar dans le coin supérieur droit

L’aliasing strict a supprimé une rotation

L’écran blanc : cinq hypothèses fausses, trois causes réelles

La règle de taille du GPU : un polygone épinglé à la limite de saturation -1024 du GTE s'étend dans l'écran 320x240 ; le GPU PlayStation refuse tout ce qui dépasse 1023x511, le rasteriseur logiciel le dessinait

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 :

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 :

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 :

Bugs plus petits

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 :

  1. SOFT_RASTER_IRAM était vide dans la build MGS, donc les boucles par pixel s’exécutaient depuis la flash. Il devrait être IRAM_ATTR. La correction a donné -2%.
  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=y est manquant. Vérifiez CONFIG_SPIRAM_SPEED 120 dans le sdkconfig.h généré.
  3. 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%.

Temps par image : la rastérisation dans s07a passant de 7,69 à 6,18 ms en trois étapes, et une image du dock à 40,9 ms de rastérisation plus environ 25 ms de logique, soit environ 15 fps contre une cible de 33,3 ms

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

Mise en route de la console portable

Câblage de la console portable : le XIAO ESP32S3 Sense, l'écran ILI9341, le stick analogique sur D0/D1, une échelle de résistances à six boutons sur D2 et deux boutons directs sur D5/D7

La console portable assemblée sur plaque à pastilles : le stick analogique à gauche, les résistances de l'échelle de boutons au milieu et le XIAO en bas

La console portable est construite à partir de :

Ce qui est fourni dans la boîte du XIAO ESP32S3 Sense : la carte avec sa caméra, une antenne Wi-Fi, des broches et des dissipateurs thermiques (photo : Seeed Studio)

Les 11 broches du XIAO sont utilisées. Le câblage est documenté dans le guide matériel. Notes de mise en route :

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

Prochaines étapes

  1. Redimensionner correctement les piles mts et déplacer les pages de textures chaudes vers la SRAM interne.
  2. Mesurer les horloges mémoire 120/120 MHz sur le XIAO.
  3. Corriger l’index de RADIO.DAT, puis vérifier si l’ascenseur suit.
  4. Implémenter le streaming dans le CD virtuel, pour retrouver les cinématiques et les voix.
  5. Ajouter l’audio via un SPU logiciel.
  6. 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.


Partager sur :
David Montero

Écrit par

David Montero

Creator of Velxio, the open-source circuit and Arduino simulator.

GitHub velxio.dev

Articles liés


Article précédent
Castlevania: Symphony of the Night tourne nativement sur l'ESP32-S3
Article suivant
222 modules Seeed Grove s'exécutent désormais dans le navigateur