Indietro

Metal Gear Solid in esecuzione nativamente sull'ESP32-S3

L'handheld XIAO ESP32S3 che esegue Metal Gear Solid sulla dock, con il radar nell'angolo in alto a destra

Amo Metal Gear Solid da quando ero bambino. Quando ho ricevuto una minuscola scheda ESP32-S3, una domanda mi è rimasta in testa: potrebbe un gioco PlayStation girare su qualcosa di così piccolo?

Il Seeed Studio XIAO ESP32S3 Sense: 21 × 17,8 × 15 mm con la sua scheda camera collegata (foto: Seeed Studio)

La scheda è il Seeed Studio XIAO ESP32S3 Sense: un ESP32-S3 dual-core con 8 MB di PSRAM e 8 MB di flash, su un modulo di 21 × 17,8 mm. La versione Sense aggiunge una scheda di espansione con una camera e uno slot microSD, e quello slot microSD è dove risiedono i dati del gioco.

Ci ho messo un bel po’ a scoprirlo. Prima ho cercato una versione del gioco che fosse già stata ricostruita come codice C eseguibile su PC, poi ho verificato se tutta quella logica potesse stare nella flash dell’ESP32-S3 e su una scheda microSD. Ci sono voluti diversi tentativi, ma alla fine ha funzionato. Un gioco meraviglioso ora gira su una scheda microcontroller che costa circa 15 USD.

Gameplay sull’handheld: guardalo su YouTube.

In questo articolo descrivo come Metal Gear Solid (PlayStation, 1998) gira sull’ESP32-S3 come port nativo. Il codice sorgente C del gioco, ricostruito dalla decompilazione mgs_reversing del FoxdieTeam, viene compilato direttamente in codice macchina Xtensa. Tutto ciò che l’hardware PlayStation forniva viene sostituito con software:

L’articolo copre l’hardware, il livello di piattaforma, il posizionamento della memoria, il metodo di debugging, i bug più significativi, le prestazioni, l’handheld e ciò che ancora non funziona.

Il codice e i progetti correlati:

Ti serve il tuo disco. Il repository non contiene nulla derivato dal gioco, e port/extract_disc.py estrae i file dalla tua immagine del disco.

Hardware

Giocare a Metal Gear Solid sull'handheld sulla dock

L’ESP32-S3 ha due core Xtensa a 240 MHz e 512 KB di SRAM interna. Entrambe le schede usate qui hanno anche 8 MB di PSRAM, che si trova dietro la stessa cache della flash.

Waveshare ESP32-S3-Touch-LCD-2Handheld fai-da-te (Seeed XIAO ESP32S3 Sense)
PannelloST7789, 320x240ILI9341, 320x240 nativo
Flash16 MB8 MB
Dati di giocomicroSD, o un STAGE.DIR ridotto nella flashmicroSD (STAGE.DIR completo)
Inputtastiera via seriale (play.py)stick di gimbal per droni, scala di resistori a 6 pulsanti, 2 pulsanti diretti

Misurare il divario prima di scrivere codice

Prima di scrivere qualsiasi codice di port, ho misurato quanto la decompilazione fosse lontana dal compilare per Xtensa:

Ho lasciato l’unico file che falliva, libdg/chanl.c, fallire di proposito. Il cast che l’avrebbe silenziato avrebbe anche cambiato silenziosamente lo stride (vedi la sezione sulla ordering table più sotto).

Il resto ha richiesto passaggi meccanici, ognuno dei quali risolveva un’intera classe di problemi:

Il risultato è stato 497 file C su 497 compilati per Xtensa. L’ELF aveva 0 riferimenti non definiti e 0 definizioni duplicate (text 987.073 B, bss 2.434.276 B). La memoria del gioco stesso è di 804 KiB (428 KiB di heap più due buffer di pacchetti da 188 KiB), che entra comodamente nella PSRAM.

--- END POST ---

Architettura

Il porting ha tre livelli tra il gioco e il SoC:

I tre livelli del porting e i due core — tutti i task mts e il tick di vblank sul core 0, la scansione dell'LCD sul core 1, e l'LCD e la microSD che condividono SPI2

I livelli, dal gioco fino all’hardware:

  1. Motore di MGS: C decompilato, compilato per Xtensa
  2. psyz: SDK PlayStation e GTE in C, rasterizzatore software
  3. Livello di piattaforma: scheduler mts su FreeRTOS, tick di vblank, CD virtuale, LCD, input
  4. ESP32-S3

psyz e il GTE

psyz, la reimplementazione dell’SDK PlayStation di Xeeynamo, modellava già l’intero file di registri del GTE e ogni operazione del GTE in C, validata contro la suite di test del GTE di PCSX-Redux.

La mia prima stima era che mancassero dalle 64 alle 70 macro. Quella stima era troppo alta. MGS include i propri header MIPS con asm inline (inline_n.h, inline_x.h), e -fsyntax-only non controlla i nomi dei registri. Una volta che quegli header sono stati dirottati verso psyz, la lacuna reale era di 41 macro. Le ho aggiunte a psyz, usando l’assembly del gioco stesso come specifica per stabilire quali registri COP2 tocca ciascuna. Poi ho ricompilato gli altri miei progetti basati su psyz contro il psyz modificato per assicurarmi che nulla si rompesse.

Quando si crea un alias di una macro GTE, bisogna controllare se ogni vincolo è un input o un output. Per esempio, gte_read_opz ha un output "=r", quindi il suo alias deve prendere &x.

Il tag della tabella di ordinamento — una parola su PSX, due in psyz

Questa è la differenza di layout più importante, ed è quella che ha causato più bug. Sulla PlayStation, ogni primitiva inizia con un tag da 32 bit — 24 bit di indirizzo della primitiva successiva e 8 bit di lunghezza. Un puntatore host non entra in 24 bit, quindi psyz usa due parole, tag e len. Ogni primitiva cresce di 4 byte, e ogni campo dopo il tag si sposta di una parola.

MGS inoltre abusa del byte di lunghezza. libdg esegue un radix sort a due passate su profondità a 16 bit:

  1. divide.c suddivide in bucket per il byte basso e parcheggia il byte alto nella lunghezza del tag.
  2. sort.c ri-suddivide in bucket per quel byte alto e scrive la lunghezza reale.

Poiché psyz separa i due campi, la traduzione è esatta:

pack->tag = (hi << 24) | *ot;  *ot = pack;     /* PSX */
addPrim(ot, pack); setlen(pack, hi);           /* psyz */

Riscrivere 42 dichiarazioni locali e 100 parametri come OT_TYPE* è stata la parte facile. La parte difficile è stato il codice che presupponeva il layout impacchettato senza dichiararlo:

C’è anche un fattore aggravante. Sulla console, addPrim() riscriveva l’intera parola del tag a ogni inserimento, quindi una lunghezza dimenticata non poteva mai passare inosservata. In psyz, una lunghezza che non è mai stata impostata semplicemente non viene mai scritta.

Lo scheduler di Konami dentro FreeRTOS

MGS gira sullo scheduler cooperativo di Konami. Il banner di avvio recita ancora Multi Task Scheduler for PSX ver2.02 Jul 11 1998. Si appoggia all’API dei thread del BIOS (OpenTh/ChangeTh) e usa l’interrupt di vblank per risvegliare i task i cui timer sono scaduti.

Nel porting, ogni thread mts è un task FreeRTOS, e solo uno di essi è eseguibile alla volta. Il design finale:

mts_GetTcbEntry inoltre leggeva la tabella delle tabelle del BIOS all’indirizzo fisso 0x100 e scriveva attraverso il risultato. Fuori da un PSX quell’indirizzo contiene spazzatura, quindi ora usa una tabella TCB privata.

Il tick di vblank e i due orologi

port/esp32_vblank.c attiva il callback VSync del gioco ogni 16 ms. Questo ha richiesto che VSyncCallback() fosse implementata in psyz, dove non memorizzava nemmeno il puntatore.

VSync(-1) deve restituire un conteggio di vblank a corsa libera. La prima versione restituiva il numero di frame presentati, che smette di avanzare quando nulla disegna, quindi nessun timer scadeva mai.

Il frame rate varia — 2 vblank per frame in un corridoio, da 4 a 5 in una stanza aperta. Per questo motivo, due cose che sembravano di competenza del vblank appartengono in realtà al frame di gioco:

Posizionamento della memoria

Dove vive tutto — stack dei task e loop caldi in SRAM interna, la mappa RAM del gioco e 1 MB di VRAM in PSRAM, il firmware in flash, e STAGE.DIR sulla microSD

La SRAM interna è scarsa e veloce. La PSRAM è abbondante e lenta. Le letture dalla flash disabilitano la cache da cui dipende anche la PSRAM.

Una classe di bug esiste solo su questa mappa di memoria — test dei puntatori basati sul bit di segno. MGS distingue un puntatore a blocco di script da un proc id a 16 bit con proc_id < 0. La RAM del PSX è a 0x8xxxxxxx, che è negativo come valore con segno. La PSRAM è a 0x3Cxxxxxx, che è positivo. Il risultato era PROC 3C1987D2 NOT FOUND, seguito da un LoadProhibited a EXCVADDR 0x00000003. Una macro GCL_IS_BLOCK_PTR corregge il sito che è stato colpito. Altri siti con lo stesso pattern necessitano ancora di un audit.

Un CD virtuale su FAT

Il CD virtuale — libfs chiede un settore assoluto, virtual_cd.c lo trasforma in un file e un offset sulla microSD e restituisce un settore alla volta

libfs lavora in settori assoluti. Legge la directory ISO9660 una volta e non usa mai più un nome di file. port/virtual_cd.c sostituisce il BIOS del CD:

I dati inizialmente vivevano in PSRAM, il che limitava il gioco a una manciata di stage. La vera soluzione è stata la microSD. La scheda è una periferica SPI, separata dalla flash XIP, quindi leggerla non disabilita la cache delle istruzioni. I file restano sulla scheda e non costano PSRAM.

La scheda e l’LCD condividono SPI2, e ESP-IDF non arbitra tra loro. Un frame dell’LCD è composto da 30 trasferimenti asincroni in coda, quindi una lettura dalla scheda nel mezzo di un frame faceva scattare assert failed: spi_hal_iram.c:134 e causava un loop di riavvio. La soluzione è la proprietà esplicita del bus (Mgs_SpiBusTake/Give), svuotando i trasferimenti in corso prima di rilasciare il bus.

Metodo: misurare, non indovinare

Circa un terzo delle spiegazioni ovvie in questo progetto si sono rivelate sbagliate. Ciò che ha funzionato è stato far stampare alla scheda un numero che decidesse tra le ipotesi. Le lezioni più utili sono venute da sonde che hanno dato risposte sbagliate:

Eseguire ogni build senza flashare la scheda

Quel metodo funziona solo se provare qualcosa costa poco, e dopo diverse ore di tentativi, flashare la scheda dopo ogni modifica non costava poco: scrivere l’immagine sulla XIAO via USB, aspettare il riavvio, leggere il log seriale, ricominciare. Per eseguire e verificare ogni build ho quindi usato velxio-cli, il client a riga di comando di Velxio. Prende lo stesso .bin prodotto dalla mia toolchain, lo esegue sull’ESP32-S3 simulato di Velxio per un tempo simulato fisso e restituisce l’output seriale, così potevo leggere le sonde qui sopra senza toccare l’hardware. La scheda riceveva una nuova immagine solo quando una build se lo meritava.

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

Installarlo e fare una prima esecuzione richiede pochi minuti: vedi la guida rapida di velxio-cli.

I bug

In gioco sulla console portatile, con il radar nell'angolo in alto a destra

Lo strict aliasing ha eliminato una rotazione

Lo schermo bianco: cinque ipotesi sbagliate, tre cause reali

La regola di dimensione della GPU: un poligono bloccato al limite di saturazione -1024 del GTE si estende nello schermo 320x240; la GPU PlayStation rifiuta qualsiasi cosa più grande di 1023x511, il rasterizzatore software lo disegnava

La correzione del culling dell’ipotesi 4 era reale, anche se non era la causa. Il test del bounding-box trattava un box che attraversa il piano vicino allo stesso modo di uno interamente dietro di esso. Separare i due casi ha portato kept-saturated da 16.090 a 4.947. Un tentativo precedente basato su coordinate sature recuperava il 97% di tutto ciò che il test dello schermo rifiutava (+40% di rasterizzazione), perché anche un muro grande e distante satura. Chiedere direttamente dello Z (SZ <= H/2) dava 1.440 invece di 15.000.

Square0 spostato di 12 bit: ogni distanza /64

Snake faceva tre passi, urtava un muro, rimbalzava indietro e non progrediva mai. Il frame rate fu il primo sospetto. Un’osservazione lo escluse: il mondo si muoveva bene e solo il giocatore no. Una sonda in GM_ActControl mostrava un passo di +4481 seguito da un rimbalzo di -14641.

In PSY-Q il suffisso numerico è lo shift: Square0 non sposta e Square12 sì. Il Square0 del port spostava di 12, quindi ogni lunghezza Square0 -> sum -> sqrt usciva /64. Questo rompeva:

Rimuovere lo shift ha reso la traiettoria monotona.

Cinque opcode GTE copiati dalla riga sbagliata

Snake era caduto fuori dal mondo (Y = -3250), il movimento era bloccato a 0,1 per frame, e il molo non aveva acqua. Psyz_GteRtv0/Rtv1/Rtv2/Ll/Llv0 di psyz usavano opcode MVMVA dalla riga sbagliata della tabella inline_n.h di MGS stesso. “Ruota questo vettore” diventava “ruotalo e aggiungi la traslazione obsoleta”, e l’illuminazione usava la matrice di rotazione invece della matrice della luce.

Dopo la correzione:

Il molo vuoto era uno script a due passaggi

Il molo aveva solo una manciata di gruppi di oggetti, e lo script sembrava eseguire un solo comando. La vera struttura di s00a è if (var[5] < 6) { set up the Colonel's call } else { build the dock }, e il proc della chiamata è un restart. Il mondo viene costruito al secondo passaggio, e rispondere al codec lo attiva.

Avevo mascherato io stesso il codec per evitare un crash, e questo disabilitava ogni radio -c ... -p proc in ogni stage. MENU_RadioDrainHeadless ora risponde alla chiamata e smista il suo proc senza aprire la schermata del codec. I gruppi di oggetti sono passati da 480 a 3.240 ogni 120 frame, e l’area dell’acqua è stata creata. La lezione: uno stub temporaneo ha bisogno di qualcosa che ti costringa a ritornarci.

Divisione per zero: MIPS sopravvive, Xtensa si riavvia

libhzd/near.c divide per una lunghezza 2D al quadrato che può essere zero in casi degeneri. L’R3000 continua con un risultato indefinito. Xtensa solleva IntegerDivideByZero e la scheda si resetta. HZD_DIV è stato applicato alle 7 divisioni con divisore a runtime. Dopo di che, 80 s di camminata in tutte e quattro le direzioni, il pattern che prima andava in crash, ha dato 0 panic. In questo port, ogni divisione per un divisore calcolato ha bisogno di una guardia.

Il blocco di 17,6 minuti

VSync di psyz troncava il suo risultato a 16 bit in ogni modalità, ma VSync(-1) deve restituire il conteggio dei field a 32 bit. A 65.536 field (17,6 minuti a 60 Hz), l’orologio mts andava da 64.800 a 1.064 mentre un task aspettava 65.537, e aspettava per sempre. La correzione restituisce il conteggio completo per mode < 0. Colpisce ogni progetto costruito su psyz. I bug che dipendono dal tempo trascorso non si manifestano mai in test da 60 secondi.

L’avvio che sembrava bloccato

Per ore l’avvio sembrava bloccato. mts_printf di Konami era uno stub vuoto sulla PSX, e il mio #define printf mts_printf mandava tutto l’output del gioco lì dentro, quindi l’avvio procedeva in silenzio. Una volta che mts_printf ha chiamato vprintf, il log ha mostrato che il gioco aveva raggiunto memcard_init(). Prima di diagnosticare un blocco, assicurati che l’output vada da qualche parte.

Un deadlock di priorità che era un malloc fallito

Il daemon dei file (task 10) non otteneva mai tempo CPU, e la traccia sembrava un deadlock di priorità. Due correzioni reali (la semantica di ChangeThFromISR e l’orologio di VSync(-1)) non cambiarono nulla. Poi una riga ha risolto tutto: [thread] OpenTh: xTaskCreate failed.

Avevo alzato gli stack a 32 KB, FreeRTOS li prende dalla SRAM interna, e il quarto task non ci stava. OpenTh restituiva -1, e ChangeTh rifiutava quel tid per sempre. Su questo SoC, controlla sempre il valore di ritorno di xTaskCreate, anche con megabyte di PSRAM libera.

Schermo nero dopo aver aggiunto i dati delle cutscene

Copiare DEMO.DAT, VOX.DAT e ZMOVIE.STR sulla scheda ha reso lo schermo nero: 720 frame, 0 panic, e zero primitivi inviati.

Il codice di cambio stage aspetta GM_StreamStatus() == -1. Lo stream di DEMO.DAT della cutscene non avanzava mai, perché il CD virtuale serve le letture a settori ma non il percorso di streaming continuo a ring-buffer. Prima che i file esistessero, lo stream veniva rifiutato subito e tutto continuava.

La gestione attuale:

Bug minori

Prestazioni

Il tempo di rasterizzazione è un contatore esp_timer nel rasterizzatore, sommato su 120 frame nella stessa posizione.

La prima passata è stata in s07a, una piccola stanza. Il tempo di rasterizzazione totale è passato da 923.000 a 903.900, poi 794.000, poi 741.700 us (da 7,69 a 6,18 ms per frame). I tre passaggi:

  1. SOFT_RASTER_IRAM era vuoto nella build di MGS, quindi i cicli per pixel venivano eseguiti dalla flash. Dovrebbe essere IRAM_ATTR. La correzione ha dato -2%.
  2. PSRAM e flash a 120 MHz hanno dato -12%. All’inizio ho concluso che questa scheda non poteva farcela. L’errore “FLASH and PSRAM Mode configuration are not supported” significa solo che manca CONFIG_IDF_EXPERIMENTAL_FEATURES=y. Controlla CONFIG_SPIRAM_SPEED 120 nel file sdkconfig.h generato.
  3. Lo scanout girava a 62,5 Hz per un gioco a 30 fps. Metà delle push reinviavano la stessa immagine, ognuna leggendo circa 120 KB di PSRAM e scacciando le texture del rasterizzatore sull’altro core. Allinearsi alla frequenza del gioco ha dato -6,6%.

Tempo per frame: la rasterizzazione in s07a scende da 7,69 a 6,18 ms in tre passaggi, e un frame del dock di 40,9 ms di rasterizzazione più circa 25 ms di logica, circa 15 fps contro un obiettivo di 33,3 ms

Il dock (s00a) è molto più pesante. Un profilo lì ha misurato 46.400 pixel texturizzati e 71.680 piatti per frame: 40,9 ms di rasterizzazione più circa 25 ms di logica e GTE, che corrisponde a circa 15 fps. Il README attualmente indica circa 15 fps per il dock con i nemici. Il documento di stato indica da 8 a 15 fps a seconda della scena, contro un obiettivo di 30.

Un percorso veloce a 32 bit per i riempimenti piatti ha guadagnato solo il 2%. Il costo è nei pixel texturizzati, a circa 207 cicli ciascuno. Un gioco 2D gira molto più veloce sullo stesso rasterizzatore: una tilemap percorre le texture in linea retta, e una singola cache line da 64 byte serve 128 pixel. Nei triangoli ruotati di MGS, U e V cambiano entrambi per pixel, e quasi ogni pixel è un cache miss. La cache dati è già al suo massimo di 64 KB.

Il prossimo passo è spostare le pagine di texture più usate nella SRAM interna, che il documento di stato stima essere 40 volte più veloce. Serve recuperare i circa 90 KB intrappolati in stack mts sovradimensionati (24 KB per il task grande e 6 KB per il resto). Ridurre le texture non è un’opzione, perché le UV sono incorporate nei modelli.

Il caricamento è anch’esso lento: circa 11,5 s per 1,1 MB dalla scheda (all’incirca 95 KB/s).

Mettere in funzione l’handheld

Cablaggio dell'handheld: lo XIAO ESP32S3 Sense, il pannello ILI9341, lo stick analogico su D0/D1, una scala di resistori a sei pulsanti su D2 e due pulsanti diretti su D5/D7

L'handheld assemblato su perfboard: lo stick analogico a sinistra, i resistori della scala dei pulsanti al centro e lo XIAO in basso

L’handheld è costruito con:

Cosa c'è nella confezione dello XIAO ESP32S3 Sense: la scheda con la sua fotocamera, un'antenna Wi-Fi, pin header e dissipatori (foto: Seeed Studio)

Tutti gli 11 pin dello XIAO sono utilizzati. Il cablaggio è documentato nella guida hardware. Note di bring-up:

MGS ora si avvia sull’handheld, monta la scheda, carica il dock e gioca senza panic, a un frame rate che il README descrive come simile alla scheda Waveshare.

Cosa non funziona ancora

Prossimi passi

  1. Ridimensionare correttamente gli stack mts e spostare le pagine di texture più usate nella SRAM interna.
  2. Misurare i clock di memoria 120/120 MHz sullo XIAO.
  3. Correggere l’indice di RADIO.DAT, poi verificare se l’ascensore ne consegue.
  4. Implementare lo streaming nel CD virtuale, per recuperare cutscene e voci.
  5. Aggiungere l’audio tramite una SPU software.
  6. Rimuovere le sonde di debug.

Conclusione

Una PlayStation tollera il type punning, la divisione per zero, le letture oltre gli array e i puntatori testati per il segno. Un compilatore e una CPU moderni non ne tollerano nessuno. L’approccio che ha funzionato su questo porting è stato progettare ogni misurazione in modo che possa fallire.


Condividi su:
David Montero

Scritto da

David Montero

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

GitHub velxio.dev

Articoli correlati


Articolo precedente
Castlevania: Symphony of the Night in esecuzione nativa sull'ESP32-S3
Articolo successivo
222 moduli Seeed Grove ora funzionano nel browser