Voltar

Metal Gear Solid rodando nativamente no ESP32-S3

O portátil XIAO ESP32S3 rodando Metal Gear Solid na dock, com o radar no canto superior direito

Eu amo Metal Gear Solid desde criança. Quando consegui uma placa ESP32-S3 minúscula, uma pergunta ficou na minha cabeça: será que um jogo de PlayStation poderia rodar em algo tão pequeno?

O Seeed Studio XIAO ESP32S3 Sense: 21 × 17,8 × 15 mm com sua placa de câmera acoplada (foto: Seeed Studio)

A placa é a Seeed Studio XIAO ESP32S3 Sense: um ESP32-S3 dual-core com 8 MB de PSRAM e 8 MB de flash, em um módulo de 21 × 17,8 mm. A versão Sense adiciona uma placa de expansão com câmera e um slot de microSD, e é nesse slot de microSD que os dados do jogo ficam.

Passei um bom tempo descobrindo. Primeiro procurei uma versão do jogo que já tivesse sido reconstruída como código C que roda em um PC, e depois verifiquei se toda aquela lógica caberia na flash do ESP32-S3 e em um cartão microSD. Foram várias tentativas, mas no final deu certo. Um jogo maravilhoso agora roda em uma placa de microcontrolador que custa cerca de 15 dólares.

Gameplay no portátil: assista no YouTube.

Neste artigo, descrevo como Metal Gear Solid (PlayStation, 1998) roda no ESP32-S3 como um port nativo. O código-fonte C do jogo, reconstruído pela decompilação mgs_reversing da FoxdieTeam, é compilado diretamente para código de máquina Xtensa. Tudo o que o hardware do PlayStation costumava fornecer é substituído por software:

O artigo aborda o hardware, a camada de plataforma, o posicionamento de memória, o método de depuração, os bugs que mais importaram, o desempenho, o portátil e o que ainda não funciona.

O código e os projetos relacionados:

Você precisa do seu próprio disco. O repositório não contém nada derivado do jogo, e port/extract_disc.py extrai os arquivos da sua própria imagem de disco.

Hardware

Jogando Metal Gear Solid no portátil na dock

O ESP32-S3 tem dois núcleos Xtensa a 240 MHz e 512 KB de SRAM interna. Ambas as placas usadas aqui também têm 8 MB de PSRAM, que fica atrás do mesmo cache que a flash.

Waveshare ESP32-S3-Touch-LCD-2Portátil DIY (Seeed XIAO ESP32S3 Sense)
PainelST7789, 320x240ILI9341, 320x240 nativo
Flash16 MB8 MB
Dados do jogomicroSD, ou um STAGE.DIR reduzido na flashmicroSD (STAGE.DIR completo)
Entradateclado via serial (play.py)stick de gimbal de drone, escada de resistores de 6 botões, 2 botões diretos

Medindo a lacuna antes de escrever código

Antes de escrever qualquer código de port, medi o quão longe a decompilação estava de compilar para Xtensa:

Deixei o único arquivo que falhava, libdg/chanl.c, falhando de propósito. O cast que teria silenciado o erro também teria alterado silenciosamente o stride (veja a seção sobre a tabela de ordenação abaixo).

O resto exigiu passagens mecânicas, cada uma corrigindo uma classe inteira de problema:

O resultado foi 497 de 497 arquivos C compilados para Xtensa. O ELF tinha 0 referências indefinidas e 0 definições duplicadas (text 987.073 B, bss 2.434.276 B). A memória do próprio jogo é de 804 KiB (428 KiB de heap mais dois buffers de pacote de 188 KiB), o que cabe confortavelmente na PSRAM.

----- END POST -----

Arquitetura

O porte tem três camadas entre o jogo e o SoC:

As três camadas do porte e os dois núcleos: todas as tarefas mts e o tick de vblank no núcleo 0, a varredura do LCD no núcleo 1, e o LCD e o microSD compartilhando o SPI2

As camadas, do jogo até o hardware:

  1. Motor do MGS: C descompilado, compilado para Xtensa
  2. psyz: SDK do PlayStation e GTE em C, rasterizador por software
  3. Camada de plataforma: escalonador mts sobre FreeRTOS, tick de vblank, CD virtual, LCD, entrada
  4. ESP32-S3

psyz e o GTE

O psyz, a reimplementação do SDK do PlayStation feita pelo Xeeynamo, já modelava todo o arquivo de registradores do GTE e cada operação do GTE em C, validado contra a suíte de testes do GTE do PCSX-Redux.

Minha primeira estimativa foi de que faltavam de 64 a 70 macros. Essa estimativa era alta demais. O MGS traz seus próprios cabeçalhos de assembly inline de MIPS (inline_n.h, inline_x.h), e -fsyntax-only não verifica nomes de registradores. Depois que esses cabeçalhos foram desviados para o psyz, a lacuna real era de 41 macros. Eu as adicionei ao psyz, usando o próprio assembly do jogo como especificação de quais registradores COP2 cada uma toca. Em seguida, recompilei meus outros projetos baseados no psyz contra o psyz modificado para garantir que nada quebrasse.

Quando você cria um alias para uma macro do GTE, verifique se cada restrição é uma entrada ou uma saída. Por exemplo, gte_read_opz tem uma saída "=r", então seu alias precisa receber &x.

A tag da tabela de ordenação: uma palavra no PSX, duas no psyz

Esta é a diferença de layout mais importante, e foi a que causou mais bugs. No PlayStation, toda primitiva começa com uma tag de 32 bits: 24 bits de endereço da próxima primitiva e 8 bits de comprimento. Um ponteiro de host não cabe em 24 bits, então o psyz usa duas palavras, tag e len. Toda primitiva cresce 4 bytes, e todo campo após a tag se desloca uma palavra.

O MGS também abusa do byte de comprimento. O libdg executa uma ordenação radix de duas passagens sobre a profundidade de 16 bits:

  1. divide.c distribui em baldes pelo byte baixo e guarda o byte alto no comprimento da tag.
  2. sort.c redistribui em baldes por esse byte alto e escreve o comprimento real.

Como o psyz separa os dois campos, a tradução é exata:

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

Redigitar 42 declarações locais e 100 parâmetros para OT_TYPE* foi a parte fácil. A parte difícil foi o código que assumia o layout empacotado sem dizer isso:

Há também um fator agravante. No console, addPrim() reescrevia a palavra da tag inteira a cada inserção, então um comprimento esquecido nunca poderia ser notado. No psyz, um comprimento que nunca foi definido simplesmente nunca é escrito.

O escalonador da Konami dentro do FreeRTOS

O MGS roda sobre o escalonador cooperativo da própria Konami. O banner de boot ainda exibe Multi Task Scheduler for PSX ver2.02 Jul 11 1998. Ele fica sobre a API de threads da BIOS (OpenTh/ChangeTh) e usa a interrupção de vblank para acordar tarefas cujos temporizadores expiraram.

No porte, cada thread mts é uma tarefa do FreeRTOS, e apenas uma delas é executável por vez. O design final:

mts_GetTcbEntry também lia a tabela de tabelas da BIOS no endereço fixo 0x100 e escrevia através do resultado. Fora de um PSX esse endereço contém lixo, então agora ele usa uma tabela de TCB privada.

O tick de vblank e os dois relógios

port/esp32_vblank.c dispara o callback de VSync do jogo a cada 16 ms. Isso exigiu que VSyncCallback() fosse implementado no psyz, onde ele nem sequer armazenava o ponteiro.

VSync(-1) precisa retornar uma contagem de vblank de execução livre. A primeira versão retornava o número de quadros apresentados, que para de avançar quando nada é desenhado, então nenhum temporizador jamais expirava.

A taxa de quadros varia: 2 vblanks por quadro em um corredor, 4 a 5 em uma sala aberta. Por causa disso, duas coisas que pareciam ser assunto de vblank na verdade pertencem ao quadro do jogo:

Posicionamento de memória

Onde tudo vive: pilhas de tarefas e loops quentes na SRAM interna, o mapa de RAM do jogo e a VRAM de 1 MB na PSRAM, o firmware na flash, e o STAGE.DIR no microSD

A SRAM interna é escassa e rápida. A PSRAM é abundante e lenta. Leituras da flash desabilitam o cache do qual a PSRAM também depende.

Uma classe de bug só existe neste mapa de memória: testes de ponteiro baseados no bit de sinal. O MGS distingue um ponteiro de bloco de script de um id de proc de 16 bits com proc_id < 0. A RAM do PSX fica em 0x8xxxxxxx, que é negativo como valor com sinal. A PSRAM fica em 0x3Cxxxxxx, que é positivo. O resultado foi PROC 3C1987D2 NOT FOUND, seguido de um LoadProhibited em EXCVADDR 0x00000003. Uma macro GCL_IS_BLOCK_PTR corrige o local que foi atingido. Outros locais com o mesmo padrão ainda precisam de auditoria.

Um CD virtual sobre FAT

O CD virtual: o libfs pede um setor absoluto, virtual_cd.c o transforma em um arquivo e um deslocamento no microSD e devolve um setor por vez

O libfs trabalha em setores absolutos. Ele lê o diretório ISO9660 uma vez e nunca mais usa um nome de arquivo. port/virtual_cd.c substitui a BIOS do CD:

Os dados primeiro viviam na PSRAM, o que limitava o jogo a um punhado de estágios. A correção real foi o microSD. O cartão é um periférico SPI, separado da flash XIP, então lê-lo não desabilita o cache de instruções. Os arquivos ficam no cartão e não custam PSRAM.

O cartão e o LCD compartilham o SPI2, e o ESP-IDF não arbitra entre eles. Um quadro do LCD são 30 transferências assíncronas enfileiradas, então uma leitura do cartão no meio de um quadro disparava assert failed: spi_hal_iram.c:134 e causava um loop de reinicialização. A correção é a posse explícita do barramento (Mgs_SpiBusTake/Give), drenando transferências em andamento antes de liberar o barramento.

Método: meça, não adivinhe

Cerca de um terço das explicações óbvias neste projeto acabaram se revelando erradas. O que funcionou foi fazer a placa imprimir um número que decide entre hipóteses. As lições mais úteis vieram de sondagens que deram respostas erradas:

Rodar cada build sem gravar a placa

Esse método só funciona quando testar algo é barato, e depois de várias horas de tentativa e erro, gravar a placa a cada mudança não era: escrever a imagem na XIAO por USB, esperar o reboot, ler o log serial, repetir. Então, para rodar e conferir cada build, usei o velxio-cli, o cliente de linha de comando do Velxio. Ele recebe o mesmo .bin que o meu toolchain gerou, executa no ESP32-S3 simulado do Velxio por um tempo simulado fixo e devolve a saída serial, então eu conseguia ler as sondas acima sem tocar no hardware. A placa só recebia uma imagem nova quando um build valia a pena.

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

Instalar e fazer a primeira execução leva poucos minutos: veja o guia rápido do velxio-cli.

Os bugs

No jogo no portátil, com o radar no canto superior direito

Strict aliasing apagou uma rotação

A tela branca: cinco hipóteses erradas, três causas reais

A regra de tamanho da GPU: um polígono fixado no limite de saturação de -1024 da GTE alcança a tela de 320x240; a GPU do PlayStation recusa qualquer coisa maior que 1023x511, o rasterizador de software o desenhava

A correção de culling da hipótese 4 era real, mesmo não sendo a causa. O teste de bounding-box tratava uma caixa que cruza o plano próximo da mesma forma que uma inteiramente atrás dele. Separar os dois casos levou kept-saturated de 16.090 para 4.947. Uma tentativa anterior baseada em coordenadas saturadas resgatou 97% de tudo que o teste de tela rejeitava (+40% de rasterização), porque uma parede grande e distante também satura. Perguntar diretamente sobre Z (SZ <= H/2) deu 1.440 em vez de 15.000.

Square0 deslocado em 12 bits: toda distância /64

O Snake dava três passos, batia numa parede, ricocheteava e nunca progredia. A taxa de quadros foi o primeiro suspeito. Uma observação a descartou: o mundo se movia bem e só o jogador não. Uma sonda em GM_ActControl mostrou um passo de +4481 seguido de um rebote de -14641.

No PSY-Q o sufixo numérico é o deslocamento: Square0 não desloca e Square12 desloca. O Square0 do port deslocava em 12, então todo comprimento Square0 -> sum -> sqrt saía /64. Isso quebrou:

Remover o deslocamento tornou a trajetória monotônica.

Cinco opcodes da GTE copiados da linha errada

O Snake havia caído para fora do mundo (Y = -3250), o movimento estava fixado em 0,1 por frame, e o dock não tinha água. Os Psyz_GteRtv0/Rtv1/Rtv2/Ll/Llv0 do psyz usavam opcodes MVMVA da linha errada da própria tabela inline_n.h do MGS. “Rotacione este vetor” virou “rotacione-o e some a translação obsoleta”, e a iluminação usava a matriz de rotação em vez da matriz de luz.

Após a correção:

O dock vazio era um script de duas passagens

O dock tinha apenas um punhado de grupos de objetos, e o script parecia executar um comando. A estrutura real de s00a é if (var[5] < 6) { set up the Colonel's call } else { build the dock }, e o proc da chamada é um restart. O mundo é construído na segunda passagem, e responder ao codec a dispara.

Eu mesmo tinha mascarado o codec para evitar um crash, e isso desabilitou todo radio -c ... -p proc em todos os estágios. MENU_RadioDrainHeadless agora responde à chamada e despacha seu proc sem abrir a tela do codec. Os grupos de objetos foram de 480 para 3.240 por 120 frames, e a área de água foi criada. A lição: um stub temporário precisa de algo que force você a revisitá-lo.

Divisão por zero: o MIPS sobrevive, o Xtensa reinicia

libhzd/near.c divide por um comprimento 2D ao quadrado que pode ser zero em casos degenerados. O R3000 continua com um resultado indefinido. O Xtensa levanta IntegerDivideByZero e a placa reinicia. HZD_DIV foi aplicado às 7 divisões com divisor em tempo de execução. Depois disso, 80 s de caminhada nas quatro direções, o padrão que costumava travar, deu 0 panics. Neste port, toda divisão por um divisor calculado precisa de uma guarda.

O congelamento de 17,6 minutos

O VSync do psyz truncava seu resultado para 16 bits em todos os modos, mas VSync(-1) deve retornar a contagem de campos de 32 bits. Em 65.536 campos (17,6 minutos a 60 Hz), o relógio do mts deu a volta de 64.800 para 1.064 enquanto uma tarefa esperava por 65.537, e esperou para sempre. A correção retorna a contagem completa para mode < 0. Isso afeta todo projeto construído sobre o psyz. Bugs que dependem de tempo decorrido nunca aparecem em testes de 60 segundos.

O boot que parecia travado

Por horas o boot pareceu travado. O mts_printf da Konami era um stub vazio no PSX, e meu #define printf mts_printf enviava toda a saída do jogo para ele, então o boot progredia silenciosamente. Assim que mts_printf chamou vprintf, o log mostrou que o jogo havia chegado a memcard_init(). Antes de diagnosticar um travamento, certifique-se de que a saída vai para algum lugar.

Um deadlock de prioridade que era um malloc falho

O daemon de arquivos (tarefa 10) nunca recebia tempo de CPU, e o trace parecia um deadlock de prioridade. Duas correções reais (a semântica de ChangeThFromISR e o relógio de VSync(-1)) não mudaram nada. Então uma linha resolveu: [thread] OpenTh: xTaskCreate failed.

Eu havia aumentado as pilhas para 32 KB, o FreeRTOS as retira da SRAM interna, e a quarta tarefa não cabia. OpenTh retornou -1, e ChangeTh rejeitava aquele tid para sempre. Neste SoC, sempre verifique o valor de retorno de xTaskCreate, mesmo com megabytes de PSRAM livre.

Tela preta após adicionar os dados de cutscene

Copiar DEMO.DAT, VOX.DAT e ZMOVIE.STR para o cartão deixou a tela preta: 720 frames, 0 panics, e zero primitivas enviadas.

O código de troca de estágio espera por GM_StreamStatus() == -1. O stream de DEMO.DAT da cutscene nunca avançava, porque o CD virtual serve leituras de setor mas não o caminho de streaming contínuo em ring-buffer. Antes de os arquivos existirem, o stream havia sido rejeitado cedo e tudo continuava.

O tratamento atual:

Bugs menores

Desempenho

O tempo de rasterização é um contador esp_timer no rasterizador, somado ao longo de 120 frames na mesma posição.

A primeira passagem foi em s07a, uma sala pequena. O tempo total de rasterização caiu de 923.000 para 903.900, depois 794.000, depois 741.700 us (de 7,69 para 6,18 ms por frame). As três etapas:

  1. SOFT_RASTER_IRAM estava vazio na build do MGS, então os laços por pixel rodavam a partir da flash. Deveria ser IRAM_ATTR. Corrigir isso rendeu -2%.
  2. PSRAM e flash a 120 MHz renderam -12%. Primeiro concluí que esta placa não conseguiria. O erro “FLASH and PSRAM Mode configuration are not supported” significa apenas que falta CONFIG_IDF_EXPERIMENTAL_FEATURES=y. Verifique CONFIG_SPIRAM_SPEED 120 no sdkconfig.h gerado.
  3. O scanout rodava a 62,5 Hz para um jogo de 30 fps. Metade dos pushes reenviava a mesma imagem, cada um lendo cerca de 120 KB de PSRAM e expulsando as texturas do rasterizador no outro núcleo. Igualar à taxa do jogo rendeu -6,6%.

Tempo de frame: rasterização em s07a caindo de 7,69 para 6,18 ms ao longo de três etapas, e um frame do dock com 40,9 ms de rasterização mais cerca de 25 ms de lógica, cerca de 15 fps contra uma meta de 33,3 ms

O dock (s00a) é bem mais pesado. Um profile ali mediu 46.400 pixels texturizados e 71.680 pixels planos por frame: 40,9 ms de rasterização mais cerca de 25 ms de lógica e GTE, o que dá cerca de 15 fps. O README atualmente indica cerca de 15 fps para o dock com inimigos. O documento de status indica de 8 a 15 fps por cena, contra uma meta de 30.

Um caminho rápido de 32 bits para preenchimentos planos ganhou apenas 2%. O custo está nos pixels texturizados, a cerca de 207 ciclos cada. Um jogo 2D roda muito mais rápido no mesmo rasterizador: um tilemap percorre texturas em linha reta, e uma linha de cache de 64 bytes serve 128 pixels. Nos triângulos rotacionados do MGS, U e V mudam a cada pixel, e quase todo pixel é um cache miss. O cache de dados já está no seu máximo de 64 KB.

O próximo passo é mover páginas de textura quentes para a SRAM interna, o que o documento de status estima ser 40 vezes mais rápido. Isso exige os cerca de 90 KB presos em pilhas mts superdimensionadas (24 KB para a tarefa grande e 6 KB para o resto). Encolher as texturas não é opção, porque as UVs estão embutidas nos modelos.

O carregamento também é lento: cerca de 11,5 s para 1,1 MB do cartão (aproximadamente 95 KB/s).

Colocando o portátil para funcionar

Fiação do portátil: o XIAO ESP32S3 Sense, o painel ILI9341, o analógico em D0/D1, uma escada de resistores de seis botões em D2 e dois botões diretos em D5/D7

O portátil montado em placa de prototipagem: o analógico à esquerda, os resistores da escada de botões no meio e o XIAO na parte de baixo

O portátil é construído com:

O que vem na caixa do XIAO ESP32S3 Sense: a placa com sua câmera, uma antena Wi-Fi, pinos de header e dissipadores (foto: Seeed Studio)

Todos os 11 pinos do XIAO são usados. A fiação está documentada no guia de hardware. Notas de bring-up:

O MGS agora inicia no portátil, monta o cartão, carrega o dock e roda sem panics, a uma taxa de frames que o README descreve como semelhante à da placa Waveshare.

O que ainda não funciona

Próximos passos

  1. Dimensionar corretamente as pilhas mts e mover páginas de textura quentes para a SRAM interna.
  2. Medir os clocks de memória 120/120 MHz no XIAO.
  3. Corrigir o índice do RADIO.DAT, depois verificar se o elevador acompanha.
  4. Implementar streaming no CD virtual, para recuperar cutscenes e vozes.
  5. Adicionar áudio através de uma SPU por software.
  6. Remover as sondas de depuração.

Conclusão

Um PlayStation tolera type punning, divisão por zero, leituras além de arrays e ponteiros testados por sinal. Um compilador e uma CPU modernos não toleram nada disso. A abordagem que funcionou neste port foi projetar cada medição de modo que ela possa falhar.


Compartilhar em:
David Montero

Escrito por

David Montero

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

GitHub velxio.dev

Artigos relacionados


Artigo anterior
Castlevania: Symphony of the Night rodando nativamente no ESP32-S3
Próximo artigo
222 módulos Seeed Grove agora rodam no navegador