Émulateur compté en cycles de la Gamebuino META (SAMD21, Cortex-M0+), de la Pokitto (LPC11U6x, Cortex-M0+) et de l’ESPboy (ESP8266, Xtensa LX106), écrit en C, avec un frontal SDL2 et un build WebAssembly.
English version: README.md
gm0 exécute les firmwares non modifiés des trois consoles depuis un seul
binaire. La cible est détectée d’après l’image du firmware (pointeur de pile
initial dans la SRAM SAMD21 ou LPC ; en-tête d’image 0xE9 ou ELF pour
l’ESPboy) et peut être forcée par --target (META et Pokitto). Le
même cœur C est compilé en natif et en WebAssembly.
.pop lu nativement.ets_*,
fonctions de flash, timer1, GPIO et sortie audio sigma-delta, SPI1 vers
l’écran ST7735 (128×128), boutons du MCP23017..zip, ou dossier de l’hôte
converti en FAT16 à la volée ; les sauvegardes des jeux sont réécrites.| Cible | État | Titres testés |
|---|---|---|
| Gamebuino META | Jouable | lapinou (pilotes bare-metal), Celeste, Cats & Coins, Picomon, Yatzy, Reuben Quest, loaders du site, firmwares Game Boy convertis (protocoles DMA/SPI 0.4.0+) |
| Pokitto | Jouable | Pandemic, Galaxy Fighters (.pop, musique streamée depuis la carte) |
| ESPboy | Démarre et fait tourner les firmwares m0boy (Game Boy, SG-1000, Game Gear, Master System) | firmwares convertis par m0boy ; non comparé à une console |
| WebAssembly | Jouable | même cœur ; page servie ou fichier HTML autonome unique |
Le dépôt ne contient ni jeux ni firmwares.
Build natif avec CMake (SDL2 et zlib requises ; Linux, macOS, Windows via MSYS2 MinGW-w64) :
cmake -B build .
cmake --build build # produit build/bin/gm0
L’interface est en anglais par défaut ; configurer avec -DGM0_FR=ON pour
le français. Les messages brefs à l’écran (redémarrage, filtre, échelle,
chargement) sont activés par défaut ; -DGM0_OSD=OFF les retire.
Build WebAssembly (emsdk requis, emcc dans le PATH) :
make wasm # produit wasm/gm0.html
Le résultat est un fichier unique, module wasm embarqué, ouvrable
directement en file://. Une version en ligne est disponible sur
https://r043v.github.io/gm0/ (émulateur seul — chargez vos propres jeux).
Windows, compilé depuis Linux avec MinGW-w64, en un seul gm0.exe (SDL2
intégrée). Avec les paquets natifs installés (mingw-w64-gcc,
mingw-w64-binutils, mingw-w64-crt, mingw-w64-headers,
mingw-w64-winpthreads, mingw-w64-sdl2 et mingw-w64-zlib de l’AUR) :
make win # build-win/bin/gm0.exe
Sans eux, make win-setup installe la même chaîne dans
~/.local/mingw-w64 (environ 440 Mo, sans root), puis make win fonctionne
de la même façon. make win WIN_STATIC=OFF garde SDL2 dans un SDL2.dll
séparé.
main exécute les firmwares META/Pokitto. La lecture directe des cartouches
SG-1000 est sur z80.
Construire un exécutable natif qui démarre le jeu sans argument :
cmake -G Ninja -S . -B build-bundle -DGM0_BUNDLE=/chemin/jeu.zip
cmake --build build-bundle
GM0_BUNDLE accepte un firmware .bin ou .pop, ou un ZIP contenant le
firmware et les fichiers de sa carte SD (dont la ROM utilisée par le firmware).
Utiliser un ZIP si le jeu lit des fichiers sur la carte. Une ROM Game Boy brute
doit d’abord être convertie en firmware META/Pokitto avec m0boy. Un jeu ou une
carte donnés en argument remplacent le jeu embarqué. Sous Windows, SDL2 est
liée statiquement par défaut lorsqu’elle est disponible.
Pour un HTML unique qui démarre le jeu intégré (emsdk requis) :
emcmake cmake -G Ninja -S . -B build-wasm -DGM0_WEB_GAME=/chemin/jeu.zip
cmake --build build-wasm # build-wasm/gm0.html
GM0_WEB_GAME accepte les mêmes formats. Le module et le jeu sont intégrés
au HTML pour fonctionner hors ligne ; le son du navigateur demande toujours
un geste utilisateur. Garder les jeux fournis et les builds générés hors des
sources suivies.
gm0 [firmware] [carte] [options]
| Argument | Sens |
|---|---|
firmware |
.bin, ou .pop (Pokitto) |
carte |
image brute .img, .zip (carte complète), ou dossier (FAT16 construit à la volée). Sur META, la carte est par défaut le dossier du firmware. |
--target meta\|pokitto |
force la cible |
--rom fichier, --sym fichier |
ESPboy : image de ROM (rom.bin, flash 0x100000) et fichier de symboles d’un .bin (défaut : rom.bin et <nom>.sym / firmware.sym à côté) |
--frames N |
exécute N frames puis quitte |
--shot fichier.ppm |
capture d’écran en fin d’exécution |
--wav fichier.wav |
enregistre l’audio de la session (48 kHz, rendu depuis le temps émulé) |
--out-img fichier.img |
exporte la carte en sortie si elle a été modifiée |
--eeprom-ro |
Pokitto : charge le .eeprom à côté du firmware sans jamais le réécrire (exécutions reproductibles) |
--record-input fichier |
enregistre la session : touches tenues à chaque image gm0 (lignes k) et, pour un firmware m0boy, les boutons que reçoit le jeu émulé avec le numéro d’image du jeu (lignes g), lus par le descripteur m0input du firmware ; r marque un redémarrage, e la fin |
--play-input fichier |
rejoue les touches (lignes k) d’une session enregistrée, image pour image |
--play-guest fichier |
rejoue une session par image du jeu (ses lignes g, firmwares m0boy) : chaque fois que le firmware écrit les boutons du jeu émulé, ils deviennent l’état enregistré pour l’image du jeu en cours ; un firmware plus rapide ou plus lent joue exactement la même partie (comparaisons de firmwares ; META et Pokitto) |
--until-guest N |
s’arrête quand le compteur d’images du jeu atteint N ; --dump-ram garde alors la RAM de cet instant |
--resume-at N |
avec --play-input : avance rapide (sans rythme, un écran sur trente) jusqu’à l’image gm0 N, puis la main au joueur ; N devient un instantané |
--dump-ram fichier |
écrit la RAM principale en fin de run (SRAM META depuis 0x20000000, Pokitto depuis 0x10000000, DRAM ESPboy depuis 0x3FFE8000) : compteurs du firmware, lus par symbole |
-w [n], -W |
Pokitto : ignore les n (ou toutes les) prochaines écritures flash fautives au lieu de lever une HardFault |
Lancée sans argument, la fenêtre s’ouvre vide ; on y dépose un jeu (.bin,
.img, .zip, dossier). L’exécution se termine par une ligne [bench]
donnant la vitesse brute d’émulation.
Exécution sans affichage (tests, captures) :
SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy \
gm0 jeu.bin carte/ --frames 300 --shot capture.ppm
gm0 jeu.zip # firmware.bin + firmware.sym [+ rom.bin], tel que compile.sh de m0boy l'emballe
gm0 firmware.bin --rom rom.bin # firmware.sym est cherché à côté
gm0 firmware.elf [--rom rom.bin] # l'ELF porte les symboles
Le code du firmware est exécuté tel quel (cœur Xtensa, carte mémoire avec les
règles d’accès de la puce : un chargement 8 ou 16 bits en IRAM ou en flash
mappée arrête l’émulation, comme le LoadStoreError de la puce). Ce qui est
d’Espressif — ROM de boot et SDK, non livrés ici — est émulé par fonction :
le démarrage (eboot, app_entry, user_init) n’est pas exécuté, la machine
fait ce qu’il laisse (pile cont, ISR de timer1, constructeurs C++) puis appelle
setup() et loop(). Accrochés par nom (firmware.sym ou l’ELF) : micros,
delay, system_update_cpu_freq, twi_writeTo/readFrom,
spi_flash_read/write/erase_sector, system_restart, chien de garde et mode
Wi-Fi. Toute autre fonction de la ROM appelée et non émulée arrête l’exécution
en donnant son nom.
MULL, +2 par branche ou appel pris (RET +3), +1 si l’instruction suivante
utilise un registre qu’un chargement vient de remplir, MEMW 4 après un
rangement, +5 par chargement en IRAM, ROM ou flash mappée (littéraux compris),
+15 par lecture d’un registre de périphérique et +10 par écriture (moitié en
cycles à 80 MHz, temps de bus), rien depuis la DRAM. Ni validé ici ni dans
cette référence : le coût d’un défaut du cache d’instructions
(GM0_ESP_FLASH_MISS=<cycles par ligne de 32 octets> active un cache direct
de 32 Kio, éteint par défaut), les octets SPI à l’horloge que programme le
firmware, l’effacement de flash 45 ms et la programmation 0,7 ms par page.
Ce sont donc des estimations bâties sur des coûts d’instruction mesurés, pas
des mesures de ce firmware sur la puce.MADCTL, pixels de 12/16/18 bits) avec ce que fait le panneau de
l’ESPboy : adresses de colonne et de ligne sur leur octet bas seulement,
SWRESET qui garde MADCTL et COLMOD, panneau BGR (MADCTL.BGR à 0
échange rouge et bleu au balayage, mémoire déjà écrite comprise), blanc
endormi ou éteint, et il n’écoute que si B0 du MCP23017 (CS) est bas. Avec la
config de TFT_eSPI (MADCTL 0xC8, fenêtre colonne 2, ligne 3, comme le
firmware m0boy), le pixel (x, y) de la vitre est la mémoire (129 − x,
128 − y). Mode partiel, défilement et veille ne sont pas modélisés.0x3C0000-0x3FB000) sont conservées dans
<nom>.sav à côté du firmware (ou du zip).tests/esp/run_tests.py compare le cœur Xtensa et les fonctions de
la ROM à l’hôte sur des programmes C compilés pour lx106 à plusieurs niveaux
d’optimisation ; tests/test_esp.py fait tourner un petit firmware sur toute
la machine (écran, boutons, audio par timer1, sauvegardes en flash). Tous
deux demandent le toolchain-xtensa de PlatformIO (sinon ils sont sautés).| META | Pokitto | |
|---|---|---|
| Croix | flèches | flèches |
| A / B | Espace / Ctrl | Espace / Ctrl |
| MENU / touche de menu (m0boy) | Entrée / H (HOME) | Entrée / H (C) |
| HOME / éclairage | * ou I (maintenu 3 s : reset du jeu) |
F |
ESPboy (touches META) : croix comme la META, A = ACT (J), B = ESC (K), MENU (U) = bouton auxiliaire droit (Start), HOME (I) = bouton auxiliaire gauche (Select ; maintenu pour le menu du frontal Game Boy).
| Touche | Action |
|---|---|
| F2 | instantané : l’image gm0, notée (ligne s) dans l’enregistrement de --record-input |
| F4 | retour au dernier instantané : gm0 repart à froid (même processus) et rejoue en avance rapide les touches tenues jusque-là ; l’enregistrement, réécrit depuis l’allumage, continue (META, Pokitto) |
| F5 | reset |
| F8 | filtre d’affichage, en cycle : pixel (défaut), vert Game Boy (DMG), LCD RGB, scanlignes, grille, aucun |
| F10 | mode d’échelle : entière, ajustée, étirée |
| F11 | plein écran |
Les manettes sont prises en charge via SDL_GameController, branchement à chaud
compris, sur les deux cibles. L’ordre des bits du registre à décalage des
boutons META suit la vitesse SPI à laquelle le jeu le lit ;
EMU_BTN_ORDER=lapinou force l’ordre des jeux maison.
| Fonction | Natif | WebAssembly |
|---|---|---|
| Audio | SDL2, calé sur le temps émulé (régulation du débit ±0,5 %) | WebAudio, démarre au premier geste |
| Sauvegardes | .SAV/.STA réécrits sur disque ; EEPROM Pokitto persistée dans <jeu>.eeprom |
en mémoire, perdues à la fermeture de l’onglet |
| Auto-programmation flash (loaders) | émulée | ignorée |
| Liste de jeux | — | dock en un clic (wasm/games.js), jeux embarquables dans le fichier autonome |
| Pause | — | boutons du dock (pause, arrêt) |
gm0 vise le matériel plutôt que les autres émulateurs : la parité avec l’émulateur TypeScript d’origine a été abandonnée volontairement en octobre 2026.
Mesurée sur la machine de développement (x86-64, GCC 16, -O3 -flto),
vitesse brute sans régulation de frame, en multiple du temps réel :
| Titre | Cible | Vitesse |
|---|---|---|
| lapinou | META | 4,4× |
| Celeste | META | 4,6× |
| Cats & Coins | META | 5,5× |
| firmware Game Boy converti (sml) | META | 5,0× |
| Pandemic | Pokitto | 4,1× |
| firmware Game Boy converti (sml) | ESPboy | 1,6× |
Les chiffres dépendent de l’hôte et de sa charge. Le build WebAssembly tourne à pleine vitesse dans les navigateurs actuels.
Les diagnostics s’activent par variables d’environnement ; les plus utiles :
| Variable | Effet |
|---|---|
EMU_INPUT="frame:touches:durée,..." |
entrées scriptées (touches parmi UDLRABMH), ex. 200:A:5,300:R:40 ; H est la touche de menu des firmwares m0boy sur toutes les consoles (HOME de la META, C de la Pokitto). Aka accepte aussi C (C), X (D), Q (L1), E (R1) |
EMU_NOPACE=1 |
exécution aussi rapide que possible (mesures) |
EMU_TRACE=1 |
empreinte de l’écran toutes les 60 frames, trace CPU périodique |
TRACE_TAIL=N |
conserve les N dernières instructions, vidées sur un PC hors mémoire |
EMU_PROF=fichier |
profil de cycles par adresse écrit en fin d’exécution |
EMU_AUDIO_STATS=1 |
statistiques producteur/consommateur audio |
EMU_FIXED_RTC=t, ADC_FIXED=1 |
RTC et ADC déterministes |
EMU_DEBUG=1, SD_DEBUG=1, NVM_DEBUG=1, EMU_DMA_DEBUG=1, EMU_LCD_DEBUG=1, EMU_SYSCTRL_DEBUG=1 |
traces des périphériques |
FAT_DUMP=fichier, FAT_DUMP_EXIT=fichier |
écrit l’image FAT telle que construite au montage, ou la carte en sortie |
FLASH_DUMP=fichier |
écrit la flash META en sortie (après une éventuelle auto-programmation) |
tests/unit/run.sh # tests unitaires du cœur (programmation flash)
GM0_GAMES=dossier tests/parity/run.sh build/bin/gm0 # parité bit à bit sur des jeux locaux
tests/parity/run.sh fait tourner chaque jeu listé dans tests/parity/games.txt
(1500 frames, entrées scriptées) et compare trois empreintes SHA-256 à
tests/parity/refs.txt : l’écran (lignes EMU_TRACE), l’enregistrement
--wav et la capture --shot. Les jeux ne sont pas dans le dépôt
(GM0_GAMES vaut wasm/ par défaut). Chaque jeu tourne seul dans un
dossier jetable, avec --eeprom-ro : aucune EEPROM sauvegardée n’est
héritée. Ne réécrire les références (-u) qu’après un changement censé
modifier la sortie.
dirent.h) ; MSVC n’est pas testé.Les travaux prévus et les pistes étudiées sont suivis dans TODO.md.
gm0 a été écrit entièrement par des agents de programmation IA ; aucune ligne de C n’a été tapée à la main. La première version — environ 5 800 lignes de C et 66 commits, du 30 septembre au 6 octobre 2026 — a été produite par GLM-5.3-Flash via l’agent ZCode. Statistiques de cette semaine, relevées dans la base de sessions :
La refactorisation, les corrections de fidélité et le travail de performance ultérieurs ont été co-écrits avec Claude Opus 5.5 dans Claude Code.
Logique portée depuis deux émulateurs sous licence MIT :
Tout le reste suit la documentation des constructeurs :
Le comportement du matériel a aussi été établi en analysant du logiciel réel, sans en reprendre de code : le source de lapinou (pilotes écran, SD et audio bare-metal, qui ont révélé le protocole DMA/SPI de l’écran, le cadencement de TC4 et les pull-ups des chip-selects), des binaires META, et la lib officielle Gamebuino META (pile SdFat, descripteurs DMAC, audio TC5), exécutés pas à pas dans l’émulateur.
Écosystèmes : gamebuino.com pour la META, PokittoLib pour la Pokitto.
gm0 est publié sous CC BY-NC-SA 4.0 (© 2026 r043v) : attribution, pas d’utilisation commerciale, partage dans les mêmes conditions.
La logique issue des deux émulateurs sous licence MIT reste sous MIT ; leurs avis sont reproduits dans LICENSE : aoneill01/gamebuino-emulator (Andy O’Neill, 2017) et felipemanga/PokittoEmu (Felipe Manga, 2017). Implémenter un comportement décrit dans les datasheets des constructeurs (Microchip, NXP, Sitronix, Arm) ne crée pas d’œuvre dérivée de ces documents, et aucun code n’a été repris du source de lapinou, des binaires META ni de la lib officielle.
Merci à Jicehel pour le partage de son émulateur Aka basé sur QEMU : ses modèles de l’expander et de l’ADC, son vérificateur d’images et les sources du Launcher ont permis d’améliorer les boutons, le joystick, la batterie et le chargement des images ESP dans gm0.
gm0 exécute le code Xtensa du firmware lui-même (émulation applicative
expérimentale) : un ELF avec symboles, ou un .bin/.zip accompagné de son
firmware.sym (gm0 jeu.zip). Les services plateforme sont interceptés par
nom ; une instruction ou un service inconnu s’arrête avec un diagnostic.
Le mode système complet optionnel démarre le bootloader, FreeRTOS et les drivers dans l’émulateur QEMU de Jicehel, installé séparément (Linux et autres hôtes POSIX) :
gm0 jeu.bin --aka-system /chemin/vers/aka-emulator [--aka-sd dossier-carte] [--aka-flash fichier]
--aka-sd sert un dossier comme carte SD du Launcher (un sous-dossier par
application : firmware.bin, meta.json) ; --aka-flash garde la flash —
donc les jeux installés et les sauvegardes — d’un run à l’autre.
Voir utilisation, services et limites.