Welcome to version 1.7.2 of VisualBoyAdvance [SDL]. This is a GB/GBC/GBA emulator for Windows, Linux, MacOS X and BeOS.

Features

• configurable GB/GBA keys, including joystick support
• option to use BIOS file
• zip/gzip file support
• directory selection for save state, battery and screen capture
• fullscreen mode (selectable resolution)
• video sizes 1x, 2x, 3x and 4x
• graphic filters Normal, TV Mode, 2xSaI, Super 2xSaI and more
• interframe blending support
• same emulation core as VisualBoyAdvance: GB and GBA emulation
• built-in ARM/THUMB assembly debugger
• 10 save states accesible through keyboard
• automatic battery file load/save
• auto-fire support
• pause, reset through keyboard
• 16, 24 and 32 bit desktop support
• GDB remote debugging (see below for information)
• auto frameskipping and throttle
• AGBPrint support for development
• RTC support

Compiling the sources

See the INSTALL file for compiling instructions. Please note the following requisites to compile:

• GCC must be 3.x or greater in order to compile GBA.cpp with -O2. Earlier versions have a problem during optimization that requires an absurd ammount of memory and usually ends up crashing the compiler/computer
• On Windows, Microsoft Visual C++ 6 or later is needed. Please note that some of the source code will not compile with the shipped header files. You will need to install the most recent Platform SDK from Microsoft.

Installing

The easiest installation is to place all files in the distribution in the same directory.

Per game settings

Version 1.5 introduced the support for per game settings for GBA games. You can defined the following settings on a per game basis by using an INI file called vba-over.ini in the same directory as the emulator:

rtcEnabled=<0 for false, anything else for true> flashSize=<65536 or 131072> saveType=<0 for automatic, 1 for EEPROM, 2 for SRAM, 3 for Flash or 4 for EEPROM+Sensor>

Use the 4 letter game code to separate settings for each game. Example:

[ABCD] rtcEnabled=0 flashSize=65536 saveType=0

[ABC2] rtcEnabled=1 flashSize=131072 saveType=0

Support

Please support VisualBoyAdvance by making a donation. You can donate money using PayPal (www.paypal.com). Use the contact form to find how you can send donations. Also, it is recommended that you use the VisualBoyAdvance forum on www.ngemu.com message board.

FAQ

See online FAQ for more information: http://vba.ngemu.com/faq.shtml

Please don't email about what you think it is problem before consulting the FAQ.

System requirements

Windows: PIII 500Mhz machine for GBA emulation. GB emulation requires far less.

Linux, MacOS X, BeOS: SDL (>= 1.2.2) runtime library must be installed prior to running the program. You can download it from http://www.libsdl.org

Key combinations during emulation

• F1...F10: load save state 1...10
• Shift+F1...F10: save state 1...10
• Alt+1...4: auto-fire A,B,L,R
• Ctrl+1...8: enable/disable graphical layers (BG0, BG1, BG2, BG3, OBJ, WIN0, WIN1, OBJWIN)
• Ctrl+N: pause on next frame
• Ctrl+R: reset
• Ctrl+P: pause
• Ctrl+B: rewind (if enabled and available)
• F11: enter built-in debugger
• ESC: exit emulator

Emulation key settings

• Movement: arrow keys
• Button A: Z
• Button B: X
• Button L: A
• Button R: S
• Button Start: ENTER
• Button Select: BACKSPACE
• Speed up: SPACE
• Screen capture: F12
• Motion Left: NUMPAD 4
• Motion Right: NUMPAD 6
• Motion Up: NUMPAD 8
• Motion Down: NUMPAD 2

GDB support

VisualBoyAdvance now provides GDB remote debugging support. This gives developers the full power of GDB to debug GBA applications.

In order to use this, you will need a cross-compiled GDB for either the arm-elf or arm-thumb-elf target (used for the --target= option of GDB configure script).

You can also use GDB frontends like DDD, CodeMedic, etc... or even GDB/Insight for GUI debugger (if using anything other than GDB/Insight, please make sure to point to the right GDB executable).

The emulator provides two transport protocols for remote debugging:

• TCP: allows debugging through TCP using port 55555 (or any specified) port. The advantage of using TCP is that it allows true remote debugging but it is slower compared to the pipe method (pipe method does not work on Windows - probably a restriction imposed by the CYGWIN port of GDB).
• PIPE: allows debugging through a PIPE between the emulator and GDB. This is a lot faster than TCP and recommened on Unix systems.

Using TCP transport

To use the TCP transport, use the flag -Gtcp[:portnum] where portnum is an optional port number to be used instead of 55555. VBA will wait for a GDB connection on the specified port (printed on screen). Start GDB by passing the .elf file, then connect to the emulator by using the command:

target remote :

where hostname is the host where the emulator is running and port number is the printed port number.

Using PIPE transport

To use the PIPE transport, start GDB with the .elf file to be debugged. Connect to the emulator by using the command:

target remote |/VisualBoyAdvance -Gpipe

Debugging with GDB

Once you connected to the emulator, you can set breakpoints and debug the application. But before doing that, you will need to issue the loda command on GDB to load the code into the emulator. Optionally, you can pass the ELF file on the emulator's command line (along with the -N option to not parse the debug information in the emulator) instead of issuing the load command.

After connecting and optionally loading the file into the debugger, you can start debugging: add breakpoints, step, etc...

While using GDB, any console output (see below) will show up in GDB's console.

If you want to break into the GDB, press F11 and it will give you full command in GDB again. Pressing ESC will terminate emulation.

You can also detach GDB from the emulator.

Console Output

There are two forms of console output in this version:

• Mappy style dprint: use the following code (from Mappy's documentation) to get output:

• VBA style: use the following code to get output: // THUMB code void print(char s) { asm volatile("mov r0, %0;" "swi 0xff;" : // no ouput : "r" (s) : "r0"); } // ARM code void print(char s) { asm volatile("mov r0, %0;" "swi 0xff0000;" : // no ouput : "r" (s) : "r0"); }

When using GDB, the output will show up in GDB's console. When using the built-in debugger, output will go to standard out.

Built-in debugger enhancements

The built-in debugger has the following enhancements (need debug enabled ELF file):

• ELF file support: both multiple and regular. Please report any messages or problems reading ELF files. C++ classes and some miscellaneous features are not supported yet. Also, method names may be mangled in C++ code.
• break command: add a breakpoint on a function, line number of file:line number
• locals command: print the local variables on the current function
• print command: prints the value of a given expression. Valid expression include *this, ptr->member, var.member, array[0], sizeof(expression), etc...
• symbols command: list information known about a symbol (or symbols that start with the given name)
• radix command: sets the output radix to eithe decimal, octal or hex.
• file and line number when stopped: the debugger will show the file and line number (if available) for the current address
• fixes to some breakpoint handling problems
• fixes to break on write function

Profiling

VisualBoyAdvance has profiling support. It produces output in the format supported by GPROF. You need a cross-compiled binary of GPROF (binutils GNU package) compiled with --target=arm-thumb-elf (or similar).

The output will always contain the histogram of PC positions at the specified frequency even if the code is not compiled with call graph support.

In order to enable profiling, you need to add a call inside your code to start it (download vba.s for a ready to use file for GCC):

void monstartup(u32 lowPC, 32 highPC)

This will start profiling for the given address region. If the code was also compiled with -pg, call graphs will be recorded.

Other calls for fine grain control:

// control profiling // 0 - stops profiling // anyother value starts it void moncontrol(int mode)

// stop profiling and output gmon.out file void moncleanup()

// record call graph (used by GCC) // r12 contains previous caller // r14 contains function that was called void mcount()

GCC bugs

All versions of GCC previous to the working version 3.3 have bugs when generating profiling for thumb functions.

The errors are:

• mov\tip,lr not a valid instruction (typo in gcc/config/arm/arm.h)
• LPxx undefined when linking (missing . before LP causes the problem)

You can fix these problems by either recompiling GCC (recommended) or by modifying cc1.exe to fix the problems.

In the first option, find the given code in gcc/config/arm/arm.h and fix the typos (remove the extra blackslash from the mov ip,lr instruction and add the missing dot before LP%d) or change THUMB_FUNCTION_PROFILER to call ARM_FUNCTION_PROFILER (the recent changes that were performed in CVS).

If you don't want to compile your own GCC, then you can use an hex editor to fix the problems. Locate cc1.exe under

VisualBoyAdvance - a Gameboy and GameboyAdvance emulator
Copyright (C) 1999-2003 Forgotten
Copyright (C) 2004 Forgotten and the VBA development team

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA