Codebase Deep Dive: SameBoy

SameBoy is a native desktop/mobile emulator — not a web app, not a server. It ships multiple GUI frontends around one shared emulation core, plus a headless tester, libretro core, and open-source boot ROMs.

C Objective-C Makefile rgbds SDL2 Metal/OpenGL

• GB_gameboy_t — opaque (public) or fully expanded (internal) struct holding all hardware state, split into GB_SECTION blocks for save states.
• GB_model_t — DMG, MGB, SGB, SGB2, CGB, CGB0, AGB, etc. (Core/model.h).
• Callback function pointers in the unsaved section — bridge to frontends without platform deps in Core.
• GB_UNIT state machines in timing.h — batchable per-component timing (display, div, APU channels).

gb.h — GB_gameboy_t sections

1. GB_init(gb, model) — zero state, allocate WRAM/VRAM by model, set defaults, call GB_reset(), load default border tiles.
2. Frontend registers callbacks (GB_set_vblank_callback, GB_apu_set_sample_callback, etc.).
3. GB_load_rom() — mmap/copy ROM, parse header via GB_configure_cart(), set MBC type.
4. GB_load_battery() — restore MBC RAM + RTC from .sav.
5. Boot ROM load via boot_rom_load_callback (frontend provides file or embedded ROM).
6. Main loop: GB_run() until exit.

GB_init · SDL run() setup and loop

SDL (SDL/main.c, gui.c, audio.c), Cocoa (Cocoa/Document.m, GBView.m), iOS (GBViewController.m), libretro (libretro.c). Each translates OS events → GB_set_key_state and callbacks → OS audio/video APIs. No emulation accuracy logic lives here.

External heap blobs: rom, ram, vram, mbc_ram — serialized as trailing blocks in save files.

• ROM — raw .gb / .gbc; header parsed at 0x0100–0x014F
• Battery — .sav beside ROM (MBC RAM + RTC); multiple legacy formats supported in gb.c
• Save state — section-ordered binary + optional BESS footer for cross-emulator compatibility
• Cheats — .cht text format
• SDL prefs — binary prefs.bin (SDL/configuration.c)
• Cocoa/iOS — NSUserDefaults keys like GBEmulatedModel, GBRight
• Libretro — core options via RETRO_ENVIRONMENT_GET_VARIABLE

No network, database, or cloud services in the core product.

• Return codes: GB_load_rom, GB_save_state, GB_load_battery return 0 on success, negative on failure.
• Assertions: GB_ASSERT_NOT_RUNNING prevents re-entrant GB_run; debug-only thread checks on callback registration.
• Logging: GB_log(gb, fmt, ...) → optional log_callback; SDL can capture to message boxes.
• Tester crash detection: stack overflow, halt-with-IE=0 deadlock, infinite 0xFF at 0x38.
• Graceful degradation: unreadable .sav path logs warning; RTC reset if timestamp implausible.

Failure modes: corrupt ROM header → GB_configure_cart may default to ROM-only; save state version mismatch → load rejected; audio backpressure in SDL drops samples when queue > freq/8.

• Core is single-threaded. running_thread_id tracks the emulation thread; callbacks must not call GB_run re-entrantly.
• Cocoa: emulation on NSThread (Document.m -run); UI on main thread; atomic blocks for debugger.
• iOS: serial GCD queue _runQueue for GB_run.
• SDL: single-threaded main loop; input polled via update_input_hint_callback from timing code.
• Libretro: host-thread driven; no internal threads.
• Tester: optional --jobs N forks processes (Unix only).

Turbo mode skips PPU rendering and may skip vblank callbacks unless enable_skipped_frame_vblank_callbacks is set. Rewind pushes state on each vblank (compressed).

Framework: Custom headless runner (Tester/main.c), not unit tests. CI compares SHA1 of output BMP screenshots.

CI ROMs (.github/actions/sanity_tests.sh): cgb_sound.gb, cgb-acid2.gbc, dmg-acid2.gb, dmg_sound-2.gb, oam_bug-2.gb.

Run locally:

make tester CONF=release
./build/bin/tester/sameboy_tester --cgb --length 10 path/to/rom.gb

Covered: PPU accuracy (Acid2), APU (blargg sound ROMs), OAM bug, basic crash detection.

Uncovered: Individual MBC edge cases, debugger commands, frontend UI, link cable timing, most cheat paths — no automated tests found.

# Dependencies: clang, make, rgbds, cppp, libsdl2 (SDL port)
git clone https://github.com/LIJI32/SameBoy.git
cd SameBoy
make                    # sdl on Linux, cocoa on macOS
make all CONF=release   # sdl + tester + libretro + lib (+ cocoa on macOS)
make -C libretro        # libretro core only
./build/bin/SDL/sameboy game.gb

# CI equivalent
make -j all CONF=release
.github/actions/sanity_tests.sh

Deploy: GitHub Actions builds artifacts on push to master; libretro branch auto-synced via update_libretro.sh; macOS releases as .app, iOS as IPA/deb; FreeDesktop make install.

Config: CONF=debug|release|native_release|fat_release, BOOTROMS_DIR=, DATA_DIR=, DISABLE_DEBUGGER=1 (lib only).

1. Core/gb.h — entire public API and state layout
2. Core/gb.c — GB_init, GB_run, ROM/battery lifecycle
3. Core/timing.c — GB_advance_cycles, the synchronization hub
4. Core/sm83_cpu.c — CPU execution and bus-cycle timing
5. Core/memory.c — memory map, side effects, OAM bug
6. Core/display.c — PPU (largest accuracy-critical file)
7. Core/apu.c — audio generation
8. Core/mbc.c — cartridge hardware
9. Core/save_state.c — persistence format
10. SDL/main.c — reference frontend integration
11. libretro/libretro.c — alternative frame-driven host model
12. Makefile — how everything is wired together

• 8 MHz cycle units: Internal cycle counters use 8 MHz units; DMG divides by 2 in GB_advance_cycles when not in double-speed CGB mode.
• GB_run ≠ one frame: Easy to misread; use GB_run_frame or loop on vblank_just_occured.
• Bus conflicts: sm83_cpu.c has per-register conflict maps for DMG/CGB/SGB — changing I/O timing can break Acid2-style tests.
• PPU state machine: 20+ states in display.c; STAT mode bits intentionally delayed 4 T-cycles (see TODO in source).
• Opaque struct: Public builds hide GB_gameboy_t layout; define GB_INTERNAL when hacking Core.
• Libretro strips features: Built with GB_DISABLE_REWIND, GB_DISABLE_DEBUGGER, etc.
• Band-limited init: apu.c uses __attribute__((constructor)) — runs at library load.
• SGB intro hack: Special path in GB_run advances PPU without CPU during intro animation.
• Save state version: STRUCT_VERSION 15 — bumping requires migration logic in save_state.c.

1. Read README.md and skim DeepWiki overview
2. Study Core/gb.h — GB_SECTION layout and public functions
3. Trace GB_init → GB_reset in gb.c
4. Read GB_run and follow into GB_cpu_run (sm83_cpu.c)
5. Understand GB_advance_cycles in timing.c
6. Pick one bus operation: GB_read_memory for I/O register side effects
7. Skim display.c GB_display_run state machine header
8. Read SDL run() in SDL/main.c for callback wiring
9. Run make tester on dmg-acid2.gb and inspect output BMP
10. Explore debugger.c if modifying CPU or memory behavior

• Exact hardware behavior for several TODO-marked timing cases (ISR IF read timing, STOP mode DMA, MGB OAM bug variants).
• Whether Windows tester target is intentionally broken (Makefile links incomplete object set).
• Production release cadence and signing process for macOS/iOS builds.
• Which real-hardware tests were used to validate each bitwise_glitch OAM corruption variant.
• Performance characteristics on low-end ARM without profiling data in repo.