
Ich liebe Metal Gear Solid seit meiner Kindheit. Als ich ein winziges ESP32-S3-Board bekam, ließ mich eine Frage nicht los: Könnte ein PlayStation-Spiel auf etwas so Kleinem laufen?

Das Board ist das Seeed Studio XIAO ESP32S3 Sense: ein Dual-Core-ESP32-S3 mit 8 MB PSRAM und 8 MB Flash, auf einem Modul von 21 × 17,8 mm. Die Sense-Version fügt ein Erweiterungsboard mit einer Kamera und einem microSD-Slot hinzu, und in diesem microSD-Slot liegen die Spieldaten.
Ich habe eine ganze Weile damit verbracht, das herauszufinden. Zuerst suchte ich nach einer Version des Spiels, die bereits als C-Code neu aufgebaut worden war und auf einem PC läuft, und dann prüfte ich, ob all diese Logik in den Flash des ESP32-S3 und auf eine microSD-Karte passt. Es brauchte mehrere Anläufe, aber am Ende hat es funktioniert. Ein wunderbares Spiel läuft jetzt auf einem Mikrocontroller-Board, das etwa 15 USD kostet.
Gameplay auf dem Handheld: auf YouTube ansehen.
In diesem Artikel beschreibe ich, wie Metal Gear Solid (PlayStation, 1998) als nativer Port auf dem ESP32-S3 läuft. Der C-Quellcode des Spiels, rekonstruiert durch die mgs_reversing-Dekompilierung des FoxdieTeam, wird direkt zu Xtensa-Maschinencode kompiliert. Alles, was früher die PlayStation-Hardware bereitstellte, wird durch Software ersetzt:
- Das SDK.
- Die GPU.
- Den GTE-Geometrie-Coprozessor.
- Das CD-Laufwerk.
- Den Vertical-Blank-Interrupt.
- Den Controller.
Der Artikel behandelt die Hardware, die Plattformschicht, die Speicherplatzierung, die Debugging-Methode, die Bugs, die am wichtigsten waren, die Performance, das Handheld und das, was noch nicht funktioniert.
Der Code und verwandte Projekte:
- MGS-Port: davidmonterocrespo24/mgs_reversing, Branch
esp32-port. - Handheld-Hardware-Anleitung: HARDWARE.md.
- psyz-Fork: davidmonterocrespo24/psyz.
Du brauchst deine eigene Disc. Das Repository enthält nichts, was vom Spiel abgeleitet ist, und port/extract_disc.py zieht die Dateien aus deinem eigenen Disc-Image heraus.
Hardware

Der ESP32-S3 hat zwei Xtensa-Kerne mit 240 MHz und 512 KB internen SRAM. Beide hier verwendeten Boards haben außerdem 8 MB PSRAM, das hinter demselben Cache wie der Flash liegt.
| Waveshare ESP32-S3-Touch-LCD-2 | DIY-Handheld (Seeed XIAO ESP32S3 Sense) | |
|---|---|---|
| Panel | ST7789, 320x240 | ILI9341, 320x240 nativ |
| Flash | 16 MB | 8 MB |
| Spieldaten | microSD, oder eine gekürzte STAGE.DIR im Flash | microSD (vollständige STAGE.DIR) |
| Eingabe | Tastatur über seriell (play.py) | Drohnen-Gimbal-Stick, 6-Tasten-Widerstandsleiter, 2 direkte Tasten |
Die Lücke messen, bevor Code geschrieben wird
Bevor ich irgendeinen Port-Code schrieb, habe ich gemessen, wie weit die Dekompilierung davon entfernt war, für Xtensa zu bauen:
- Die Engine-Bibliotheken (libgv, libdg, libgcl, libhzd, libfs) ließen sich fast sofort mit
xtensa-esp32s3-elf-gcc14.2 gegen die psyz-Header kompilieren: 57 von 58 Dateien. - Keine von ihnen enthält absolute
0x800xxxxx-Adressen. - Die gesamte Grafikausgabe läuft über 11 libgpu-Aufrufe (
DrawOTag,LoadImage,ClearOTagRund so weiter). Genau das ist die Schicht, die der Software-Renderer von psyz ersetzt.
Ich habe die eine fehlschlagende Datei, libdg/chanl.c, absichtlich fehlschlagen lassen. Der Cast, der sie zum Schweigen gebracht hätte, hätte auch stillschweigend den Stride verändert (siehe den Abschnitt zur Ordering-Tabelle unten).
Der Rest erforderte mechanische Durchgänge, von denen jeder eine ganze Problemklasse behob:
-std=gnu17und-mlongcallssind beide zwingend erforderlich. Das standardmäßige gnu23 von GCC 14 lehnt diesen Code ab, und Xtensacall8erreicht nur +/-512 KB.- psyz und MGS haben beide eine
common.h, also müssen die Include-Pfade von MGS zuerst kommen. - 12 Cast-als-lvalue-Ausdrücke, eine GCC-2.x-Erweiterung, wurden umgeschrieben.
- MGS ersetzt das
printfder libc durch seinen eigenen Stub. Ich habe es inmts_printfumbenannt, und das verursachte später einen der irreführendsten Bugs (siehe „Der Boot, der hängen zu bleiben schien”). - 346 literale Scratchpad-Adressen (
0x1f8000xx) über 16 Dateien hinweg wurden zuSCRPAD_ADDR + offset, gestützt auf ein Array.
Das Ergebnis waren 497 von 497 C-Dateien, die zu Xtensa kompiliert wurden. Das ELF hatte 0 undefinierte Referenzen und 0 doppelte Definitionen (Text 987.073 B, BSS 2.434.276 B). Der eigene Speicher des Spiels beträgt 804 KiB (428 KiB Heap plus zwei 188-KiB-Paketpuffer), was bequem in PSRAM passt.
----- END POST -----
Architektur
Der Port hat drei Schichten zwischen dem Spiel und dem SoC:
Die Schichten, vom Spiel bis hinunter zur Hardware:
- MGS-Engine: dekompiliertes C, kompiliert für Xtensa
- psyz: PlayStation-SDK und GTE in C, Software-Rasterizer
- Plattformschicht: mts-Scheduler auf FreeRTOS, Vblank-Tick, virtuelles CD, LCD, Eingabe
- ESP32-S3
psyz und die GTE
psyz, Xeeynamos Reimplementierung des PlayStation-SDK, modellierte bereits die gesamte GTE-Registerdatei und jede GTE-Operation in C, validiert gegen die PCSX-Redux-GTE-Testsuite.
Meine erste Schätzung war, dass 64 bis 70 Makros fehlten. Diese Schätzung war zu hoch. MGS liefert eigene MIPS-Inline-Asm-Header mit (inline_n.h, inline_x.h), und -fsyntax-only prüft keine Registernamen. Nachdem diese Header auf psyz umgeleitet wurden, betrug die tatsächliche Lücke 41 Makros. Ich fügte sie zu psyz hinzu und nutzte die Assembler-Ausgabe des Spiels selbst als Spezifikation dafür, welche COP2-Register jedes einzelne berührt. Dann baute ich meine anderen psyz-basierten Projekte gegen das modifizierte psyz neu, um sicherzustellen, dass nichts kaputtging.
Wenn man ein GTE-Makro aliast, sollte man prüfen, ob jede Constraint ein Input oder ein Output ist. Zum Beispiel hat gte_read_opz einen "=r"-Output, also muss sein Alias &x annehmen.
Das Ordering-Table-Tag — ein Wort auf PSX, zwei in psyz
Dies ist der wichtigste Layout-Unterschied, und er verursachte die meisten Bugs. Auf der PlayStation beginnt jede Primitive mit einem 32-Bit-Tag — 24 Bits Adresse der nächsten Primitive und 8 Bits Länge. Ein Host-Pointer passt nicht in 24 Bits, also verwendet psyz zwei Wörter, tag und len. Jede Primitive wächst um 4 Bytes, und jedes Feld nach dem Tag verschiebt sich um ein Wort.
MGS missbraucht außerdem das Längenbyte. libdg führt einen zweiphasigen Radix-Sort über 16-Bit-Tiefe durch:
divide.cverteilt nach dem niedrigen Byte in Buckets und parkt das hohe Byte in der Länge des Tags.sort.cverteilt nach diesem hohen Byte erneut in Buckets und schreibt die echte Länge.
Da psyz die beiden Felder trennt, ist die Übersetzung exakt:
pack->tag = (hi << 24) | *ot; *ot = pack; /* PSX */
addPrim(ot, pack); setlen(pack, hi); /* psyz */
42 lokale Deklarationen und 100 Parameter auf OT_TYPE* umzutippen war der leichte Teil. Der schwierige Teil war Code, der das gepackte Layout voraussetzte, ohne es zu sagen:
DG_PrimInfossetzte den ersten Vertex auf +8 statt +12.LinkModelToParentberechnete Parent-Vertex-Offsets als*52 + 8statt*56 + 12vor.- Die Primitiv-Konstruktoren, die unten in „Der weiße Bildschirm” beschrieben werden.
Es gibt außerdem einen erschwerenden Faktor. Auf der Konsole schrieb addPrim() bei jeder Einfügung das gesamte Tag-Wort neu, sodass eine vergessene Länge nie auffallen konnte. In psyz wird eine Länge, die nie gesetzt wurde, einfach nie geschrieben.
Konamis Scheduler innerhalb von FreeRTOS
MGS läuft auf Konamis eigenem kooperativen Scheduler. Das Boot-Banner liest noch immer Multi Task Scheduler for PSX ver2.02 Jul 11 1998. Er sitzt auf der BIOS-Thread-API (OpenTh/ChangeTh) und nutzt den Vblank-Interrupt, um Tasks aufzuwecken, deren Timer abgelaufen sind.
Im Port ist jeder mts-Thread ein FreeRTOS-Task, und nur einer von ihnen ist jemals gleichzeitig lauffähig. Das endgültige Design:
- Alle mts-Tasks sind an Kern 0 gebunden, zusammen mit dem Vblank-Tick bei Priorität 10, sodass der Tick das Spiel so unterbricht, wie es der PSX-Interrupt tat. LCD-Scanout läuft auf Kern 1. Diese Zuweisungen zu vertauschen verursachte Races, die geparkte Tasks mitten im Stack wiederbelebten. Ein Log zeigte zwei Kopien von
Main(), Zeile für Zeile verschachtelt. - Ein neuer Task suspendiert sich selbst in seinem Trampolin.
xTaskCreategefolgt vonvTaskSuspendist nicht atomar, und auf zwei Kernen lief der Task, bevor sein Control Block gefüllt war. - Kritische Abschnitte sind echt. Jeder Task hat ein absolutes Flag, das bei jedem Wechsel gespeichert und wiederhergestellt wird, wie das MIPS-Statusregister. Es ist ein Flag statt eines Zählers, weil das Spiel
ExitCriticalSectionohne ein passendesEnteraufruft. - Der Tick führt den mts-Callback nur aus, während der Idle-Task (11) aktiv ist. Dieser Task ist Konamis SIO-Konsolen-Schleife, der einzige Code, der niemals den Scheduler-Zustand berührt. Auf der Konsole lief er genau aus diesem Grund mit aktivierten Interrupts. Das Spiel durchläuft jede Frame den Idle-Zustand, sodass die Aufweck-Latenz unter einer Frame bleibt. Diese Änderung beseitigte sporadische Hänger an der Quelle, wo frühere flag-basierte Versionen nur das Race-Fenster verengt hatten.
mts_GetTcbEntry las außerdem die BIOS-Tabelle der Tabellen an der festen Adresse 0x100 und schrieb durch das Ergebnis. Außerhalb einer PSX enthält diese Adresse Müll, also verwendet es jetzt eine private TCB-Tabelle.
Der Vblank-Tick und die zwei Uhren
port/esp32_vblank.c feuert den VSync-Callback des Spiels alle 16 ms. Dafür musste VSyncCallback() in psyz implementiert werden, wo es nicht einmal den Pointer speicherte.
VSync(-1) muss einen frei laufenden Vblank-Zähler zurückgeben. Die erste Version gab die Anzahl der präsentierten Frames zurück, die stehen bleibt, wenn nichts zeichnet, sodass kein Timer jemals ablief.
Die Bildrate variiert — 2 Vblanks pro Frame in einem Korridor, 4 bis 5 in einem offenen Raum. Deshalb gehören zwei Dinge, die nach Vblank-Arbeit aussahen, tatsächlich zur Spiel-Frame:
- Serielle Key-Holds werden in
DG_ActFirstdekrementiert, direkt nachGV_UpdatePadSystem, dem einzigen Punkt, der bedeutet „eine Frame hat das Pad gelesen”. Vblanks dort zu zählen ließ Snake entweder zu weit laufen oder gab Tasten frei, bevor das Spiel sie sah. - Das LCD sendet nur dann eine Frame, wenn sich eine in
DG_SwapFrameerhöhte Sequenznummer geändert hat, mit einem 250-ms-Fallback.
Speicherplatzierung
Internes SRAM ist knapp und schnell. PSRAM ist reichlich und langsam. Flash-Lesevorgänge deaktivieren den Cache, von dem auch PSRAM abhängt.
- Die RAM-Map des Spiels hängt an einem Define,
MEM_BOTTOM. Beide Packet-Arenen, der Heap und der libfs-Sektorpuffer stammen durch Subtraktion daraus. Sie wird auf ein statisches PSRAM-Array verschoben (mgs_main_ram[0xC9000],EXT_RAM_BSS_ATTR). Sie muss statisch sein, weilRESIDENT_BOTTOMals statischer Initialisierer verwendet wird, wasmallocausschließt. - Die 1 MB PSX-VRAM lebt im PSRAM. Ohne
EXT_RAM_BSS_ATTRläuft dram0 um etwa 900 KB über. - Task-Stacks wanderten hin und her.
- 32-KB-Stacks aus internem SRAM ließen das vierte
xTaskCreatestill fehlschlagen (siehe „Ein Priority-Deadlock, der ein fehlgeschlagenes malloc war”). - Stacks, die nach PSRAM verschoben wurden, funktionierten, bis ein Task
fopenaufrief. Der Flash-Treiber deaktiviert den Cache, der Task verliert seinen eigenen Stack, und der SoC startet neu, ohne eine Panic auszugeben. - Stacks sind jetzt 20 KB im internen SRAM. High-Water-Marks zeigen fünf Tasks mit etwa 2 KB und einen mit 14.484 B.
- 32-KB-Stacks aus internem SRAM ließen das vierte
- Ein Stub mit dem falschen Typ landet im Nur-Lese-Flash.
_spu_transferCallbackist ein Funktionspointer. Ihn als Funktion zu deklarieren legte ihn in.text, sodass das erste= 0abstürzte. Ich fand es, indem ichnmauf einem funktionierenden psyz-basierten ELF und auf diesem ausführte, sie mitcommverglich und Symbole auflistete, die dortB/Dund hierTsind.
Eine Klasse von Bugs existiert nur auf dieser Speicher-Map — Pointer-Tests basierend auf dem Vorzeichenbit. MGS unterscheidet einen Script-Block-Pointer von einer 16-Bit-Proc-ID mit proc_id < 0. PSX-RAM liegt bei 0x8xxxxxxx, was als vorzeichenbehafteter Wert negativ ist. PSRAM liegt bei 0x3Cxxxxxx, was positiv ist. Das Ergebnis war PROC 3C1987D2 NOT FOUND, gefolgt von einem LoadProhibited bei EXCVADDR 0x00000003. Ein GCL_IS_BLOCK_PTR-Makro behebt die Stelle, die getroffen wurde. Andere Stellen mit demselben Muster brauchen noch ein Audit.
Ein virtuelles CD über FAT
libfs arbeitet mit absoluten Sektoren. Es liest das ISO9660-Verzeichnis einmal und verwendet nie wieder einen Dateinamen. port/virtual_cd.c ersetzt das CD-BIOS:
- Jede Datei bekommt einen synthetischen Bereich von 1.000.000 Sektoren, sodass eine Sektornummer mit einer Division auf (Datei, Offset) zurückgeführt wird.
CDBIOS_ReadRequestliefert Daten Sektor für Sektor und ruft nach jedem Sektor einen Callback auf. Der Callback darf die verbleibende Größe umschreiben.FS_CdStageFileInithängt davon ab, um die Größe derSTAGE.DIR-Tabelle aus ihren ersten 4 Bytes zu erfahren. Die Anfrage als einfache Byte-Kopie zu behandeln und den Callback zu ignorieren ließ jede Stage-SucheNOT FOUNDzurückgeben.- Die Auslieferung muss asynchron sein. Der Parser und die „Disc” sind Koroutinen, die sich ein Pufferfenster teilen. Alles auf einmal auszuliefern ließ Datei 2 Datei 1 überschreiben, bevor sie geparst war.
ReadRequestzeichnet jetzt nur die Anfrage auf, undReadSyncpumpt Sektoren, bis der Callback 2 zurückgibt („Puffer umgeleitet”).
Die Daten lebten zuerst im PSRAM, was das Spiel auf eine Handvoll Stages begrenzte. Die eigentliche Lösung war die microSD. Die Karte ist ein SPI-Peripheriegerät, getrennt vom XIP-Flash, sodass das Lesen von ihr nicht den Instruktions-Cache deaktiviert. Dateien bleiben auf der Karte und kosten kein PSRAM.
- Die vollständige
STAGE.DIRmit 71.892.992 Bytes (alle 96 Stages) wird bei Bedarf gelesen. - Von 93 Stage-Dateien haben 65 vollständig symbolische Actor-Tabellen. Die anderen 28 enthalten noch rohe MIPS-Adressen, weil ihr Actor-Code nicht dekompiliert ist.
- Ein Generator baut eine deduplizierte Actor-Tabelle und eine Whitelist auf — 56 Stages und 149 Actor-Klassen. Der Stage-Wechsel-Befehl des Skripts prüft die Whitelist, während die aktuelle Welt noch intakt ist.
Die Karte und das LCD teilen sich SPI2, und ESP-IDF arbitriert nicht zwischen ihnen. Eine LCD-Frame besteht aus 30 in die Warteschlange gestellten asynchronen Transfers, sodass ein Kartenlesevorgang mitten in einer Frame assert failed: spi_hal_iram.c:134 auslöste und eine Reboot-Schleife verursachte. Die Lösung ist explizites Bus-Eigentum (Mgs_SpiBusTake/Give), das laufende Transfers leert, bevor der Bus freigegeben wird.
Methode: messen, nicht raten
Etwa ein Drittel der naheliegenden Erklärungen in diesem Projekt erwies sich als falsch. Was funktionierte, war das Board dazu zu bringen, eine Zahl auszugeben, die zwischen Hypothesen entscheidet. Die nützlichsten Lektionen kamen von Sonden, die falsche Antworten lieferten:
- Ein Zähler, den niemand inkrementiert, erfindet einen Befund.
[trap] scanning 63 triggers, 0 entered so farwäre fast zu „das Trigger-System ist tot” geworden. Dem Zähler fehlte ein++. Mit einem echten feuerten Trigger ab der ersten Sekunde. - Eine tautologische Prüfung erzeugt falsches Vertrauen. Die Skeleton-Prüfung verglich
|R·t|mit|t|. Diese sind für jede Rotation gleich, also blieb die Prüfung wochenlang grün, während jedes Skeleton deformiert war (siehe „Strict Aliasing hat eine Rotation gelöscht”). - Prüfe, wo ein Feld geschrieben wird, bevor du es interpretierst.
eye_inv.tsieht wie eine Kameraposition aus, ist aber ein rotierter Richtungsvektor. Die Lesart als Position erzeugte eine detaillierte, falsche Geschichte über eine davonfliegende Kamera. - Halte eine Sonde breit, bis die Daten sie eingrenzen. Ich filterte die Vollbild-Primitiv-Sonde auf untexturierte Primitive, in der Annahme, ein Blitz habe keine Textur. Ein Suchscheinwerferkegel hat eine.
- Teile Zähler nach Ursache auf. „65 % der Nähte sind veraltet” waren vier Ursachen in einem Topf, und die große davon waren harmlose Root-Objekte. Nach der Aufteilung feuerte mein Fix null Mal, und ich entfernte ihn.
- Instrumentiere alle N Schreiber. Als
DG_UnDrawFrameCount = 0x7fff0000den Bildschirm schwärzte, riet ich zweimal falsch. Die vier Schreiber mit"file:line"zu markieren benannte sofortgame/gamed.c:476. - Dekodiere die Daten, bevor du den Interpreter verdächtigst. Das Skript des Docks schien einen Befehl auszuführen. Das Dekodieren des Retail-Bytecodes zeigte 19 Knoten, von denen nur einer etwas ausgibt (siehe „Das leere Dock war ein Zwei-Pass-Skript”).
- Prüfe, dass die Sonde im Binary ist. Ein Breadcrumb, der „(nothing)” anzeigte, war nie eingefügt worden, weil ein skriptgesteuertes
str.replacestillschweigend fehlgeschlagen war.grepden String in der.bin. - Nutze Hardware-Watchpoints für ausreißende Schreiber.
esp_cpu_set_watchpoint(0, addr, 4, STORE)zeigte, dass etwa 230 GPU-Desyncs vonDG_PcxRead4Bppstammten, einem Textur-Decoder, dessen Scratch-Puffer mit aktiven Paketen überlappte. - Sei misstrauisch bei plötzlichen Verbesserungen. Als die Karte nicht gemountet werden konnte, fiel das Board auf 9 Stages im Flash zurück, und die Ladezeiten sanken von 693 auf 21 vblanks. Das sieht wie eine 35-fache Beschleunigung aus, bedeutet aber, dass die Karte fehlt. Prüfe zuerst auf
microSD mountedundtable_size 1152 -> 96 stages.
Jeden Build ausführen, ohne das Board zu flashen
Diese Methode funktioniert nur, wenn ein Versuch wenig kostet, und nach mehreren Stunden Versuch und Irrtum war das Flashen nach jeder Änderung alles andere als billig: Image per USB auf den XIAO schreiben, auf den Neustart warten, das serielle Log lesen, von vorn. Deshalb habe ich jeden Build mit velxio-cli ausgeführt und geprüft, dem Kommandozeilen-Client von Velxio. Er nimmt dieselbe .bin, die meine Toolchain erzeugt, führt sie eine feste simulierte Zeit lang auf Velxios simuliertem ESP32-S3 aus und liefert die serielle Ausgabe zurück. So konnte ich die Messpunkte oben lesen, ohne die Hardware anzufassen. Das Board bekam nur dann ein neues Image, wenn sich ein Build dafür lohnte.
# 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 .
Installation und erster Lauf dauern ein paar Minuten: siehe den velxio-cli-Schnellstart.
Die Bugs

Strict Aliasing löschte eine Rotation
- Symptom: Bei jeder Figur waren die Arme vom Torso getrennt, ein Knie nach hinten gebogen und die Füße zeigten in verschiedene Richtungen. Die Welt war in Ordnung.
- Sackgassen:
- Ein
MulRotMatrix-”Fix”, der alles deutlich schlimmer machte und zurückgerollt wurde. - Der Model-Stride, der auf drei unabhängige Weisen aus den Daten als 88 Bytes bewiesen wurde.
- Veraltete Seams, mit gemessen null Effekt.
- Ein eingefrorener Rest-Pose-Dump, bei dem alle 16 Gelenke innerhalb eines Millimeters der vom Disc dekodierten Positionen lagen, mit
det = 4096undd2 == wantbei jedem Knochen.
- Ein
- Warum diese Checks es übersahen: In der Rest-Pose ist jede Rotation die Identität,
d2 == wantist eine Tautologie, unddetprüft den 3x3-Block, der korrekt war. - Was es aufdeckte: Gelenkpositionen in zwei verschiedenen Frames. Der Parent-to-Child-Offset blieb Byte für Byte identisch, während der Parent sich um 19 Grad drehte.
- Ursache:
CompMatrixschrieb die Translation über(VECTOR*)&tmp.t[0]über einlong[3]. GCC 14 bei-O2schloss daraus, dass niemand diese Stores liest, und entfernte den Aufruf. Die Disassembly enthielt keine Multiplikationsbefehle. Sie berechnetem2->t = m0->t + m1->t. - Fix:
long long-Arithmetik ohne Type Punning, plus-fno-strict-aliasingfür das gesamte Spiel. Ein zweiter identischer Fall existiert inlibdg/display.c:318, also ist das Flag der eigentliche Schutz. Ein[rig]-Audit prüft jetzt jedes Skelett anhand skalierungsinvarianter Verhältnisse zum längsten Knochen: 14.416 Gelenke geprüft, 0 fehlerhaft.
Der weiße Bildschirm: fünf falsche Hypothesen, drei echte Ursachen
- Symptom: Wenn ein Gegner Snake entdeckte, bedeckte eine weiße Fläche die Szene. Das HUD schien weiterhin durch, und es gab Farbblitze.
- Durch Messung ausgeschlossene Hypothesen:
- Ein Full-Screen-Blitz. Die Probe protokollierte 0 Zeilen.
change camera -1als Fehler. Es ist der Sentinel für “hier keine feste Kamera”, und die Behandlung als Fehler fror die Kamera hinter dem Spieler ein.- Eine durchgehende Kamera. Das war das falsch gelesene
eye_inv.t; die tatsächliche Position war stabil. - Draw-Queue-Überlauf. Ein Culling-Fix reduzierte gezeichnete Modelle von 25.093 auf 14.054, und das Weiß blieb.
setlen(pack, z_idx >> 8)individe.c.setlencastet zuu_char, kann also keine Längen wie0x2E000000erzeugen.
- Ursache 1:
SetDrawStpmachte((u_long*)p)[1] = 0xE6000000 | stp. In psyz ist Wort 1len, und der Befehl gehört incode[0]. Der Reader sah ein Paket von Milliarden Wörtern Länge, verwarf es und setzte mitten in einem Primitiv wieder an, wobei er Vertices als Befehle dekodierte. Es trat im Kampf auf, weil Mündungsfeuer und Rauch das sind, was Semi-Transparenz einschaltet. psyz hatte denselben Fehler in seinem eigenensetDrawTPagebereits behoben, aber niemand hatte das spielseitige Gegenstück überprüft. Nach dem Fix: 0 verworfen, 0 Desync. - Ursache 2:
DG_MakePriminitialisierte die Länge nie. Sie wird an einer Stelle behoben, indemlen = psize/4 - 2abgeleitet und das Ergebnis gegen die psyz-Makros geprüft wird (FT4 ergibt 9, GT4 ergibt 12, TILE ergibt 3). - Ursache 3, die fehlende Hardware-Regel: Sobald texturierte Primitive einbezogen wurden, zeigte die Probe
[cover] code 3E abe 1 tex 1 box -1024,-1024..142,66, was das GTE-Sättigungslimit ist. Polygone, die hinter die Kamera ragen, werden dort als bildschirmüberspannende Quads festgenagelt. Die PSX-GPU verweigert jedes Polygon, das größer als 1023x511 ist, und das Spiel verlässt sich darauf. Unser Rasterizer zeichnete sie: 27,8 M Texel pro 120 Frames, etwa drei Bildschirme pro Frame, und 142 ms Rasterisierung. Der Größen-Test läuft jetzt insoft_raster.inc.cvor dem Clipping, weil Clipping das Polygon auf Bildschirmgröße schrumpfen und genau die zu testende Eigenschaft verbergen würde.
Der Culling-Fix aus Hypothese 4 war real, auch wenn er nicht die Ursache war. Der Bounding-Box-Test behandelte eine Box, die die Near-Plane kreuzt, genauso wie eine, die vollständig dahinter liegt. Die Trennung der beiden Fälle brachte kept-saturated von 16.090 auf 4.947. Ein früherer Versuch setzte bei gesättigten Koordinaten an und rettete 97 % von allem, was der Bildschirmtest verwarf (+40 % Rasterisierung), weil eine große, weit entfernte Wand ebenfalls sättigt. Direkt nach Z zu fragen (SZ <= H/2) ergab 1.440 statt 15.000.
Square0 um 12 Bits verschoben: jede Distanz /64
Snake machte drei Schritte, stieß gegen eine Wand, prallte zurück und kam nie voran. Die Framerate war der erste Verdacht. Eine Beobachtung schloss sie aus: Die Welt bewegte sich einwandfrei, nur der Spieler nicht. Eine Probe in GM_ActControl zeigte einen Schritt von +4481, gefolgt von einem Rückstoß von -14641.
In PSY-Q ist das numerische Suffix die Verschiebung: Square0 verschiebt nicht, Square12 schon. Das Square0 des Ports verschob um 12, also kam jede Square0 -> sum -> sqrt-Länge als /64 heraus. Das brach:
- Bewegung und Kollisionen.
- Sichtweite der Gegner.
- Kugeln.
- Den Infrarotsensor.
- Lichtdämpfung.
Das Entfernen der Verschiebung machte die Trajektorie monoton.
Fünf GTE-Opcodes aus der falschen Zeile kopiert
Snake war aus der Welt gefallen (Y = -3250), die Bewegung war auf 0,1 pro Frame festgenagelt, und der Dock hatte kein Wasser. psyz’ Psyz_GteRtv0/Rtv1/Rtv2/Ll/Llv0 verwendeten MVMVA-Opcodes aus der falschen Zeile von MGS’ eigener inline_n.h-Tabelle. “Diesen Vektor rotieren” wurde zu “ihn rotieren und die veraltete Translation addieren”, und die Beleuchtung verwendete die Rotationsmatrix statt der Lichtmatrix.
Nach dem Fix:
- Ein Schritt von
27,0wurde durchgehalten. - Y = 250.
- Sanftes Drehen.
- Texturierte Pixel pro Frame stiegen von 23.500 auf 107.877.
- Das Wasser kam ebenfalls zurück, weil es daran geknüpft ist, dass die Kamera sich im Wasservolumen befindet.
Der leere Dock war ein Zwei-Pass-Skript
Der Dock hatte nur eine Handvoll Objektgruppen, und das Skript schien einen Befehl auszuführen. Die tatsächliche Struktur von s00a ist if (var[5] < 6) { set up the Colonel's call } else { build the dock }, und die Proc des Calls ist ein restart. Die Welt wird im zweiten Durchlauf aufgebaut, und das Beantworten des Codec löst ihn aus.
Ich hatte den Codec selbst abgeschaltet, um einen Absturz zu vermeiden, und das deaktivierte jedes radio -c ... -p proc in jeder Stage. MENU_RadioDrainHeadless beantwortet jetzt den Call und führt seine Proc aus, ohne den Codec-Bildschirm zu öffnen. Objektgruppen gingen von 480 auf 3.240 pro 120 Frames, und der Wasserbereich wurde erstellt. Die Lektion: Ein temporärer Stub braucht etwas, das einen zwingt, ihn erneut aufzusuchen.
Division durch Null: MIPS übersteht es, Xtensa startet neu
libhzd/near.c dividiert durch eine quadrierte 2D-Länge, die in degenerierten Fällen null sein kann. Der R3000 macht mit einem undefinierten Ergebnis weiter. Xtensa löst IntegerDivideByZero aus, und das Board startet neu. HZD_DIV wurde auf die 7 Divisionen mit Laufzeit-Divisor angewendet. Danach ergaben 80 s Gehen in alle vier Richtungen, das Muster, das früher abstürzte, 0 Panics. In diesem Port braucht jede Division durch einen berechneten Divisor eine Absicherung.
Der 17,6-Minuten-Freeze
psyz’ VSync kürzte sein Ergebnis in jedem Modus auf 16 Bits, aber VSync(-1) muss die 32-Bit-Feldanzahl zurückgeben. Bei 65.536 Feldern (17,6 Minuten bei 60 Hz) lief die mts-Uhr von 64.800 auf 1.064 über, während eine Task auf 65.537 wartete, und sie wartete für immer. Der Fix gibt die vollständige Anzahl für mode < 0 zurück. Er betrifft jedes auf psyz aufbauende Projekt. Bugs, die von verstrichener Zeit abhängen, zeigen sich nie in 60-Sekunden-Tests.
Der Boot, der hängengeblieben aussah
Stundenlang schien der Boot festzustecken. Konamis mts_printf war auf der PSX ein leerer Stub, und mein #define printf mts_printf schickte die gesamte Ausgabe des Spiels dorthin, sodass der Boot still voranschritt. Sobald mts_printf vprintf aufrief, zeigte das Log, dass das Spiel memcard_init() erreicht hatte. Bevor man einen Hänger diagnostiziert, sollte man sicherstellen, dass die Ausgabe irgendwohin geht.
Ein Priority-Deadlock, der ein fehlgeschlagenes malloc war
Der File-Daemon (Task 10) bekam nie CPU-Zeit, und der Trace sah wie ein Priority-Deadlock aus. Zwei echte Fixes (die Semantik von ChangeThFromISR und die VSync(-1)-Uhr) änderten nichts. Dann klärte eine Zeile die Sache: [thread] OpenTh: xTaskCreate failed.
Ich hatte die Stacks auf 32 KB erhöht, FreeRTOS nimmt sie aus dem internen SRAM, und die vierte Task passte nicht hinein. OpenTh gab -1 zurück, und ChangeTh lehnte diese tid für immer ab. Auf diesem SoC sollte man immer den Rückgabewert von xTaskCreate prüfen, selbst wenn Megabyte an PSRAM frei sind.
Schwarzer Bildschirm nach dem Hinzufügen der Cutscene-Daten
Das Kopieren von DEMO.DAT, VOX.DAT und ZMOVIE.STR auf die Karte machte den Bildschirm schwarz: 720 Frames, 0 Panics und null gesendete Primitive.
Der Stage-Wechsel-Code wartet auf GM_StreamStatus() == -1. Der DEMO.DAT-Stream der Cutscene kam nie voran, weil die virtuelle CD Sektor-Reads bedient, aber nicht den kontinuierlichen Ring-Buffer-Streaming-Pfad. Bevor die Dateien existierten, war der Stream früh abgelehnt worden, und alles lief weiter.
Die aktuelle Behandlung:
- Alle Input-Streams werden in
NewStreamControlabgelehnt, indem ihr Callback ausgeführt wird, mit einem 600-Frame-Watchdog als Sicherheitsnetz. Das kostet Cutscenes und Stimmen und ergibt ein Spiel, das spielbar ist. - Die aufgezeichnete Pad-Eingabe einer Cutscene startete sofort, und Snake lief von selbst los. Diese Wiedergabe wird jetzt genauso übersprungen, wie das Spiel sie bei START überspringt.
- FMV wird ebenfalls abgelehnt, weil psyz keinen MDEC-Decoder hat.
Kleinere Bugs
PSX_Wwar 256, übernommen aus dem Code, den ich wiederverwendete. MGS rendert 320 Spalten, also ging ein Fünftel des Bildes verloren. Man sollte jede übernommene Konstante prüfen.- Boot-Race: Der Tick las USB-Serial, bevor der Treiber installiert war, was in 2 von 6 gemessenen Boots zu
LoadProhibitedführte. - Konamis Frame-Dropper: Zwei Actors lasen das Skip-Flag zu unterschiedlichen Zeitpunkten, sodass Puffer ungezeichnet getauscht wurden und der Bildschirm flackerte. Beide Flags werden unter
__psyzauf 0 gezwungen. Schwere Szenen laufen jetzt langsamer, statt zu flackern. - “Kaputte Kollision”: Wandstöße maßen etwa 452 gegen einen Radius von 450, was genau richtig ist. Bei 8 bis 10 fps sieht eine Korrektur von 450 Einheiten einfach wie ein Sprung aus.
Performance
Die Rasterzeit ist ein esp_timer-Zähler im Rasterizer, summiert über 120 Frames an derselben Position.
Der erste Durchlauf war in s07a, einem kleinen Raum. Die gesamte Rasterzeit ging von 923.000 auf 903.900, dann 794.000, dann 741.700 us (7,69 auf 6,18 ms pro Frame). Die drei Schritte:
SOFT_RASTER_IRAMwar im MGS-Build leer, sodass die Per-Pixel-Schleifen aus dem Flash liefen. Es sollteIRAM_ATTRsein. Die Korrektur brachte -2%.- PSRAM und Flash mit 120 MHz brachten -12%. Ich schloss zunächst daraus, dass dieses Board es nicht schaffen kann. Der Fehler “FLASH and PSRAM Mode configuration are not supported” bedeutet nur, dass
CONFIG_IDF_EXPERIMENTAL_FEATURES=yfehlt. PrüfeCONFIG_SPIRAM_SPEED 120in der generiertensdkconfig.h. - Der Scanout lief mit 62,5 Hz für ein 30-fps-Spiel. Die Hälfte der Pushes sendete dasselbe Bild erneut, wobei jeder etwa 120 KB PSRAM las und die Texturen des Rasterizers auf dem anderen Kern verdrängte. Die Angleichung an die Rate des Spiels brachte -6,6%.
Das Dock (s00a) ist deutlich schwerer. Ein Profil dort maß 46.400 texturierte und 71.680 flache Pixel pro Frame: 40,9 ms Rasterisierung plus etwa 25 ms Logik und GTE, was etwa 15 fps entspricht. Die README gibt derzeit etwa 15 fps für das Dock mit Gegnern an. Das Statusdokument gibt 8 bis 15 fps je Szene an, gegen ein Ziel von 30.
Ein 32-Bit-Fast-Path für flache Füllungen brachte nur 2%. Die Kosten liegen bei texturierten Pixeln, bei etwa 207 Zyklen pro Stück. Ein 2D-Spiel läuft auf demselben Rasterizer viel schneller: Eine Tilemap durchläuft Texturen in einer geraden Linie, und eine 64-Byte-Cacheline bedient 128 Pixel. Bei MGS’ rotierten Dreiecken ändern sich U und V beide pro Pixel, und nahezu jedes Pixel ist ein Cache-Miss. Der Datencache ist bereits an seinem Maximum von 64 KB.
Der nächste Schritt ist, heiße Texturseiten in den internen SRAM zu verschieben, was das Statusdokument auf 40-mal schneller schätzt. Dafür müssen die rund 90 KB freigegeben werden, die in überdimensionierten mts-Stacks gefangen sind (24 KB für den großen Task und 6 KB für den Rest). Texturen zu verkleinern ist keine Option, da die UVs in die Modelle eingebacken sind.
Das Laden ist ebenfalls langsam: etwa 11,5 s für 1,1 MB von der Karte (grob 95 KB/s).
- Ein Burst von 128 statt 16 Sektoren brachte nur 7%.
- Die Karte ist bei 20 MHz auf dem Waveshare-Board zuverlässig. Bei 40 MHz liefert sie CRC-Fehler.
- Das Überspringen redundanter
fseek-Aufrufe ist umgesetzt, aber noch nicht gemessen.
Das Handheld zum Laufen bringen

Das Handheld besteht aus:
- Einem XIAO ESP32S3 Sense, dessen Erweiterungsboard den microSD-Slot bereitstellt.
- Einem ILI9341-SPI-Panel.
- Einem Drohnencontroller-Gimbal.
- 8 Tasten: 6 auf einer Widerstandsleiter an einem ADC-Pin, plus Feuer und Zielen an eigenen Pins, weil eine Leiter nur jeweils eine Taste registriert.

Alle 11 XIAO-Pins werden verwendet. Die Verkabelung ist im Hardware-Leitfaden dokumentiert. Notizen zum Bring-up:
- Die fehlende Masse. Das Panel leuchtete weiß und änderte die Helligkeit, wenn Daten gesendet wurden, weil es sich über die Schutzioden an seinen Eingängen selbst mit Strom versorgte. Zuvor schloss die Messung die Verkabelung, den Reset-Puls, die Versorgungsspannung und das SPI-Setup aus. Ein Bug von mir kostete ebenfalls zwei Runden: Ein skriptgesteuerter Edit, der
lcd_bus_init()einfügen sollte, schlug stillschweigend fehl, und das Panel wurde umsonst neu gelötet. - ILI9341, nicht ILI9488. Der Plan ging von einem 480x320 ILI9488 aus, der über SPI nur 3-Byte-RGB666 akzeptiert. Ein früheres Projekt von mir mit demselben Panel zeigte, dass es ein ILI9341 mit 320x240 ist. Das war besser als geplant: native Auflösung, keine Skalierung, 2 Bytes pro Pixel. Die Farbreihenfolge wurde mit drei beschrifteten R/G/B-Streifen auf einmal geprüft.
- RST an einem echten Pin. Mit RESET an 3V3 und nur einem Software-Reset startete der ILI9341 nicht zuverlässig, also wanderte RST nach D4. D4 war frei, weil das CS der Karte GPIO21 ist, intern auf dem Sense-Board. Eine Websuche hatte falsche SD-Pins geliefert. Der Fehler war
ESP_ERR_INVALID_ARG, ein Konfigurationsfehler statt eines Kartenfehlers, was auf Seeeds offizielle Dokumentation hinwies. - Tasten und Potis. Verkable 4-Bein-Schalter an diagonalen Beinen, sonst liest sich eine Taste als dauerhaft gedrückt. Zu den Potis:
- Ein Messwert, der bei 0 oder 4095 festhängt, bedeutet, dass das Kabel an einem äußeren Bein liegt.
- Ein Messwert, der in der Mitte hängen bleibt, bedeutet, dass dem Poti 3V3/GND fehlt.
- Ein weiter Bereich bedeutet, dass die Achse gesund ist.
- Stick-Kalibrierung. Das Gimbal ruht bei 2317, nicht bei 2048, und X wandert von 141 bis 2888.
- Die Mitte ist der Ruhewert beim Booten, und jede Hälfte wird mit dem in dieser Richtung beobachteten Weg skaliert.
- Die Deadzone beträgt 60 Counts (etwa 4x das gemessene Rauschen von +/-15), auf beiden Seiten abgezogen, damit die Bewegung sanft beginnt.
- Jede Achse mittelt 8 Messwerte, und beide Achsen sind in Software invertiert.
- Ein seit dem Booten akkumuliertes Min/Max ist hier nutzlos, weil ein floatender Eingang beim Einschalten 0 und 4095 berührt. Verwende ein gleitendes Fenster.
- ADC-Messungen im Vblank-Tick froren alles ein. 24 Konvertierungen pro Tick blockierten den Tick und jeden mts-Task. Die Warnung stand bereits in
esp_input.c. Ein Task auf Kern 1 tastet jetzt alle 10 ms ab und veröffentlicht drei Integer. printfüber natives USB blockiert, wenn kein Host es abnimmt (UART nicht). MGS gibt viel aus, sodass ein blockierter Print den kooperativen Scheduler anhielt.port/mgs_printf.hschreibt mit einem Timeout von null.- Taktpaare. PSRAM mit 120 MHz und Flash mit 80 MHz ist kein unterstütztes MSPI-Paar, und der Fehler sieht wie ein Toolchain-Bug aus. Der XIAO läuft vorerst mit 80/80, und 120/120 ist das Nächste, was gemessen wird.
- Panel-SPI. Mit Jumper-Kabeln ist das Panel bei 40 MHz stabil. Bei 80 MHz verrutschen Bildbänder seitwärts.
MGS bootet jetzt auf dem Handheld, mountet die Karte, lädt das Dock und spielt ohne Panics, mit einer Framerate, die die README als ähnlich zum Waveshare-Board beschreibt.
Was noch nicht funktioniert
- Codec-Anrufe. Die 417.792-Byte-Face-Gruppe lädt jetzt aus einer statischen PSRAM-Reserve, weil der Pool des Spiels die Allokation verweigert. Der
RADIO.DAT-Index ist immer noch falsch: Der berechnete Startsektor ist 31.392, und die Datei hat 867 Sektoren. Der Eingabewert ist schlecht; die Arithmetik ist in Ordnung. Das Aktivieren des echten Codec-Bildschirms führt außerdem zu einem Panic innerhalb einesprintf. - Das Intro. Das Booten durch den Titelbildschirm ergab 11 Panics. Die letzte Zeile vor dem ersten war
this memcard is OK. Das Einschwimmen und das Briefing benötigen die Speicherkarte, CD-Streaming und den Codec. - Der Aufzug. Sonden in beiden Aufzugs-Konstruktoren bleiben eine ganze Sitzung lang stumm, sodass das Stage-Skript ihn nie anfordert. Der wahrscheinliche, noch nicht bewiesene Grund ist eine Story-Variable, die nur ein Codec-Anruf voranbringt.
- CD-Streaming (Zwischensequenzen, Stimmen), FMV (kein MDEC), Audio und Speicherkarten-Speicherstände.
- 28 Stages, deren Actor-Code noch MIPS-Assembly ist.
- Performance jenseits von etwa 15 fps.
Nächste Schritte
- Die mts-Stacks richtig dimensionieren und heiße Texturseiten in den internen SRAM verschieben.
- 120/120-MHz-Speichertaktraten auf dem XIAO messen.
- Den
RADIO.DAT-Index reparieren und dann prüfen, ob der Aufzug folgt. - Streaming in der virtuellen CD implementieren, um Zwischensequenzen und Stimmen zurückzubekommen.
- Audio über einen Software-SPU hinzufügen.
- Die Debug-Sonden entfernen.
Fazit
Eine PlayStation toleriert Type-Punning, Division durch null, Reads über Arrays hinaus und vorzeichengeprüfte Pointer. Ein moderner Compiler und eine moderne CPU tolerieren nichts davon. Der Ansatz, der bei diesem Port funktionierte, war, jede Messung so zu gestalten, dass sie fehlschlagen kann.