Tuesday, January 28, 2014

BitBoy : a gameboy emulator for bitbox !

BitBoy is a port from the gnuboy emulator heavily modified to fit in the Bitbox console.

The Gameboy emulator successfully emulates several games and homebrews for this venerable console.


Screenshots of the emulator.

The menu to select the on-chip games

NB :  Emulators are standard SDL games built with all bitbox programs running on the bitbox kernel with no modification of the game source code as the normal build of any game.
Meh, an emulator. But not only, it runs also on the real hardware : 

Available features

  • Based on (heavily modified to fit in memory constraints : 1MB incl. games & vga generation+ 192k RAM !) gnuboy emulator, as GNU GPL code available on github
  • Working Commercial and homebrew GameBoy titles (public domain homebrews or rightfully licensed games !)
  • 4 color palette B&W display, with custom palettes (fixed colors by game) to colorize the games.
  • Working on rev1 hardware including gamepad
  • Several ROMs can be embedded in on-chip flash (up to 1MB), with a selection menu

Source code

Code (including original very good gnuboy emulator heavily modified) is available here : https://github.com/makapuf/bitboy

Making of 

The adaptation of gnuboy to bitboy consisted of : 

  • mapping the inputs to bitboy rev1 gamepad
  • rewriting the main loop & main function (from command line to bitbox kernel frame interface), remapping time-relating functions.
  • interfacing the sound callbacks of bitbox to gnuboy engine generation.
  • removing / disabling all file related functions. Some could be re enabled to save some backup RAM to SDCard by example or load data cart from SD Card.
  • rewriting all the display code, not to fit bitbox display model -this adaptation was done quite simply by blitting a virtual framebuffer, but to make it faster and not depend on huge (100k) in-memory precomputed tables. Now only B&W GB has been done, but color could be done.
  • writing a blitter for the gnuboy pseudo-vram to Bitbox graphical kernel. Maybe this step (and the 2 VRAM buffers) can be skipped and real Bitbox lines be generated on the fly by the new gnuboy, faking Gnuboy v-syncs from the real Vsync bitbox interrupts.
  • modifying the memory mapper to use bitbox flash / Ram & mapping some RAM data (2 VRAM buffers) to ccm ram in order to save place in sram, disabling many functions like rom compression, battery-powered ram.
  • making a menu loader of ROMs in Flash, replacing the file loader. This is currently done by embedding roms as C data. Some quick "compression" could be done. (removing zeros or const data at end of pages)
  • menu selection of ROM as several ROMs can be placed in flash
  • linking ROM to custom palettes : Color games are not supported yet (colorized games using custom palettes are supported however), but given the size of those color games, they often wouldn't be able to be stored on the box anyway.
  • cutting color gameboy features to simplify development and lower memory requirements (standard GB has 8k, GBC has 32k of RAM, which could fit in CCM RAM, 16k VRAM vs 8k, and much larger games - often starting at 1MB).

Future work

Many things could be done (contribs welcome ! ) to further development :
  • Some graphical glitches on games (or frankly ugly artifacts), yes, they exist.
  • Sound has been neglected, ie should work, has worked, but now doesn't.
  • Loading ROMs from SDCard to RAM (64k max cartridges) - or even flash programming from uSD ?
  • Saving games states as  SDCard files
  • HiDef Scale2x type graphical output ?
  • Support of GBC seems doable, maybe in a future release, this would include working around memory limitations and reimplementing color GB features in graphical layer, on the fly loading some pages in RAM from SD to handle large ROMs?
  • Maybe adapting this emulator or graphical engine for NES ?


  1. This comment has been removed by the author.

  2. build/new_vga.o: In function `HSYNCHandler':
    c:/Retro/bitbox/lib/new_vga.c:317: undefined reference to `graph_line'
    c:/Retro/bitbox/lib/new_vga.c:330: undefined reference to `graph_frame'
    c:/Retro/bitbox/lib/new_vga.c:344: undefined reference to `graph_line'
    collect2.exe: error: ld returned 1 exit status

    How I can resolve these unimplemented functions?

  3. Ah, I see. there was some small changes in the API, the bitboy program needs to be adapted. (game_line -> graph_line basically, and the same for graph_frame, basically. Sound might need some adaptation also.)

    1. should be OK now. please send a message to the ML to discuss further bugs (works for me with latest API/ kernel)