ndsemu

Emulador de Nintendo DS em Java 25, irmao do gbaemu. Reaproveita a biblioteca arm-jitter como runtime ARM (JIT + interpretador de debug), dirigindo os dois processadores do DS.

Estado: jogos comerciais jogaveis. Mario Kart DS roda de ponta a ponta (validado em gameplay real), Jump Ultimate Stars e Super Mario 64 DS rodam in-game, e todo o corpus homebrew moderno (libnds 2.x/calico) boota. Ver "Compatibilidade" abaixo.

Arquitetura

                +-------------------+        +-------------------+
   ARM9 (v5TE)  |     Arm9Bus       |        |     Arm7Bus       |  ARM7 (v4T)
   ArmCore  --> | (AddressSpace)    |        | (AddressSpace)    | <-- ArmCore
   JitRuntime   +---------+---------+        +---------+---------+  JitRuntime
                          |   \                  /     |
                          |    \                /      |
                       ITCM/    \   Main RAM   /    ARM7 WRAM
                       DTCM      \  (4 MB)    /     (64 KB)
                       BIOS9   shared WRAM (32 KB, WRAMCNT)   BIOS7
                                  VRAM / Palette / OAM
                              IPCSYNC + IPC FIFO + I/O

Cada CPU executa via arm-jitter (ArmCore + JitRuntime), acessando memoria por um InvalidationAwareAddressSpace que invalida blocos JIT em escritas (codigo automodificado). O NdsConsole intercala os dois (~2 ciclos ARM9 : 1 ciclo ARM7) e roda os perifericos por ciclo. O backend padrao e o JIT ASM com superblocos de loop, chaining de blocos com budget de ciclos e warm-start (PCs quentes persistidos por ROM em .hotpcs, pre-compilados no load).

Estado atual

Nucleo

• Dois ArmCore (ARM9 = ARMv5TE com CP15 completo incl. c13; ARM7 = ARMv4T), scheduler intercalado, direct-boot HLE (header do cartucho, copia dos binarios, WRAMCNT, estado pos-firmware).
• Slot-1 CardController (comandos de cartucho + DMA de card).
• IPC (IPCSYNC + FIFO), IRQ por CPU, 4 timers por CPU, DMA por CPU (imediato, VBlank, HBlank, GXFIFO, card), divisao/raiz quadrada por hardware do ARM9.

Video

• Dois engines 2D (A/B) com as duas telas 256x192; bancos de VRAM A-I com mapeamento flexivel (VRAMCNT) e cache de mapeamento.
• Engine 3D: GXFIFO (IRQ level-triggered), pipeline de matrizes, texturas (todos os formatos usados pelos jogos validados), rasterizador com Z-buffer e W-buffer, blend.

Audio e perifericos

• SPU de 16 canais; saida com buffer de ~200 ms usado como relogio mestre + frameskip adaptativo de video (audio nunca engasga; video cede quando falta CPU).
• SPI (touchscreen, firmware), RTC, input.

Saves e estados

• Backup SPI (.sav).
• Save states de maquina completa (.ss) + warm-start do JIT no restore.

GUI e ferramentas

• GUI Swing (ui/NdsDesktop): duas telas, HUD de fps no titulo, F9 destrava o throttle, settings persistentes, dialogo de configuracao de firmware.
• GDB server (porta 3333) via arm-jitter: debug source-level do codigo guest com arm-none-eabi-gdb + o .elf do homebrew.
• Oraculo melonDS: parsers de savestate (VRAM + polygon RAM) em texdump/ para comparar estado grafico contra ground truth.

Compatibilidade

Titulo	Estado
Mario Kart DS	Jogavel (~92-97% realtime); item-box do HUD 2D nao renderiza (aberto)
Jump Ultimate Stars	In-game, ~99% realtime
Super Mario 64 DS	In-game, ~72% realtime
Pokemon Platinum	Renderiza intro/attract/overworld; trava indo ao menu do titulo (task D5)
rockwrestler (suite de testes)	Passa 100%
Homebrew libnds 2.x/calico	Boota (corpus: 80 exemplos do devkitPro nds-examples, todos buildam e rodam)

Bugs abertos alem dos da tabela: perda de luz 3D apos restore de save state.

Build

Requer JBR 25 (JDK do IntelliJ). A arm-jitter resolve do Maven Central (dev.vitorsilverio:arm-jitter:1.0.0), sem mvn install local:

mvn test

Só é preciso instalar uma versão local da arm-jitter quando se está desenvolvendo a lib junto com o ndsemu (mudança ainda não publicada) — ver arm-jitter/README.md, seção "Desenvolvendo a lib junto com um consumidor".

Uso

GUI (forma recomendada):

mvn exec:java -Dexec.mainClass=dev.vitorsilverio.ndsemu.ui.NdsDesktop

Harness headless de debug/bench (Main):

# roda N frames e grava frame.png
mvn exec:java -Dexec.mainClass=dev.vitorsilverio.ndsemu.Main -Dexec.args="game.nds 600"
# bench limpo (emulate+render+mix, CSV por janela de 60 frames)
... -Dexec.args="game.nds 3600 bench"
# GDB remote stub no ARM9 (porta 3333)
... -Dexec.args="homebrew.nds gdb"
# carregar um save state e/ou dumpar materiais/texturas 3D
... -Dexec.args="game.nds 60 state=cena.ss texdump"

Layout

src/main/java/dev/vitorsilverio/ndsemu/
  core/        NdsConsole, scheduler, direct-boot
  memory/      Main RAM, WRAM, TCM, BIOS, buses, mapa de memoria
  cartridge/   header, ROM, slot-1 CardController
  video/ gpu/  engines 2D, VRAM, engine 3D
  audio/       SPU + saida de audio
  dma/ timer/ interrupt/ ipc/ math/ io/   perifericos e I/O
  spi/ rtc/ input/                        touch, firmware, relogio, teclas
  save/        backup SPI + save states
  jit/         integracao JIT (hot blocks, warm-start)
  ui/          GUI Swing (NdsDesktop)
firmware/      BIOS9/BIOS7/firmware/key (assets locais, nao versionar dumps)

Licença

BSD 3-Clause — ver LICENSE.

Os binários de terceiros usados em testes e execução (BIOS, firmware, ROMs, kernels, busybox) não são cobertos por esta licença e não são redistribuídos por este projeto salvo quando a licença original permitir; ver o README.md do diretório correspondente.