
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?

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’SDK.
- La GPU.
- Il coprocessore geometrico GTE.
- Il lettore CD.
- L’interrupt di vertical blank.
- Il controller.
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:
- Port di MGS: davidmonterocrespo24/mgs_reversing, branch
esp32-port. - Guida hardware dell’handheld: HARDWARE.md.
- Fork di psyz: davidmonterocrespo24/psyz.
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

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-2 | Handheld fai-da-te (Seeed XIAO ESP32S3 Sense) | |
|---|---|---|
| Pannello | ST7789, 320x240 | ILI9341, 320x240 nativo |
| Flash | 16 MB | 8 MB |
| Dati di gioco | microSD, o un STAGE.DIR ridotto nella flash | microSD (STAGE.DIR completo) |
| Input | tastiera 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:
- Le librerie del motore (libgv, libdg, libgcl, libhzd, libfs) si sono compilate quasi subito con
xtensa-esp32s3-elf-gcc14.2 contro gli header di psyz: 57 file su 58. - Nessuna di esse contiene indirizzi assoluti
0x800xxxxx. - Tutto l’output grafico passa attraverso 11 chiamate libgpu (
DrawOTag,LoadImage,ClearOTagRe così via). È esattamente il livello che il renderer software di psyz sostituisce.
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:
-std=gnu17e-mlongcallssono entrambi obbligatori. Il gnu23 predefinito di GCC 14 rifiuta questo codice, ecall8di Xtensa raggiunge solo +/-512 KB.- psyz e MGS hanno entrambi un
common.h, quindi i percorsi di include di MGS devono venire per primi. - 12 espressioni cast-as-lvalue, un’estensione di GCC 2.x, sono state riscritte.
- MGS sostituisce il
printfdi libc con il proprio stub. L’ho rinominatomts_printf, e questo in seguito ha causato uno dei bug più fuorvianti (vedi “Il boot che sembrava bloccato”). - 346 indirizzi letterali della scratchpad (
0x1f8000xx) in 16 file sono diventatiSCRPAD_ADDR + offset, supportati da un array.
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 livelli, dal gioco fino all’hardware:
- Motore di MGS: C decompilato, compilato per Xtensa
- psyz: SDK PlayStation e GTE in C, rasterizzatore software
- Livello di piattaforma: scheduler mts su FreeRTOS, tick di vblank, CD virtuale, LCD, input
- 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:
divide.csuddivide in bucket per il byte basso e parcheggia il byte alto nella lunghezza del tag.sort.cri-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:
DG_PrimInfosmetteva il primo vertice a +8 invece che a +12.LinkModelToParentprecalcolava gli offset dei vertici genitori come*52 + 8invece che*56 + 12.- I costruttori di primitive descritti in “Lo schermo bianco” qui sotto.
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:
- Tutti i task mts sono fissati al core 0, insieme al tick di vblank a priorità 10, così il tick pre-empta il gioco come faceva l’interrupt del PSX. La scansione dell’LCD gira sul core 1. Incrociare queste assegnazioni causava race che riattivavano task parcheggiati a metà stack. Un log mostrava due copie di
Main()interlacciate riga per riga. - Un nuovo task si sospende da solo nel proprio trampolino.
xTaskCreateseguito davTaskSuspendnon è atomico, e su due core il task girava prima che il suo blocco di controllo fosse riempito. - Le sezioni critiche sono reali. Ogni task ha un flag assoluto, salvato e ripristinato a ogni switch come il registro di stato MIPS. È un flag invece che un contatore perché il gioco chiama
ExitCriticalSectionsenza unEntercorrispondente. - Il tick esegue il callback mts solo mentre il task idle (11) è attivo. Quel task è il loop della console SIO di Konami, l’unico codice che non tocca mai lo stato dello scheduler. Sulla console girava con gli interrupt abilitati esattamente per questo motivo. Il gioco passa attraverso l’idle a ogni frame, quindi la latenza di risveglio resta sotto un frame. Questa modifica ha eliminato i blocchi intermittenti alla fonte, dove le versioni precedenti basate su flag avevano solo ridotto la finestra della race.
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:
- Le pressioni prolungate dei tasti seriali vengono decrementate in
DG_ActFirst, subito dopoGV_UpdatePadSystem, l’unico punto che significa “un frame ha letto il pad”. Contare i vblank lì faceva o camminare Snake troppo lontano o rilasciare i tasti prima che il gioco li vedesse. - L’LCD invia un frame solo quando un numero di sequenza incrementato in
DG_SwapFrameè cambiato, con un fallback di 250 ms.
Posizionamento della memoria
La SRAM interna è scarsa e veloce. La PSRAM è abbondante e lenta. Le letture dalla flash disabilitano la cache da cui dipende anche la PSRAM.
- La mappa RAM del gioco pende da un unico define,
MEM_BOTTOM. Entrambe le arene di pacchetti, l’heap e il buffer di settore di libfs derivano da esso per sottrazione. È stata ricollocata su un array statico in PSRAM (mgs_main_ram[0xC9000],EXT_RAM_BSS_ATTR). Deve essere statico perchéRESIDENT_BOTTOMè usato come inizializzatore statico, il che escludemalloc. - 1 MB di VRAM del PSX vive in PSRAM. Senza
EXT_RAM_BSS_ATTR, dram0 va in overflow di circa 900 KB. - Gli stack dei task sono andati avanti e indietro.
- Stack da 32 KB dalla SRAM interna facevano fallire silenziosamente la quarta
xTaskCreate(vedi “Un deadlock di priorità che era un malloc fallito”). - Stack spostati in PSRAM funzionavano finché un task chiamava
fopen. Il driver della flash disabilita la cache, il task perde il proprio stack, e il SoC si resetta senza stampare un panic. - Ora gli stack sono da 20 KB in SRAM interna. Gli high-water mark mostrano cinque task che usano circa 2 KB e uno che ne usa 14.484 B.
- Stack da 32 KB dalla SRAM interna facevano fallire silenziosamente la quarta
- Uno stub con il tipo sbagliato finisce nella flash in sola lettura.
_spu_transferCallbackè un puntatore a funzione. Dichiararlo come funzione lo metteva in.text, quindi il primo= 0andava in crash. L’ho trovato eseguendonmsu un ELF funzionante basato su psyz e su questo, confrontandoli concomm, ed elencando i simboli che là sonoB/De qui sonoT.
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
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:
- Ogni file riceve un intervallo sintetico di 1.000.000 di settori, così un numero di settore si mappa di nuovo su (file, offset) con una divisione.
CDBIOS_ReadRequestconsegna i dati settore per settore e chiama un callback dopo ogni settore. Il callback può riscrivere la dimensione rimanente.FS_CdStageFileInitdipende da questo per apprendere la dimensione della tabellaSTAGE.DIRdai suoi primi 4 byte. Trattare la richiesta come una semplice copia di byte e ignorare il callback faceva restituireNOT FOUNDa ogni ricerca di stage.- La consegna deve essere asincrona. Il parser e il “disco” sono coroutine che condividono una finestra di buffer. Consegnare tutto in una volta lasciava che il file 2 sovrascrivesse il file 1 prima che fosse analizzato. Ora
ReadRequestregistra solo la richiesta, eReadSyncpompa i settori finché il callback non restituisce 2 (“buffer reindirizzato”).
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.
- L’intero
STAGE.DIRda 71.892.992 byte (tutti i 96 stage) viene letto su richiesta. - Di 93 file di stage, 65 hanno tabelle di attori completamente simboliche. Gli altri 28 contengono ancora indirizzi MIPS grezzi perché il loro codice degli attori non è decompilato.
- Un generatore costruisce una tabella di attori deduplicata e una whitelist — 56 stage e 149 classi di attori. Il comando di cambio stage dello script controlla la whitelist mentre il mondo corrente è ancora intatto.
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:
- Un contatore che nessuno incrementa inventa una scoperta.
[trap] scanning 63 triggers, 0 entered so farè quasi diventato “il sistema dei trigger è morto”. Il contatore non aveva un++. Con uno vero, i trigger si attivavano dal primo secondo. - Un controllo tautologico dà falsa sicurezza. L’audit dello scheletro confrontava
|R·t|con|t|. Sono uguali per qualsiasi rotazione, quindi il controllo è rimasto verde per settimane mentre ogni scheletro era deformato (vedi “Lo strict aliasing ha cancellato una rotazione”). - Controlla dove viene scritto un campo prima di interpretarlo.
eye_inv.tsembra una posizione della telecamera ma è un vettore direzione ruotato. Leggerlo come una posizione ha prodotto una storia dettagliata e falsa su una telecamera che vola via. - Mantieni una sonda ampia finché i dati non la restringono. Ho filtrato la sonda delle primitive a schermo intero alle primitive non texturizzate, pensando che un flash non abbia texture. Un cono di luce di ricerca ne ha una.
- Dividi i contatori per causa. “Il 65% delle giunzioni è obsoleto” erano quattro cause in un unico gruppo, e quella principale erano oggetti radice innocui. Dopo la divisione, la mia correzione si è attivata zero volte, e l’ho rimossa.
- Strumenta tutti gli N scrittori. Quando
DG_UnDrawFrameCount = 0x7fff0000ha oscurato lo schermo, ho indovinato male due volte. Etichettando i quattro scrittori con"file:line"è emerso subitogame/gamed.c:476. - Decodifica i dati prima di sospettare dell’interprete. Lo script del dock sembrava eseguire un solo comando. Decodificando il bytecode retail sono emersi 19 nodi, di cui solo uno stampa (vedi “Il dock vuoto era uno script a due passaggi”).
- Controlla che la sonda sia nel binario. Una breadcrumb che leggeva “(nothing)” non era mai stata inserita, perché uno
str.replacescriptato era fallito silenziosamente. Faigrepdella stringa nel.bin. - Usa watchpoint hardware per scrittori anomali.
esp_cpu_set_watchpoint(0, addr, 4, STORE)ha mostrato che circa 230 desincronizzazioni della GPU provenivano daDG_PcxRead4Bpp, un decoder di texture il cui buffer di scratch si sovrapponeva ai pacchetti attivi. - Sospetta dei miglioramenti improvvisi. Quando la scheda non è riuscita a montarsi, la board è ricaduta su 9 stage in flash, e i tempi di caricamento sono scesi da 693 a 21 vblank. Sembra un speedup di 35x, ma significa che la scheda è assente. Controlla prima
microSD mountedetable_size 1152 -> 96 stages.
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

Lo strict aliasing ha eliminato una rotazione
- Sintomo: ogni personaggio aveva le braccia staccate dal torso, un ginocchio piegato all’indietro e i piedi puntati in direzioni diverse. Il mondo era a posto.
- Vicoli ciechi:
- Una “correzione” di
MulRotMatrixche peggiorava molto le cose ed è stata annullata. - Lo stride del modello, dimostrato essere di 88 byte dai dati in tre modi indipendenti.
- Cuciture obsolete, misurate con effetto zero.
- Un dump congelato della posa di riposo metteva tutte e 16 le articolazioni entro un millimetro dalle posizioni decodificate dal disco, con
det = 4096ed2 == wantsu ogni osso.
- Una “correzione” di
- Perché quei controlli non l’hanno individuato: nella posa di riposo ogni rotazione è l’identità,
d2 == wantè una tautologia, edetcontrolla il blocco 3x3, che era corretto. - Cosa l’ha individuato: le posizioni delle articolazioni in due frame diversi. L’offset genitore-figlio restava identico byte per byte mentre il genitore ruotava di 19 gradi.
- Causa principale:
CompMatrixscriveva la traslazione tramite(VECTOR*)&tmp.t[0]su unlong[3]. GCC 14 con-O2ha concluso che nulla legge quei valori e ha rimosso la chiamata. Il disassemblato non aveva istruzioni di moltiplicazione. Calcolavam2->t = m0->t + m1->t. - Correzione: aritmetica con
long longsenza type punning, più-fno-strict-aliasingper tutto il gioco. Un secondo caso identico esiste inlibdg/display.c:318, quindi il flag è la vera protezione. Un audit[rig]ora controlla ogni scheletro usando rapporti invarianti di scala rispetto all’osso più lungo: 14.416 articolazioni controllate, 0 difettose.
Lo schermo bianco: cinque ipotesi sbagliate, tre cause reali
- Sintomo: quando un nemico individuava Snake, un velo bianco copriva la scena. L’HUD restava visibile e c’erano lampi di colore.
- Ipotesi escluse dalla misurazione:
- Un flash a schermo intero. La sonda registrava 0 righe.
change camera -1come errore. È il sentinella “nessuna telecamera fissa qui”, e trattarlo come errore congelava la telecamera dietro il giocatore.- Una telecamera impazzita. Era il frainteso
eye_inv.t; la posizione reale era stabile. - Overflow della coda di disegno. Una correzione del culling ridusse i modelli disegnati da 25.093 a 14.054 e il bianco rimase.
setlen(pack, z_idx >> 8)individe.c.setlenfa un cast au_char, quindi non può produrre lunghezze come0x2E000000.
- Causa 1:
SetDrawStpfaceva((u_long*)p)[1] = 0xE6000000 | stp. In psyz, la parola 1 èlen, e il comando appartiene acode[0]. Il lettore vedeva un pacchetto lungo miliardi di parole, lo scartava e riprendeva a metà primitiva, decodificando i vertici come comandi. Si attivava in combattimento, perché i lampi di sparo e il fumo sono ciò che accende la semitrasparenza. psyz aveva già corretto lo stesso errore nel propriosetDrawTPage, ma nessuno aveva revisionato il gemello lato gioco. Dopo la correzione: 0 scartati, 0 desincronizzazioni. - Causa 2:
DG_MakePrimnon inizializzava mai la lunghezza. È corretto in un punto derivandolen = psize/4 - 2e verificando il risultato rispetto alle macro di psyz (FT4 dà 9, GT4 dà 12, TILE dà 3). - Causa 3, la regola hardware mancante: una volta inclusi i primitivi texturizzati, la sonda mostrava
[cover] code 3E abe 1 tex 1 box -1024,-1024..142,66, che è il limite di saturazione del GTE. I poligoni che attraversano dietro la telecamera vengono bloccati lì come quad che coprono lo schermo. La GPU PSX rifiuta qualsiasi poligono più grande di 1023x511, e il gioco dipende da questo. Il nostro rasterizzatore li disegnava: 27,8 M texel ogni 120 frame, circa tre schermate per frame, e 142 ms di rasterizzazione. Il test di dimensione ora viene eseguito insoft_raster.inc.cprima del clipping, perché il clipping ridurrebbe il poligono alla dimensione dello schermo e nasconderebbe proprio la proprietà in esame.
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:
- Movimento e collisioni.
- Raggio visivo dei nemici.
- Proiettili.
- Il sensore a infrarossi.
- Attenuazione della luce.
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:
- Un passo di
27,0sostenuto. - Y = 250.
- Rotazione fluida.
- Pixel texturizzati per frame saliti da 23.500 a 107.877.
- È tornata anche l’acqua, perché è vincolata alla telecamera dentro il volume d’acqua.
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:
- Tutti gli stream di input vengono rifiutati in
NewStreamControleseguendo il loro callback, con un watchdog di 600 frame come rete di sicurezza. Questo costa le cutscene e le voci, e dà un gioco che si può giocare. - L’input registrato del pad di una cutscene partiva subito e Snake se ne andava da solo. Ora quella riproduzione viene saltata allo stesso modo in cui il gioco la salta con START.
- Anche gli FMV vengono rifiutati, perché psyz non ha un decoder MDEC.
Bug minori
PSX_Wera 256, ereditato dal codice che ho riutilizzato. MGS renderizza 320 colonne, quindi un quinto dell’immagine andava perso. Controlla ogni costante ereditata.- Race all’avvio: il tick leggeva la seriale USB prima che il driver fosse installato, causando
LoadProhibitedin 2 avvii su 6 misurati. - Il frame dropper di Konami: due attori leggevano il flag di skip in momenti diversi, quindi i buffer venivano scambiati senza essere disegnati e lo schermo sfarfallava. Entrambi i flag sono forzati a 0 sotto
__psyz. Le scene pesanti ora girano più lentamente invece di sfarfallare. - “Collisione rotta”: le spinte contro i muri misuravano circa 452 contro un raggio di 450, che è esattamente giusto. A 8-10 fps, una correzione di 450 unità sembra solo un salto.
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:
SOFT_RASTER_IRAMera vuoto nella build di MGS, quindi i cicli per pixel venivano eseguiti dalla flash. Dovrebbe essereIRAM_ATTR. La correzione ha dato -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. ControllaCONFIG_SPIRAM_SPEED 120nel filesdkconfig.hgenerato. - 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%.
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).
- Un burst di 128 invece di 16 settori ha guadagnato solo il 7%.
- La scheda è affidabile a 20 MHz sulla scheda Waveshare. A 40 MHz dà errori CRC.
- Saltare le chiamate
fseekridondanti è già in atto ma non ancora misurato.
Mettere in funzione l’handheld

L’handheld è costruito con:
- Un XIAO ESP32S3 Sense, la cui scheda di espansione fornisce lo slot microSD.
- Un pannello SPI ILI9341.
- Un gimbal di un controller per droni.
- 8 pulsanti: 6 su una scala di resistori su un pin ADC, più fuoco e mira sui propri pin, perché una scala registra un solo pulsante alla volta.

Tutti gli 11 pin dello XIAO sono utilizzati. Il cablaggio è documentato nella guida hardware. Note di bring-up:
- La massa mancante. Il pannello si illuminava di bianco e cambiava luminosità quando venivano inviati dati, perché si alimentava attraverso i diodi di protezione sui suoi ingressi. Prima di allora, le misurazioni avevano escluso il cablaggio, il impulso di reset, la tensione di alimentazione e la configurazione SPI. Un mio bug è costato anche due giri: una modifica scriptata pensata per inserire
lcd_bus_init()è fallita silenziosamente, e il pannello è stato risaldato per nulla. - ILI9341, non ILI9488. Il piano prevedeva un ILI9488 480x320, che su SPI accetta solo RGB666 a 3 byte. Un mio progetto precedente con lo stesso pannello ha mostrato che è un ILI9341 a 320x240. Meglio del previsto: risoluzione nativa, nessun ridimensionamento, 2 byte per pixel. L’ordine dei colori è stato verificato con tre strisce R/G/B etichettate contemporaneamente.
- RST su un pin reale. Con RESET collegato a 3V3 e solo un reset software, l’ILI9341 non si avviava in modo affidabile, quindi RST è stato spostato su D4. D4 era libero perché il CS della scheda è GPIO21, interno alla scheda Sense. Una ricerca web aveva dato pin SD sbagliati. L’errore era
ESP_ERR_INVALID_ARG, un errore di configurazione più che un errore della scheda, che ha portato alla documentazione ufficiale di Seeed. - Pulsanti e potenziometri. Collega gli interruttori a 4 piedini sui piedini diagonali, altrimenti un pulsante risulta premuto permanentemente. Per i potenziometri:
- Una lettura bloccata a 0 o 4095 significa che il filo è su un piedino esterno.
- Una lettura bloccata a metà scala significa che il potenziometro non ha 3V3/GND.
- Un intervallo ampio significa che l’asse è sano.
- Calibrazione dello stick. Il gimbal a riposo sta a 2317, non 2048, e X va da 141 a 2888.
- Il centro è la lettura a riposo all’avvio, e ogni metà è scalata dalla corsa vista in quella direzione.
- La zona morta è di 60 conteggi (circa 4 volte il rumore misurato di +/-15), sottratta su entrambi i lati così il movimento inizia in modo fluido.
- Ogni asse fa la media di 8 letture, ed entrambi gli assi sono invertiti nel software.
- Un min/max accumulato dall’avvio è inutile qui, perché un ingresso flottante tocca 0 e 4095 all’accensione. Usa una finestra mobile.
- Le letture ADC nel tick di vblank bloccavano tutto. 24 conversioni per tick bloccavano il tick e ogni task mts. L’avvertimento era già scritto in
esp_input.c. Ora un task sul core 1 campiona ogni 10 ms e pubblica tre interi. printfsu USB nativo si blocca quando nessun host lo drena (UART no). MGS stampa molto, quindi una stampa bloccata fermava lo scheduler cooperativo.port/mgs_printf.hscrive con un timeout zero.- Coppie di clock. PSRAM a 120 MHz con flash a 80 MHz non è una coppia MSPI supportata, e il fallimento sembra un bug della toolchain. Lo XIAO per ora gira a 80/80, e 120/120 è la prossima cosa da misurare.
- SPI del pannello. Con fili jumper il pannello è stabile a 40 MHz. A 80 MHz, bande dell’immagine scivolano lateralmente.
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
- Le chiamate al codec. Il gruppo di volti da 417.792 byte ora si carica da una riserva statica di PSRAM, perché il pool del gioco rifiuta l’allocazione. L’indice di
RADIO.DATè ancora sbagliato: il settore di inizio calcolato è 31.392, e il file ha 867 settori. Il valore di input è sbagliato; l’aritmetica è corretta. Abilitare la vera schermata del codec va anche in panic dentro unprintf. - L’intro. Avviare attraverso la schermata del titolo ha dato 11 panic. L’ultima riga prima del primo era
this memcard is OK. Il swim-in e il briefing richiedono la memory card, lo streaming da CD e il codec. - L’ascensore. Le sonde in entrambi i costruttori dell’ascensore restano silenziose per un’intera sessione, quindi lo script della scena non lo richiede mai. La ragione probabile, non ancora provata, è una variabile di storia che solo una chiamata al codec fa avanzare.
- Lo streaming da CD (cutscene, voci), FMV (nessun MDEC), audio e salvataggi su memory card.
- 28 stage il cui codice degli attori è ancora assembly MIPS.
- Le prestazioni oltre circa 15 fps.
Prossimi passi
- Ridimensionare correttamente gli stack mts e spostare le pagine di texture più usate nella SRAM interna.
- Misurare i clock di memoria 120/120 MHz sullo XIAO.
- Correggere l’indice di
RADIO.DAT, poi verificare se l’ascensore ne consegue. - Implementare lo streaming nel CD virtuale, per recuperare cutscene e voci.
- Aggiungere l’audio tramite una SPU software.
- 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.