Permalink
| 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 <hostname>:<port number> | |
| 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 |<full path to VBA>/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 <dir>/lib/gcc-lib/<config>/<version> | |
| and find the mov\tip,lr instruction. Change the extra backslash to a space. | |
| Locate the .LP string just before the mov instruction and change it to | |
| .P instead (make sure to place 0 after the P). Then find the text .word | |
| LP%d and change it to .word .P%d. | |
| Histograms will be output even if the code is not compiled with call graph | |
| support. | |
| Options configuration | |
| --------------------- | |
| All configurable options are accessible from the configuration file | |
| VisualBoyAdvance.cfg. | |
| This file is searched in this order: | |
| - current directory | |
| - user home directory (defined by HOME environment variable) | |
| - user profile directory (Windows only defined by USERPROFILE directory) | |
| - executable directory (either relative or defined by PATH variable) | |
| All options are documented in the file supplied with this distribution. | |
| Command line options (override settings in configuration file) | |
| -------------------------------------------------------------- | |
| -1, --video-1x 1x | |
| -2, --video-2x 2x | |
| -3, --video-3x 3x | |
| -4, --video-4x 4x | |
| -F, --fullscreen Full screen | |
| -G, --gdb=PROTOCOL GNU Remote Stub mode: | |
| tcp - use TCP at port 55555 | |
| tcp:PORT - use TCP at port PORT | |
| pipe - use pipe transport | |
| -N, --no-debug Don't parse debug information | |
| -S, --flash-size=SIZE Set the Flash size | |
| --flash-64k 0 - 64K Flash | |
| --flash-128k 1 - 128K Flash | |
| -T, --throttle=THROTTLE Set the desired throttle (5...1000) | |
| -Y, --yuv=TYPE Use YUV overlay for drawing: | |
| 0 - YV12 | |
| 1 - UYVY | |
| 2 - YVYU | |
| 3 - YUY2 | |
| 4 - IYUV | |
| -b, --bios=BIOS Use given bios file | |
| -c, --config=FILE Read the given configuration file | |
| -d, --debug Enter debugger | |
| -f, --filter=FILTER Select filter: | |
| --filter-normal 0 - normal mode | |
| --filter-tv-mode 1 - TV Mode | |
| --filter-2xsai 2 - 2xSaI | |
| --filter-super-2xsai 3 - Super 2xSaI | |
| --filter-super-eagle 4 - Super Eagle | |
| --filter-pixelate 5 - Pixelate | |
| --filter-motion-blur 6 - Motion Blur | |
| --filter-advmame 7 - AdvanceMAME Scale2x | |
| --filter-simple2x 8 - Simple2x | |
| --filter-bilinear 9 - Bilinear | |
| --filter-bilinear+ 10 - Bilinear Plus | |
| --filter-scanlines 11 - Scanlines | |
| --filter-hq2x 12 - hq2x | |
| --filter-lq2x 13 - lq2x | |
| -h, --help Print this help | |
| -i, --ips=PATCH Apply given IPS patch | |
| -p, --profile=[HERTZ] Enable profiling | |
| -s, --frameskip=FRAMESKIP Set frame skip (0...9) | |
| -t, --save-type=TYPE Set the available save type | |
| --save-auto 0 - Automatic (EEPROM, SRAM, FLASH) | |
| --save-eeprom 1 - EEPROM | |
| --save-sram 2 - SRAM | |
| --save-flash 3 - FLASH | |
| --save-sensor 4 - EEPROM+Sensor | |
| --save-none 5 - NONE | |
| -v, --verbose=VERBOSE Set verbose logging (trace.log) | |
| 1 - SWI | |
| 2 - Unaligned memory access | |
| 4 - Illegal memory write | |
| 8 - Illegal memory read | |
| 16 - DMA 0 | |
| 32 - DMA 1 | |
| 64 - DMA 2 | |
| 128 - DMA 3 | |
| 256 - Undefined instruction | |
| 512 - AGBPrint messages | |
| Long options only: | |
| --agb-print Enable AGBPrint support | |
| --auto-frameskip Enable auto frameskipping | |
| --ifb-none No interframe blending | |
| --ifb-motion-blur Interframe motion blur | |
| --ifb-smart Smart interframe blending | |
| --no-agb-print Disable AGBPrint support | |
| --no-auto-frameskip Disable auto frameskipping | |
| --no-ips Do not apply IPS patch | |
| --no-mmx Disable MMX support | |
| --no-pause-when-inactive Don't pause when inactive | |
| --no-rtc Disable RTC support | |
| --no-show-speed Don't show emulation speed | |
| --no-throttle Disable thrrotle | |
| --pause-when-inactive Pause when inactive | |
| --rtc Enable RTC support | |
| --show-speed-normal Show emulation speed | |
| --show-speed-detailed Show detailed speed data | |
| Known bugs | |
| ---------- | |
| - loading a save state that uses a different sound quality may hang the | |
| emulator. Please only use the 22Khz sound quality save states from the | |
| Windows version with this release | |
| - built-in debugger still has a few bugs | |
| - disassembler contains a few errors. Please report anything wrong you find | |
| LICENSE | |
| ------- | |
| 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 | |
| This program also contains code developed by the University of | |
| California and is subject to the extra conditions: | |
| Copyright (c) 1991, 1998 The Regents of the University of California. | |
| All rights reserved. | |
| Redistribution and use in source and binary forms, with or without | |
| modification, are permitted provided that the following conditions | |
| are met: | |
| 1. Redistributions of source code must retain the above copyright | |
| notice, this list of conditions and the following disclaimer. | |
| 2. Redistributions in binary form must reproduce the above copyright | |
| notice, this list of conditions and the following disclaimer in the | |
| documentation and/or other materials provided with the distribution. | |
| 3. [rescinded 22 July 1999] | |
| 4. Neither the name of the University nor the names of its contributors | |
| may be used to endorse or promote products derived from this software | |
| without specific prior written permission. | |
| Contact | |
| ------- | |
| Please don't email unless you found some bug. Requests will be ignored and | |
| deleted. Also, be descriptive when emailing. You have to tell me what version | |
| of the emulator you are writing about and a good description of the problem. | |
| Remember, there are several interfaces (Windows, SDL and GTK+) and | |
| several systems (Windows, Linux, MacOS X and BeOS). | |
| Also, there are still people writing about the old VisualBoy which is no longer | |
| supported. Also remember I am not paid to work on VisualBoyAdvance. This is | |
| just a hobby. | |
| Forgotten (http://vba.ngemu.com/contact.shtml) | |
| kxu <kxu@users.sourceforge.net> | |
| http://vba.ngemu.com | |
| http://sourceforge.net/projects/vba | |
| Special Thanks | |
| -------------- | |
| PokemonHacker for all his help improving the emulator. | |
| Costis for his help fixing some of the graphics bugs. | |
| Snes9x developers for the great emulator and source code. | |
| Kreed for his great graphic filters. | |
| SDL team for this amazing library. | |
| And all users who kindly reported problems. |