Virtual GameBoy Advance
version 0.6

by Marat Fayzullin

Disclaimers

GameBoy and GameBoy Advance are registered trademarks of Nintendo.
The author is in no way affiliated with Nintendo.
The author is in no way affiliated with any pirate group out there.
The author cannot and will not provide you with any GameBoy or GameBoy Advance games.
The author cannot be held responsible for anything this program will do to your computer, brains, free time, housemates, pets, or family members.

New in This Version

Added JEDEC FlashROM support.
Added CRC/CMP check. All failing cartridges will now be rejected unless you use the -nocrc option.
Implemented pending IRQ handling after IRQs were switched on.
Disabled IRQs in the SVC mode.
Added ObjAffineSet() BIOS call.
Added Halt() and Stop() BIOS calls.
Fixed several BIOS calls.
Fixed a special case of DMA with the length of 0 items.
Fixed LDR/STR/LDRB/STRB instruction display in the debugger.
Improved cartridge information reporting.
Added a lot of command line options.
Added a lot of control keys.

History

New in Version 0.5

Moved dummy GBA.ROM contents inside the VGBA code.
Added DMA3 start at the beginning of HRefresh.
Added 'v' command to the debugger to show GBA status.
Fixed transparency effects in bitmap modes.
Fixed transparency with multiple backgrounds.
Now initializing rotation/scaling properly.
No longer supporting 128kB flash ROM above the cartridge ROM.

New in Version 0.4

Added MULL/MLAL ARM opcodes.
Added color effects to all screen modes.
Added rotation to all appropriate screen modes.
Added rotation to sprites.
Fixed DMA transfers to start correctly.
Fixed DMA transfers to leave correct values in DMACONT registers.
Added IRQ at the end of DMA transfer, if required.
Fixed GB sound chip emulation.
Added CPUSet() and CPUFastSet() BIOS calls.
Added RLUnCompWRAM() and RLUnCompVRAM() BIOS calls.
Now saving cartridge SRAM and flash ROM into a .SAV file.
Both 16bit color and 8bit color versions are included. 16bit version requires VESA-compatible video card. I still recommend it over the 8bit version as GBA programs are extremely ugly in 256 colors :)

What is It?

This is a pre-release version of the GameBoy Advance emulator I am working on. It will run a few GBA games, albeit somewhat sluggishly and with a few glitches. It will also run correctly written homebrewn demos. You can always get the latest version of VGBA at

http://www.komkon.org/fms/VGB/

I am mainly releasing this version of VGBA for game developers and demo programmers who would like to start coding for GBA but cannot afford to buy an official development kit from Nintendo. VGBA is not a replacement for the real development kit though, as it does not emulate all GBA features. I hope that the number of supported features will increase with time and your help.

How to Use It?

This release of VGBA has been compiled to run with PMODE/W extender on MSDOS (external extender not required). It will also run on Windows 95/98/ME. I have not tested it on Windows NT/2000, but other people told me that it runs on Windows 2000. The future releases will run on multiple platforms. There are two versions of VGBA included into this distribution:

VGBA8.EXE uses 320x200x8bit screen mode supported by the standard VGA BIOS. It should run on any computer, but is limited to 256 colors. Thus, the colors may sometimes look incorrect.
VGBA16.EXE uses 320x200x16bit VESA screen mode. Therefore, the VESA drivers are necessary to run this version of VGBA. It will fail on your computer if you do not have VESA drivers that support the 320x200x16bit screen mode.

Start VGBA with the following command line:

VGBA.EXE [-option1 [-option2...]] [FILENAME.GBA]

VGBA will load FILENAME.GBA at address 0x08000000 and start execution. You can exit the emulator by pressing ESCAPE or F12 keys. To break execution and drop into the debugger press F1 key. To make VGBA break when execution reaches some address, use the -trap <address> option, where address is a hexadecimal number. To make VGBA go into debugger right away, use -trap now option.

If you run VGBA.EXE without any arguments, it will show the list of all available options and key assignments:

Options:
  -uperiod <period>   - Number of interrupts per screen update [1]
  -verbose <level>    - Select debugging messages [1]
                         0 - Silent          1 - Startup messages
                         2 - I/O accesses    4 - Illegal memory accesses
                         8 - DMA transfers  16 - Illegal CPU ops
                        32 - SWI calls      64 - FlashROM accesses
  -crc/-nocrc         - Check cartridge CRC/CMP [-crc]
  -logsnd <filename>  - Write soundtrack to a MIDI file [LOG.MID]
  -sound [<quality>]  - Sound emulation quality [44100]
                        0 - Off                1 - Adlib (MSDOS)
                        Values >8191 are treated as wave synthesis
                        frequencies. Default frequency is 44kHz.
  -nosound            - Same as '-sound 0'
  -trap <address>     - Trap execution when PC reaches address [FFFFh]
                        When a keyword 'now' is used in place of the
                        <address>, execution will trap immediately.
  -vsync              - Sync screen updates to VBlank [-nosync]
  -sync <frequency>   - Sync screen updates to <frequency> [-nosync]
                        (<frequency> must be in 20Hz..100Hz range)
  -nosync             - Do not sync screen updates

Keyboard Bindings:
  [SPACE]    - A button (also: [LALT],A,S,D,F,G,H,J,K,L)
  [LCONTROL] - B button (also: Z,X,C,V,B,N,M)
  [Q]        - LEFT button (also: E,T,U,O)
  [W]        - RIGHT button (also: R,Y,I,P)
  [TAB]      - SELECT button
  [ENTER]    - START button
  [ESC]      - Quit emulation (also: [F12])
  [F1]       - Go into the built-in debugger
  [F2]       - Turn soundtrack logging on/off
  [F3]       - Turn A button autofire on/off
  [F4]       - Turn B button autofire on/off
  [F5]       - Turn LEFT button autofire on/off
  [F6]       - Turn RIGHT button autofire on/off
  [F11]      - Reset GBA hardware
  [F12]      - Quit emulation (also: [ESC])
  [0]        - Turn all sound on/off
  [1]-[4]    - Turn sound channels on/off
  [5]-[8]    - Turn backgrounds display on/off
  [9]        - Turn sprites display on/off

What is Emulated?

This version of VGBA has emulation for the following:

ARM7TDMI CPU with ARM and THUMB opcode sets.
Internal RAM at addresses 0x03000000 (32kB) and 0x02000000 (256kB).
Cartridge ROM at address 0x08000000 mirrored at 0x09000000 and 0x0A000000.
Cartridge RAM at address 0x0E000000 (64kB).
Cartridge FlashROM (JEDEC) at address 0x0E000000 (64kB).
Interrupts: VBlank, HBlank, line coincidence, timers, DMA, joypad.
Timers: TIMER0, TIMER1, TIMER2, TIMER3.
DMA channels: DMA0, DMA1, DMA2, DMA3.
DMA modes (instantaneous, HBlank, VBlank, HRefresh) and repeat feature.
Joypad buttons and interrupts.
GameBoy-compatible melodic sound chip.

Not emulated:

CPU timings are not correct. All ARM commands are assumed to take two clocks. All THUMB commands take one clock.
DMA happens "instantly".
Cartridge serial EEPROM (9851) is not emulated.
GBA-specific sound hardware is not emulated.

GBA video subsystem is extremely complicated not completely emulated in the VGBA. Both text backgrounds and rotation backgrounds are emulated, in the correct order, for modes 0..2. High color modes 3..5 and sprites also work:

Feature	Text BGs	Rotation BGs	MODE 3	MODE 4	MODE 5	Sprites
Variable Size	YES	YES	N/A	N/A	N/A	YES
Tile Flipping	YES	N/A	N/A	N/A	N/A	YES
16/256-Color Tiles	YES	N/A	N/A	N/A	N/A	YES
Scrolling	YES	N/A	N/A	N/A	N/A	N/A
Mosaic	YES	YES	YES	YES	YES	rotated sprites only
Rotation	N/A	YES	YES	YES	YES	YES
Window	NO	NO	N/A	N/A	N/A	NO
Color Effects	YES	YES	YES	YES	YES	YES

GBA BIOS is partly emulated. Including the real Nintendo BIOS with the emulator would be clearly illegal. Therefore, I have tried to simulate GBA BIOS routines by trapping and handling ARM SWI opcodes. Here is the correspondence between BIOS call names and SWI numbers:

Function	SWI #	Supported
BIOS_SoftReset	0x00	Yes
BIOS_RegisterRAMReset	0x01	Yes
BIOS_Halt	0x02	Yes
BIOS_Stop	0x03	Yes
BIOS_IntrWait	0x04	Yes
BIOS_VBlankIntrWait	0x05	Yes
BIOS_Div	0x06	Yes
BIOS_DivARM	0x07	Yes
BIOS_Sqrt	0x08	Yes
BIOS_ArcTan	0x09	Yes
BIOS_ArcTan2	0x0A	Yes
BIOS_CPUSet	0x0B	Yes
BIOS_CPUFastSet	0x0C	Yes
BIOS_BgAffineSet	0x0E	No
BIOS_ObjAffineSet	0x0F	Yes
BIOS_BitUnPack	0x10	No
BIOS_LZ77UnCompWRAM	0x11	Yes
BIOS_LZ77UnCompVRAM	0x12	Yes
BIOS_HuffUnComp	0x13	No
BIOS_RLUnCompWRAM	0x14	Yes
BIOS_RLUnCompVRAM	0x15	Yes
BIOS_Diff8bitUnFilterWRAM	0x16	No
BIOS_Diff8bitUnFilterVRAM	0x17	No
BIOS_Diff16bitUnFilter	0x18	No
BIOS_SoundBiasChange	0x19	No
BIOS_SoundDriverInit	0x1A	No
BIOS_SoundDriverMode	0x1B	No
BIOS_SoundDriverMain	0x1C	No
BIOS_SoundDriverVSync	0x1D	No
BIOS_SoundChannelClear	0x1E	No
BIOS_MIDIKey2Freq	0x1F	No
BIOS_MusicPlayerOpen	0x20	No
BIOS_MusicPlayerStart	0x21	No
BIOS_MusicPlayerStop	0x22	No
BIOS_MusicPlayerContinue	0x23	No
BIOS_MusicPlayerFadeOut	0x24	No
BIOS_MultiBoot	0x25	No
BIOS_SoundDriverVSyncOff	0x28	No
BIOS_SoundDriverVSyncOn	0x29	No

Notes to Demo Authors

This version of VGBA no longer simulates bugs of the previous emulators (such as GBAEmu written by Tim Schuerewegen). This means that many demos that made use of those bugs will not work on VGBA. But then, they would not work on the real GBA hardware either. Following is a list of problems that I've found. If you are a demo author, please, check your demos for these problems and fix them:

Many demos use random areas of address space for RAM. Apparently, GBAEmu will create RAM at any address accessed by the program. The real GBA (according to the latest specification) is only going to have RAM at addresses 0x03000000 (32kB) and 0x02000000 (256kB). Use only this memory.
Many demos use cartridge address space (0x08000000 and up) as RAM. This is not correct as cartridge ROM is not writable. Please, use RAM areas described above.
In graphical screen modes (MODEs 3,4,5) the entire screen is treated as background #2. This means that to actually show the screen you have to enable background #2 in DISPCONT and set appropriate bits in BG2CONT.
The backgrounds are shown in the order 0,1,2,3, with background #0 being on top and background #3 on the bottom. When you set different background priorities, the backgrounds with lower priorities will be on top.
When using ARM data comparison opcodes, you should always set the S flag in the opcode. In fact, ARM7TDMI programming manual explicitely requires this.
At least two demos (FireDemo and ConsoleDev Demo) are using reads from non-aligned addresses. While non-aligned reads are a documented feature of ARM7TDMI CPU, they are rarely used and cannot be efficiently simulated. The current VGBA binary has been compiled to be compatible with these demos. In the next version, I hope to use fast read functions that speed up emulation but do not simulate non-aligned reads.
Older (pre-TS2) development boards from Nintendo had hardware different from the later boards (TS2 and up). VGBA will not correctly run some programs compiled for TS1, such as programs using interrupts.

Thanks

I would like to thank people from the EFNet #GBADEV IRC channel for their help locating GBA specifications and testing the emulator.

Virtual GameBoy Advanceversion 0.6