Volver

Metal Gear Solid ejecutándose de forma nativa en el ESP32-S3

La consola portátil XIAO ESP32S3 ejecutando Metal Gear Solid en la base, con el radar en la esquina superior derecha

Me ha encantado Metal Gear Solid desde que era un crío. Cuando conseguí una placa ESP32-S3 diminuta, se me quedó grabada una pregunta: ¿podría un juego de PlayStation ejecutarse en algo tan pequeño?

La Seeed Studio XIAO ESP32S3 Sense: 21 × 17,8 × 15 mm con su placa de cámara acoplada (foto: Seeed Studio)

La placa es la Seeed Studio XIAO ESP32S3 Sense: un ESP32-S3 de doble núcleo con 8 MB de PSRAM y 8 MB de flash, en un módulo de 21 × 17,8 mm. La versión Sense añade una placa de expansión con cámara y una ranura microSD, y esa ranura microSD es donde viven los datos del juego.

Tardé un buen rato en averiguarlo. Primero busqué una versión del juego que ya se hubiera reconstruido como código C que se ejecutara en un PC, y luego comprobé si toda esa lógica cabría en la flash del ESP32-S3 y en una tarjeta microSD. Hicieron falta varios intentos, pero al final funcionó. Un juego maravilloso se ejecuta ahora en una placa de microcontrolador que cuesta unos 15 USD.

Jugabilidad en la consola portátil: míralo en YouTube.

En este artículo describo cómo Metal Gear Solid (PlayStation, 1998) se ejecuta en el ESP32-S3 como un port nativo. El código fuente en C del juego, reconstruido por la descompilación mgs_reversing del FoxdieTeam, se compila directamente a código máquina Xtensa. Todo lo que antes proporcionaba el hardware de PlayStation se sustituye por software:

El artículo cubre el hardware, la capa de plataforma, la ubicación de la memoria, el método de depuración, los errores que más importaron, el rendimiento, la consola portátil y lo que aún no funciona.

El código y los proyectos relacionados:

Necesitas tu propio disco. El repositorio no contiene nada derivado del juego, y port/extract_disc.py extrae los archivos de tu propia imagen de disco.

Hardware

Jugando a Metal Gear Solid en la consola portátil sobre la base

El ESP32-S3 tiene dos núcleos Xtensa a 240 MHz y 512 KB de SRAM interna. Ambas placas usadas aquí también tienen 8 MB de PSRAM, que se sitúa detrás de la misma caché que la flash.

Waveshare ESP32-S3-Touch-LCD-2Consola portátil casera (Seeed XIAO ESP32S3 Sense)
PanelST7789, 320x240ILI9341, 320x240 nativo
Flash16 MB8 MB
Datos del juegomicroSD, o un STAGE.DIR recortado en la flashmicroSD (STAGE.DIR completo)
Entradateclado por puerto serie (play.py)stick de gimbal de dron, escalera de resistencias de 6 botones, 2 botones directos

Medir la distancia antes de escribir código

Antes de escribir cualquier código del port, medí a qué distancia estaba la descompilación de compilar para Xtensa:

Dejé el único archivo que fallaba, libdg/chanl.c, fallando a propósito. El cast que lo habría silenciado también habría cambiado el stride en silencio (véase la sección de la tabla de ordenación más abajo).

El resto requirió pasadas mecánicas, cada una arreglando toda una clase de problema:

El resultado fue 497 de 497 archivos C compilados a Xtensa. El ELF tenía 0 referencias sin definir y 0 definiciones duplicadas (text 987.073 B, bss 2.434.276 B). La memoria propia del juego es de 804 KiB (428 KiB de heap más dos búferes de paquetes de 188 KiB), que cabe holgadamente en la PSRAM.

Arquitectura

El port tiene tres capas entre el juego y el SoC:

Las tres capas del port y los dos núcleos — todas las tareas de mts y el tick de vblank en el núcleo 0, el escaneo del LCD en el núcleo 1, y el LCD y la microSD compartiendo SPI2

Las capas, desde el juego hasta el hardware:

  1. Motor de MGS — C descompilado, compilado a Xtensa
  2. psyz — SDK de PlayStation y GTE en C, rasterizador por software
  3. Capa de plataforma — planificador de mts sobre FreeRTOS, tick de vblank, CD virtual, LCD, entrada
  4. ESP32-S3

psyz y el GTE

psyz, la reimplementación del SDK de PlayStation de Xeeynamo, ya modelaba todo el fichero de registros del GTE y cada operación del GTE en C, validado contra la suite de pruebas del GTE de PCSX-Redux.

Mi primera estimación fue que faltaban entre 64 y 70 macros. Esa estimación era demasiado alta. MGS incluye sus propias cabeceras de ensamblador en línea de MIPS (inline_n.h, inline_x.h), y -fsyntax-only no comprueba los nombres de los registros. Una vez que esas cabeceras se redirigieron a psyz, la brecha real era de 41 macros. Las añadí a psyz, usando el propio ensamblador del juego como especificación de qué registros COP2 toca cada una. Después recompilé mis otros proyectos basados en psyz contra el psyz modificado para asegurarme de que nada se rompía.

Cuando alias una macro del GTE, comprueba si cada restricción es una entrada o una salida. Por ejemplo, gte_read_opz tiene una salida "=r", así que su alias tiene que tomar &x.

La etiqueta de la tabla de ordenación — una palabra en PSX, dos en psyz

Esta es la diferencia de diseño más importante, y la que causó más errores. En la PlayStation, cada primitiva empieza con una etiqueta de 32 bits — 24 bits de dirección de la siguiente primitiva y 8 bits de longitud. Un puntero del host no cabe en 24 bits, así que psyz usa dos palabras, tag y len. Cada primitiva crece 4 bytes, y cada campo después de la etiqueta se desplaza una palabra.

MGS también abusa del byte de longitud. libdg ejecuta una ordenación radix de dos pasadas sobre la profundidad de 16 bits:

  1. divide.c agrupa por el byte bajo y aparca el byte alto en la longitud de la etiqueta.
  2. sort.c reagrupa por ese byte alto y escribe la longitud real.

Como psyz separa los dos campos, la traducción es exacta:

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

Reescribir 42 declaraciones locales y 100 parámetros a OT_TYPE* fue la parte fácil. La parte difícil fue el código que asumía el diseño empaquetado sin decirlo:

También hay un factor agravante. En la consola, addPrim() reescribía toda la palabra de la etiqueta en cada inserción, así que una longitud olvidada nunca podía notarse. En psyz, una longitud que nunca se estableció simplemente nunca se escribe.

El planificador de Konami dentro de FreeRTOS

MGS se ejecuta sobre el propio planificador cooperativo de Konami. El banner de arranque todavía dice Multi Task Scheduler for PSX ver2.02 Jul 11 1998. Se apoya en la API de hilos de la BIOS (OpenTh/ChangeTh) y usa la interrupción de vblank para despertar tareas cuyos temporizadores han expirado.

En el port, cada hilo de mts es una tarea de FreeRTOS, y solo una de ellas es ejecutable en un momento dado. El diseño final:

mts_GetTcbEntry también leía la tabla de tablas de la BIOS en la dirección fija 0x100 y escribía a través del resultado. Fuera de una PSX esa dirección contiene basura, así que ahora usa una tabla de TCB privada.

El tick de vblank y los dos relojes

port/esp32_vblank.c dispara la llamada de retorno de VSync del juego cada 16 ms. Eso requería que VSyncCallback() estuviera implementada en psyz, donde ni siquiera almacenaba el puntero.

VSync(-1) tiene que devolver un contador de vblank de ejecución libre. La primera versión devolvía el número de fotogramas presentados, que deja de avanzar cuando no se dibuja nada, así que ningún temporizador expiraba jamás.

La tasa de fotogramas varía — 2 vblanks por fotograma en un pasillo, 4 o 5 en una sala abierta. Por eso, dos cosas que parecían cosa de vblank en realidad pertenecen al fotograma del juego:

Ubicación de la memoria

Dónde vive todo — pilas de tareas y bucles calientes en SRAM interna, el mapa de RAM del juego y el 1 MB de VRAM en PSRAM, el firmware en flash, y STAGE.DIR en la microSD

La SRAM interna es escasa y rápida. La PSRAM es abundante y lenta. Las lecturas de flash deshabilitan la caché de la que también depende la PSRAM.

Hay una clase de error que solo existe en este mapa de memoria — comprobaciones de punteros basadas en el bit de signo. MGS distingue un puntero a bloque de script de un id de proc de 16 bits con proc_id < 0. La RAM de la PSX está en 0x8xxxxxxx, que es negativa como valor con signo. La PSRAM está en 0x3Cxxxxxx, que es positiva. El resultado era PROC 3C1987D2 NOT FOUND, seguido de un LoadProhibited en EXCVADDR 0x00000003. Una macro GCL_IS_BLOCK_PTR arregla el sitio que se vio afectado. Otros sitios con el mismo patrón todavía necesitan una auditoría.

Un CD virtual sobre FAT

El CD virtual — libfs pide un sector absoluto, virtual_cd.c lo convierte en un fichero y un desplazamiento en la microSD y devuelve un sector cada vez

libfs trabaja en sectores absolutos. Lee el directorio ISO9660 una vez y nunca vuelve a usar un nombre de fichero. port/virtual_cd.c sustituye a la BIOS del CD:

Los datos vivían primero en PSRAM, lo que limitaba el juego a un puñado de escenarios. La solución real fue la microSD. La tarjeta es un periférico SPI, separado de la flash XIP, así que leerla no deshabilita la caché de instrucciones. Los ficheros se quedan en la tarjeta y no cuestan PSRAM.

La tarjeta y el LCD comparten SPI2, y ESP-IDF no arbitra entre ellos. Un fotograma del LCD son 30 transferencias asíncronas en cola, así que una lectura de tarjeta en medio de un fotograma disparaba assert failed: spi_hal_iram.c:134 y causaba un bucle de reinicio. La solución es una propiedad explícita del bus (Mgs_SpiBusTake/Give), drenando las transferencias en vuelo antes de liberar el bus.

Método: medir, no adivinar

Alrededor de un tercio de las explicaciones obvias de este proyecto resultaron ser erróneas. Lo que funcionó fue conseguir que la placa imprimiera un número que decidiera entre hipótesis. Las lecciones más útiles vinieron de sondas que dieron respuestas equivocadas:

Ejecutar cada build sin grabar la placa

Ese método solo funciona si probar algo es barato, y tras varias horas de prueba y error, grabar la placa después de cada cambio no lo era: escribir la imagen en la XIAO por USB, esperar al reinicio, leer el log serie y vuelta a empezar. Así que para ejecutar y comprobar cada build usé velxio-cli, el cliente de línea de comandos de Velxio. Toma el mismo .bin que genera mi toolchain, lo ejecuta en el ESP32-S3 simulado de Velxio durante un tiempo simulado fijo y devuelve la salida serie, así que podía leer las sondas de arriba sin tocar el hardware. La placa solo recibía una imagen nueva cuando un build lo merecía.

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

Instalarlo y hacer una primera ejecución lleva unos minutos: mira la guía rápida de velxio-cli.

Los errores

En el juego en la consola portátil, con el radar en la esquina superior derecha

El aliasing estricto eliminó una rotación

La pantalla blanca: cinco hipótesis erróneas, tres causas reales

La regla de tamaño de la GPU: un polígono fijado en el límite de saturación de -1024 del GTE se adentra en la pantalla de 320x240; la GPU de PlayStation rechaza cualquier cosa mayor de 1023x511, el rasterizador software lo dibujaba

El arreglo de culling de la hipótesis 4 era real, aunque no fuera la causa. La prueba de bounding-box trataba una caja que cruza el plano cercano igual que una completamente detrás de él. Separar los dos casos llevó kept-saturated de 16.090 a 4.947. Un intento anterior basado en coordenadas saturadas rescataba el 97% de todo lo que la prueba de pantalla rechazaba (+40% de rasterización), porque una pared grande y lejana también satura. Preguntar directamente por Z (SZ <= H/2) daba 1.440 en lugar de 15.000.

Square0 desplazado 12 bits: todas las distancias /64

Snake daba tres pasos, chocaba con una pared, rebotaba y nunca avanzaba. La tasa de fotogramas fue el primer sospechoso. Una observación lo descartó: el mundo se movía bien y solo el jugador no. Una sonda en GM_ActControl mostró un paso de +4481 seguido de un rebote de -14641.

En PSY-Q el sufijo numérico es el desplazamiento: Square0 no desplaza y Square12 sí. El Square0 del port desplazaba 12, así que toda longitud Square0 -> sum -> sqrt salía /64. Eso rompía:

Eliminar el desplazamiento hizo que la trayectoria fuera monótona.

Cinco opcodes del GTE copiados de la fila equivocada

Snake se había caído del mundo (Y = -3250), el movimiento estaba fijado en 0,1 por fotograma, y el muelle no tenía agua. Los Psyz_GteRtv0/Rtv1/Rtv2/Ll/Llv0 de psyz usaban opcodes MVMVA de la fila equivocada de la propia tabla inline_n.h de MGS. “Rotar este vector” se convertía en “rotarlo y sumar la traslación obsoleta”, y la iluminación usaba la matriz de rotación en lugar de la matriz de luz.

Tras el arreglo:

El muelle vacío era un script de dos pasadas

El muelle solo tenía un puñado de grupos de objetos, y el script parecía ejecutar un solo comando. La estructura real de s00a es if (var[5] < 6) { set up the Colonel's call } else { build the dock }, y el proc de la llamada es un restart. El mundo se construye en la segunda pasada, y responder al códec la dispara.

Yo mismo había enmascarado el códec para evitar un crash, y eso desactivó todos los radio -c ... -p proc en todas las fases. MENU_RadioDrainHeadless ahora responde a la llamada y despacha su proc sin abrir la pantalla del códec. Los grupos de objetos pasaron de 480 a 3.240 por cada 120 fotogramas, y se creó el área del agua. La lección: un stub temporal necesita algo que te obligue a revisitarlo.

División por cero: MIPS la sobrevive, Xtensa se reinicia

libhzd/near.c divide por una longitud 2D al cuadrado que puede ser cero en casos degenerados. El R3000 continúa con un resultado indefinido. Xtensa lanza IntegerDivideByZero y la placa se reinicia. Se aplicó HZD_DIV a las 7 divisiones con divisor en tiempo de ejecución. Después de eso, 80 s caminando en las cuatro direcciones, el patrón que solía provocar el crash, dieron 0 pánicos. En este port, toda división por un divisor calculado necesita una guarda.

El congelamiento de 17,6 minutos

El VSync de psyz truncaba su resultado a 16 bits en todos los modos, pero VSync(-1) debe devolver el contador de campos de 32 bits. A los 65.536 campos (17,6 minutos a 60 Hz), el reloj de mts daba la vuelta de 64.800 a 1.064 mientras una tarea esperaba 65.537, y esperaba para siempre. El arreglo devuelve el contador completo para mode < 0. Afecta a todos los proyectos construidos sobre psyz. Los errores que dependen del tiempo transcurrido nunca aparecen en pruebas de 60 segundos.

El arranque que parecía colgado

Durante horas el arranque parecía atascado. El mts_printf de Konami era un stub vacío en la PSX, y mi #define printf mts_printf enviaba toda la salida del juego ahí, así que el arranque progresaba en silencio. Una vez que mts_printf llamó a vprintf, el log mostró que el juego había llegado a memcard_init(). Antes de diagnosticar un cuelgue, asegúrate de que la salida va a algún sitio.

Un deadlock de prioridades que era un malloc fallido

El daemon de ficheros (tarea 10) nunca obtenía tiempo de CPU, y la traza parecía un deadlock de prioridades. Dos arreglos reales (la semántica de ChangeThFromISR y el reloj de VSync(-1)) no cambiaron nada. Entonces una línea lo resolvió: [thread] OpenTh: xTaskCreate failed.

Había subido las pilas a 32 KB, FreeRTOS las toma de la SRAM interna, y la cuarta tarea no cabía. OpenTh devolvía -1, y ChangeTh rechazaba ese tid para siempre. En este SoC, comprueba siempre el valor de retorno de xTaskCreate, incluso con megabytes de PSRAM libres.

Pantalla negra tras añadir los datos de las cinemáticas

Copiar DEMO.DAT, VOX.DAT y ZMOVIE.STR a la tarjeta puso la pantalla en negro: 720 fotogramas, 0 pánicos, y cero primitivas enviadas.

El código de cambio de fase espera a GM_StreamStatus() == -1. El stream de DEMO.DAT de la cinemática nunca avanzaba, porque el CD virtual sirve lecturas por sector pero no la ruta de streaming continuo con ring-buffer. Antes de que existieran los ficheros, el stream se había rechazado pronto y todo seguía funcionando.

El manejo actual:

Errores menores

Rendimiento

El tiempo de rasterizado es un contador de esp_timer en el rasterizador, sumado a lo largo de 120 fotogramas en la misma posición.

La primera pasada fue en s07a, una sala pequeña. El tiempo total de rasterizado pasó de 923.000 a 903.900, luego a 794.000 y después a 741.700 us (de 7,69 a 6,18 ms por fotograma). Los tres pasos:

  1. SOFT_RASTER_IRAM estaba vacío en la compilación de MGS, así que los bucles por píxel se ejecutaban desde la flash. Debería ser IRAM_ATTR. Corregirlo dio un -2%.
  2. PSRAM y flash a 120 MHz dieron un -12%. Primero concluí que esta placa no podía con ello. El error “FLASH and PSRAM Mode configuration are not supported” solo significa que falta CONFIG_IDF_EXPERIMENTAL_FEATURES=y. Comprueba CONFIG_SPIRAM_SPEED 120 en el sdkconfig.h generado.
  3. El scanout funcionaba a 62,5 Hz para un juego a 30 fps. La mitad de los envíos reenviaban la misma imagen, y cada uno leía unos 120 KB de PSRAM y desalojaba las texturas del rasterizador en el otro núcleo. Igualar la tasa del juego dio un -6,6%.

Tiempo de fotograma: el rasterizado en s07a bajando de 7,69 a 6,18 ms en tres pasos, y un fotograma del muelle de 40,9 ms de rasterizado más unos 25 ms de lógica, unos 15 fps frente a un objetivo de 33,3 ms

El muelle (s00a) es mucho más pesado. Un perfil allí midió 46.400 píxeles texturizados y 71.680 planos por fotograma: 40,9 ms de rasterizado más unos 25 ms de lógica y GTE, lo que supone unos 15 fps. El README indica actualmente unos 15 fps para el muelle con enemigos. El documento de estado da entre 8 y 15 fps según la escena, frente a un objetivo de 30.

Una ruta rápida de 32 bits para rellenos planos solo ganó un 2%. El coste está en los píxeles texturizados, a unos 207 ciclos cada uno. Un juego 2D se ejecuta mucho más rápido en el mismo rasterizador: un tilemap recorre las texturas en línea recta, y una sola línea de caché de 64 bytes sirve 128 píxeles. En los triángulos rotados de MGS, tanto U como V cambian por píxel, y casi todos los píxeles son un fallo de caché. La caché de datos ya está en su máximo de 64 KB.

El siguiente paso es mover las páginas de textura activas a la SRAM interna, lo que el documento de estado estima en 40 veces más rápido. Eso requiere los aproximadamente 90 KB atrapados en pilas mts sobredimensionadas (24 KB para la tarea grande y 6 KB para el resto). Reducir las texturas no es una opción, porque las UV están integradas en los modelos.

La carga también es lenta: unos 11,5 s para 1,1 MB desde la tarjeta (aproximadamente 95 KB/s).

Poniendo en marcha la consola portátil

Cableado de la consola portátil: el XIAO ESP32S3 Sense, el panel ILI9341, el joystick analógico en D0/D1, una escalera de resistencias de seis botones en D2 y dos botones directos en D5/D7

La consola portátil ensamblada sobre placa perforada: el joystick analógico a la izquierda, las resistencias de la escalera de botones en el centro y el XIAO abajo

La consola portátil está construida con:

Lo que viene en la caja del XIAO ESP32S3 Sense: la placa con su cámara, una antena Wi-Fi, pines de cabecera y disipadores (foto: Seeed Studio)

Se usan los 11 pines del XIAO. El cableado está documentado en la guía de hardware. Notas de puesta en marcha:

MGS ahora arranca en la consola portátil, monta la tarjeta, carga el muelle y se juega sin pánicos, a una tasa de fotogramas que el README describe como similar a la de la placa Waveshare.

Lo que aún no funciona

Próximos pasos

  1. Dimensionar correctamente las pilas mts y mover las páginas de textura activas a la SRAM interna.
  2. Medir los relojes de memoria a 120/120 MHz en el XIAO.
  3. Arreglar el índice de RADIO.DAT y luego comprobar si el ascensor va detrás.
  4. Implementar el streaming en el CD virtual, para recuperar las cinemáticas y las voces.
  5. Añadir audio mediante una SPU por software.
  6. Eliminar las sondas de depuración.

Conclusión

Una PlayStation tolera el type punning, la división por cero, las lecturas más allá de los arrays y los punteros con prueba de signo. Un compilador y una CPU modernos no toleran nada de eso. El enfoque que funcionó en este port fue diseñar cada medición de modo que pueda fallar.


Compartir en:
David Montero

Escrito por

David Montero

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

GitHub velxio.dev

Artículos relacionados


Artículo anterior
Castlevania: Symphony of the Night ejecutándose de forma nativa en el ESP32-S3
Artículo siguiente
222 módulos Seeed Grove ya funcionan en el navegador