# Virtual GameBoy Advance
version 1.0

### by Marat Fayzullin

# Contents

- Disclaimers
- New in This Version
- History
- Introduction
- VGBA Ports
- Registered Users
- What is Included
- What is not Included
- Buttons
- Command Line Options
- Frequently Asked Questions
- Notes to Demo Authors
- Thanks

# 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

- VGBA-Windows is now available. Register it NOW!
- VGBA-Unix is now available.
- Added facility to save and load emulation state.
- Added serial EEPROM emulation.
- Implemented more or less accurate CPU cycle counting (still not accurate enough though).
- Implemented HuffUncomp() call.
- Fixed ObjAffineSet(), CpuSet(), CpuFastSet(), and SoftReset() calls.
- Fixed timers to reload values correctly.
- Majorly updated documentation.
- Fixed background color problem in the non-VESA (256 color) version of VGBA-MSDOS.

# History

## New in Version 0.6

- 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.

## 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 :)

# Introduction

Virtual GameBoy Advance (VGBA) is a portable emulator of the GameBoy Advance handheld videogame console from Nintendo. In its current state, VGBA allows to run some of the commercial GameBoy Advance software on a personal computer. It will also run correctly written homebrewn demos. You can always get the latest version of VGBA at

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

VGBA is a logical continuation of my previous work on the videogame console emulators, namely, the Virtual GameBoy (GameBoy Classic, GameBoy Pocket, Super GameBoy, and GameBoy Color emulator). VGBA is completely different from VGB though. It will not run original GameBoy software, you will have to use VGB for that.

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.

# VGBA Ports

So far, I have ported VGBA to MSDOS, Windows, and Unix. All three ports are maintained by myself. You should expect more versions to come up soon, as porters receive the VGBA core code and work on it.

## Windows 95/98/ME/NT/2000

  The Windows version of VGB is available from me, Marat Fayzullin, for $35US. This fee ensures that you will get you the latest full version of VGBA-Windows with free updates via email as long as VGBA-Windows is being updated. For more information about it, take a look at

  http://www.komkon.org/fms/VGBA/VGBAWindows.html

  You can register VGBA-Windows by one of the following methods:

  ORDER BY MAIL
    Send $35US in cash, money order, or a US bank check to:

             Marat Fayzullin
             6304 Hampton Place
             Elkridge, MD 21075
             USA

    Don't forget to include your email address and mention that you want VGBA-Windows, as I'm selling several other products as well. The software will be emailed to you as soon as I receive the money.

  ORDER ON THE WEB
    Tell your WWW browser to go to

    http://www.digibuy.com/cgi-bin/order.html?296825+99046733021

    and use the online form to register VGBA-Windows. You can pay with a credit card. They take MasterCard, Visa, Amex, or Discover and also allow to register over the phone. The software will be emailed to you as soon as I receive the notification from DigiBuy.

## MSDOS

  The first (<1.0) versions of VGBA were released for MSDOS. You may find them on the Net for free, but they lack the compatibility and features of the later versions. VGBA-MSDOS 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 MSDOS distribution includes two flavors of VGBA:

  - `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.

## Unix

# Registered Users

If you've bought VGBA-Windows, please do not give your copy to anybody. And I do mean anybody. There was a couple of cases when registered users gave my programs away to their friends, relatives, or just "KeWl" guys on the Net, and then I found my work pirated, put onto WWW pages, and even posted to USENET newsgroups. If I find your personalized copy of VGBA being spread around, your registration gets automatically cancelled which means no support and no more updates.

I understand that the previous paragraph may sound threatening to some people, but this kind of piracy really hurts my profits and feelings. I've put a lot of effort into VGBA, and can only continue working on it if people do not try to cheat on me.

It may also be a good idea to buy a real cartridge for each GameBoy Advance ROM image you use with the emulator. GameBoy Advance software is copyrighted, but as long as you own the real cartridge, you are protected by the law allowing customers to backup bought software.

# What is Included

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 `0x0A000000` and `0x0C000000`.
- Cartridge RAM at address `0x0E000000` (64kB).
- Cartridge FlashROM (JEDEC) at address `0x0E000000` (64kB).
- Cartridge serial EEPROM at address `0x09000000` (64x64bits), mirrored at `0x0B000000` and `0x0D000000`.
- 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:

- GBA-specific sound hardware is not emulated.
- DMA happens "instantly".
- CPU timings are close but not entirely correct. VGBA considers all memory accesses as "sequential". There are some other discrepancies as well, but overally, it should be pretty close.

GBA video subsystem is extremely complicated and still not completely emulated in the VGBA. I am hoping to complete the emulation in later versions. Here is a list of emulated features:

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 | Yes
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

# What is not Included

Absolutely no ROM images of commercial GameBoy Advance games are included. These games are copyrighted by the companies which produced them, and therefore, I cannot distribute any of these games. I'm also unable to tell you where to find the games, so do not send me email asking for them. You will have to look for them on your own.

The VGBA WWW page contains some links to GameBoy Advance cartridge copier info. Cartridge copiers can be used to dump GameBoy Advance cartridges into files. I cannot provide you with any additional information about these copiers, so do not send me email asking for this information. Use the copier-related links at the VGBA WWW page.

GameBoy Advance has a BIOS ROM inside with some useful subroutines. Including the real Nintendo BIOS with the emulator would be clearly illegal. Therefore, VGBA tries to simulate GBA BIOS routines. It still has an option to use the real BIOS read from the `GBA.ROM` file in the current directory. I cannot tell you where to find the real BIOS, so do not ask me about it. The BIOS simulation is quite functional and will become better over time.

# Buttons

These button assignments apply to all three VGBA ports developed by myself. They will work in Windows, Unix, and MSDOS.

      [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
      [F7]       - Save emulation state to .STA file
      [F8]       - Load emulation state
      [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

# Command Line Options

Start VGBA with the following command line:

    vgba [-option1 [-option2...]] [FILENAME.GBA]

When no cartridge name is given, VGBA will print the list of keyboard assignments and available command line options. Following is a list of options supported in VGBA-MSDOS and VGBA-Unix. VGBA-Windows only accepts the cartridge name.

      -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/EEEPROM accesses
      -crc/-nocrc         - Check cartridge CRC/CMP [-crc]
      -logsnd <filename>  - Write soundtrack to a MIDI file [LOG.MID]
      -sync <frequency>   - Sync screen updates to <frequency> [-nosync]
                            (<frequency> must be in 20Hz..100Hz range)
      -nosync             - Do not sync screen updates

    With #define SOUND:
      -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'

    With #define DEBUG:
      -trap <address>     - Trap execution when PC reaches address [FFFFh]
                            When a keyword 'now' is used in place of the
                            <address>, execution will trap immediately.

    With #define MSDOS:
      -vsync              - Sync screen updates to VBlank [-nosync]

    With #define UNIX:
      -saver/-nosaver     - Save CPU when inactive [-saver]
      -scale <factor>     - Scale window by <factor> [1]

    With #define MITSHM:
      -shm/-noshm         - Use MIT SHM extensions for X [-shm]

# Frequently Asked Questions

1. I WANNA PLAY GAMES!!!! WHERE DO I GET GAMES???????
   I do not know. I can't give you any due to both legal and moral reasons. Please, do not mail me asking for games. I will delete your mail right away, and you won't get an answer.

2. Can I play GameBoy Classic and GameBoy Color games on VGBA?
   No, you can't. GameBoy Advance hardware is completely different from the older GameBoy and GameBoy Color models. To play older games, you may want to consider my other emulator, Virtual GameBoy (VGB) .

3. How do I copy games from cartridges to a computer?
   You can use a special device called cartridge copier, such as Flash Advance Linker from Lik-Sang. Don't forget to get a rewritable flash card too.

4. What is GameBoy Advance? How its hardware works?
   GameBoy Advance (GBA) is a handheld videogame machine made by Nintendo. Its hardware has nothing to do with GameBoy and GameBoy Color handhelds previously produced by Nintendo. GBA is built around an ARM7TDMI 32bit CPU running at 16MHz. GBA video subsystem is very similar to that of SNES, but more advanced. The sound subsystem uses direct sample output. GBA also includes the four-channel melodic sound chip from the original GameBoy.

   In order to be compatible with the original GB/GBC, GBA includes the complete set of GBC hardware. This hardware (aside from the sound chip) is not accessible from the GBA side and only used when somebody inserts a GB/GBC cartridge into GBA.

5. There is no version of VGBA for my Unix!
   I am trying to compile Unix binaries for as many flavors of Unix as possible, but as I do not have access to many machines, do not expect immediate support for every Unix flavor out there. Don't mail me asking for the source either: VGBA source code is not publicly distrbutable, as much as I regret to say this :(.

6. My favorite game doesn't work on VGBA. What do I do?
   There may be several reasons why a game has problems running on VGBA or does not run at all.

   - If emulator does not even recognize the ROM image, its CRC or CMP may be wrong. Try turning CRC checking off by using the `-nocrc` option or clearing "Check CRC" checkbox in VGBA-Windows Setup Panel. You really need to find an uncorrupted ROM image though.

   - If some sprites blink or do not appear at all, try changing `-uperiod` value (1 will give you the best picture, but the slowest emulation), or moving an "Update Period" knob in the VGBA-Windows Setup Panel.

   - VGBA may not currently run this game. Not all games are supported at this moment. Don't expect 100% compatibility with the real hardware. At least, not yet :).

7. There is no sound!
   Currently, VGBA only emulates the four channels of the melodic sound that GBA has inherited from the original GameBoy. Unfortunately, most GBA games use the "direct" sample sound that is not emulated in VGBA. I hope to emulate this GBA feature in the later VGBA versions.

8. Why is VGBA so slow on my machine?
   Because your machine is too slow to run VGBA. My experience shows that you need at least a PentiumII/400 machine with fast video to run VGBA at a reasonable speed. Following are the ways to speed things up:

   - Increase Update Period. The picture will get more jerky, but VGBA will become faster.

   - On Unix, always use MIT Shared Memory Extension for X (MITSHM). This, of course, means that you have to run VGB locally.

   - On Unix, run X in 256-color mode.

   - On Windows and Unix, use 1:1 window to achieve the highest speed.

   - On Windows, use MIDI sound, as wave synthesis takes quite a lot of CPU time.

9. VGBA is too fast on my machine! How do I slow it down?
   Frankly, when I started writing VGBA, I never expected that it will be too fast on any machine :). But times change...

   - On Unix, use `-sync` option to tie screen updates to the certain frequency (usually, 60Hz/UPeriod).

   - On Windows, use "Sync To..." option in the Setup Panel to tie screen updates to a certain frequency (usually, 60Hz divided by UPeriod).

   - Decrease Update Period to 2 or even to 1. The emulation will become much slower, but smoother.

   - On Windows and Unix, double or triple the window size.

10. When starting VGBA-Unix, ld says that some library isn't found.
    This may happen if the versions of your shared libraries are older than the ones for which VGBA has been compiled. A decent way to deal with this is to upgrade your Unix. A quick and dirty way is to make a symbolic link from the existing library to a name required by VGBA.

11. When starting VGBA-Unix, I get X_ShmAttach error.
    You are probably trying to run VGBA-Unix on a remote Xterminal while it attempts to use shared memory for interfacing with X. Use `-noshm` option to tell it not to use shared memory.

12. When starting VGBA-Unix, I get X_PutImage error.
    VGBA-Unix version currently needs 8bit, 16bit, or 32bit X. Neither 2-color nor 16-color Xterminals will work. 24bit Xterminals may work, but don't count on it.

13. When starting VGBA-Unix, the window stays black.
    Some other X application took over all available colors so that the emulation could not allocate any for itself. Check if you run XV, Netscape, or something similar.

14. The sound is distorted in the VGBA-Windows. How do I fix it?
    The wave-synthetized sound in VGBA may become distorted on slow or highly loaded machines (no graphics acceleration, for example). There are several ways you can improve sound:

    - Use MIDI sound instead. It has both advantages and disadvantages though.

    - Make VGBA window smaller to decrease the load on the CPU. 1:1 is the optimal size.

    - Decrease the sampling frequency (in Setup Panel). The sound may become tinkier, but less distorted.

    - Increase the number of wave buffers (in Setup Panel). This may cause sound to fall a second or two behind the screen action, but the sound quality will become better.

15. Does VGBA-Windows support joystick? My joystick doesn't work!
    VGBA-Windows supports joystick. If your joystick does not work, go into Windows Control Panel to see if it is configured and calibrated properly. Also, some new joysticks working in esoteric standards (like GRiP) are known to have problems.

16. VGBA-Windows starts, but then quits immediately!
    Check the pathname to wherever your VGBA is located. It should not contain spaces. For example, "C:\Program Files\VGBA" is a bad place for VGBA, while "C:\VGBA" will work. This bug is caused by an old version of C compiler I am using. I hope to get rid of it when I switch to a new compiler.

17. Colors are all screwed up in VGBA-Windows!
    VGBA-Windows requires Windows to be in 65536-color or better color mode. When running Windows in 256-color mode, it will try to approximate colors to existing ones, but expect results to be dismal.

18. Black window in VGBA-Windows!
    If you are running Windows in 256-color mode, then this is most likely the cause of a problem. Try switching Windows into 65536-color or better screen mode.

19. Command line options don't work in VGBA-Windows!
    They shouldn't. The demo version of VGBA-Windows supports no command line interface at all. The full version will only accept the .GBA file name at the command line, but no options. All configuration is done via Setup Panel and VGBA.INI file.

20. Volume control works strangely in VGBA-Windows!
    It is a result of the volume control being shared between VGBA and other Windows applications. You can usually restore normal volume by leaving VGBA window and then activating it again.

21. How do I save and load the GBA state during the game?
    The GBA state can be saved by pressing [F7] button. The resulting data file will have the same name as your .GBA file, but its extension is going to be .STA. You can load state from this file by pressing [F8] at any point in the game. This state file will also be loaded automatically next time you start VGBA. The same state file is not guaranteed to work for versions of VGBA running on a different hardware. State saving is not perfect yet, so for some games state may not be correctly saved.

# 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:

- Prior to running the program, VGBA will check CMP and CRC of the ROM image. If they do not match CMP/CRC given in the cartridge header, VGBA will refuse to run the program. To make your program run, either fix CMP/CRC (preferable) or use the `-nocrc` option. Also, be aware that Nintendo requires CRC of a cartridge to be 0 i.e. your ROM image must have padding bytes somewhere that compensate CRC to be zero.
- 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.

© Copyright by Marat Fayzullin (fms@cs.umd.edu)