README

   1 Welcome to version 1.8.0 of VisualBoyAdvance [SDL].
   2 This is a GB/GBC/GBA emulator for Windows, Linux, MacOS X and BeOS.
   3
   4 Features
   5 --------
   6
   7 - configurable GB/GBA keys, including joystick support
   8 - option to use BIOS file
   9 - zip/gzip file support
  10 - directory selection for save state, battery and screen capture
  11 - fullscreen mode (selectable resolution)
  12 - video sizes 1x, 2x, 3x and 4x
  13 - graphic filters Normal, TV Mode, 2xSaI, Super 2xSaI and more
  14 - interframe blending support
  15 - same emulation core as VisualBoyAdvance: GB and GBA emulation
  16 - built-in ARM/THUMB assembly debugger
  17 - 10 save states accesible through keyboard
  18 - automatic battery file load/save
  19 - auto-fire support
  20 - pause, reset through keyboard
  21 - 16, 24 and 32 bit desktop support
  22 - GDB remote debugging (see below for information)
  23 - auto frameskipping and throttle
  24 - AGBPrint support for development
  25 - RTC support
  26
  27 Compiling the sources
  28 ---------------------
  29
  30 See the INSTALL file for compiling instructions. Please note the following
  31 requisites to compile:
  32
  33 - GCC must be 3.x or greater in order to compile GBA.cpp with -O2. Earlier
  34   versions have a problem during optimization that requires an absurd
  35   ammount of memory and usually ends up crashing the compiler/computer
  36 - On Windows, Microsoft Visual C++ 6 or later is needed. Please note that
  37   some of the source code will not compile with the shipped header files.
  38   You will need to install the most recent Platform SDK from Microsoft.
  39
  40 Installing
  41 ----------
  42
  43 The easiest installation is to place all files in the distribution in the
  44 same directory.
  45
  46 Per game settings
  47 -----------------
  48
  49 Version 1.5 introduced the support for per game settings for GBA games. You
  50 can defined the following settings on a per game basis by using an INI file
  51 called vba-over.ini in the same directory as the emulator:
  52
  53 rtcEnabled=<0 for false, anything else for true>
  54 flashSize=<65536 or 131072>
  55 saveType=<0 for automatic, 1 for EEPROM, 2 for SRAM, 3 for Flash or 4 for
  56 EEPROM+Sensor>
  57
  58 Use the 4 letter game code to separate settings for each game. Example:
  59
  60 [ABCD]
  61 rtcEnabled=0
  62 flashSize=65536
  63 saveType=0
  64
  65 [ABC2]
  66 rtcEnabled=1
  67 flashSize=131072
  68 saveType=0
  69
  70 Support
  71 -------
  72
  73 Please support VisualBoyAdvance by making a donation. You can donate money
  74 using PayPal (www.paypal.com). Use the contact form to find how you can
  75 send donations. Also, it is recommended that you use the VisualBoyAdvance
  76 forum on www.ngemu.com message board.
  77
  78 FAQ
  79 ---
  80
  81 See online FAQ for more information: http://vba.ngemu.com/faq.shtml
  82
  83 Please don't email about what you think it is problem before consulting
  84 the FAQ.
  85
  86 System requirements
  87 -------------------
  88
  89 Windows: PIII 500Mhz machine for GBA emulation. GB emulation requires far less.
  90
  91 Linux, MacOS X, BeOS:
  92   SDL (>= 1.2.2) runtime library must be installed prior to running the
  93   program. You can download it from http://www.libsdl.org
  94
  95 Key combinations during emulation
  96 ---------------------------------
  97
  98 - F1...F10: load save state 1...10
  99 - Shift+F1...F10: save state 1...10
 100 - Alt+1...4: auto-fire A,B,L,R
 101 - Ctrl+1...8: enable/disable graphical layers (BG0, BG1, BG2, BG3, OBJ, WIN0,
 102   WIN1, OBJWIN)
 103 - Ctrl+N: pause on next frame
 104 - Ctrl+R: reset
 105 - Ctrl+P: pause
 106 - Ctrl+B: rewind (if enabled and available)
 107 - F11: enter built-in debugger
 108 - ESC: exit emulator
 109
 110 Emulation key settings
 111 ----------------------
 112
 113 - Movement: arrow keys
 114 - Button A: Z
 115 - Button B: X
 116 - Button L: A
 117 - Button R: S
 118 - Button Start: ENTER
 119 - Button Select: BACKSPACE
 120 - Speed up: SPACE
 121 - Screen capture: F12
 122 - Motion Left: NUMPAD 4
 123 - Motion Right: NUMPAD 6
 124 - Motion Up: NUMPAD 8
 125 - Motion Down: NUMPAD 2
 126
 127
 128 GDB support
 129 -----------
 130
 131 VisualBoyAdvance now provides GDB remote debugging support. This gives
 132 developers the full power of GDB to debug GBA applications.
 133
 134 In order to use this, you will need a cross-compiled GDB for either the arm-elf
 135 or arm-thumb-elf target (used for the --target= option of GDB configure
 136 script).
 137
 138 You can also use GDB frontends like DDD, CodeMedic, etc... or even GDB/Insight
 139 for GUI debugger (if using anything other than GDB/Insight, please make sure
 140 to point to the right GDB executable).
 141
 142 The emulator provides two transport protocols for remote debugging:
 143
 144 - TCP: allows debugging through TCP using port 55555 (or any specified) port.
 145   The advantage of using TCP is that it allows true remote debugging but it is
 146   slower compared to the pipe method (pipe method does not work on Windows -
 147   probably a restriction imposed by the CYGWIN port of GDB).
 148 - PIPE: allows debugging through a PIPE between the emulator and GDB. This is a
 149   lot faster than TCP and recommened on Unix systems.
 150
 151 Using TCP transport
 152 -------------------
 153
 154 To use the TCP transport, use the flag -Gtcp[:portnum] where portnum is an
 155 optional port number to be used instead of 55555. VBA will wait for a GDB
 156 connection on the specified port (printed on screen). Start GDB by passing the
 157 .elf file, then connect to the emulator by using the command:
 158
 159 target remote <hostname>:<port number>
 160
 161 where hostname is the host where the emulator is running and port number is the
 162 printed port number.
 163
 164 Using PIPE transport
 165 --------------------
 166
 167 To use the PIPE transport, start GDB with the .elf file to be debugged. Connect
 168 to the emulator by using the command:
 169
 170 target remote |<full path to VBA>/VisualBoyAdvance -Gpipe
 171
 172 Debugging with GDB
 173 ------------------
 174
 175 Once you connected to the emulator, you can set breakpoints and debug the
 176 application. But before doing that, you will need to issue the loda command on
 177 GDB to load the code into the emulator. Optionally, you can pass the ELF file
 178 on the emulator's command line (along with the -N option to not parse the debug
 179 information in the emulator) instead of issuing the load command.
 180
 181 After connecting and optionally loading the file into the debugger, you can
 182 start debugging: add breakpoints, step, etc...
 183
 184 While using GDB, any console output (see below) will show up in GDB's console.
 185
 186 If you want to break into the GDB, press F11 and it will give you full command
 187 in GDB again. Pressing ESC will terminate emulation.
 188
 189 You can also detach GDB from the emulator.
 190
 191
 192 Console Output
 193 --------------
 194
 195 There are two forms of console output in this version:
 196
 197 - Mappy style dprint: use the following code (from Mappy's documentation)
 198   to get output:
 199
 200 - VBA style: use the following code to get output:
 201   // THUMB code
 202   void print(char *s)
 203   {
 204     asm volatile("mov r0, %0;"
 205                  "swi 0xff;"
 206                  : // no ouput
 207                  : "r" (s)
 208                  : "r0");
 209   }
 210   // ARM code
 211   void print(char *s)
 212   {
 213     asm volatile("mov r0, %0;"
 214                  "swi 0xff0000;"
 215                  : // no ouput
 216                  : "r" (s)
 217                  : "r0");
 218   }
 219
 220 When using GDB, the output will show up in GDB's console. When using the
 221 built-in debugger, output will go to standard out.
 222
 223 Built-in debugger enhancements
 224 ------------------------------
 225
 226 The built-in debugger has the following enhancements (need debug enabled ELF
 227 file):
 228 - ELF file support: both multiple and regular. Please report any messages or
 229   problems reading ELF files. C++ classes and some miscellaneous features are
 230   not supported yet. Also, method names may be mangled in C++ code.
 231 - break command: add a breakpoint on a function, line number of file:line
 232   number
 233 - locals command: print the local variables on the current function
 234 - print command: prints the value of a given expression. Valid expression
 235   include *this, ptr->member, var.member, array[0], sizeof(expression), etc...
 236 - symbols command: list information known about a symbol (or symbols that start
 237   with the given name)
 238 - radix command: sets the output radix to eithe decimal, octal or hex.
 239 - file and line number when stopped: the debugger will show the file and line
 240   number (if available) for the current address
 241 - fixes to some breakpoint handling problems
 242 - fixes to break on write function
 243
 244 Profiling
 245 ---------
 246
 247 VisualBoyAdvance has profiling support. It produces output in the format
 248 supported by GPROF. You need a cross-compiled binary of GPROF (binutils
 249 GNU package) compiled with --target=arm-thumb-elf (or similar).
 250
 251 The output will always contain the histogram of PC positions at the specified
 252 frequency even if the code is not compiled with call graph support.
 253
 254 In order to enable profiling, you need to add a call inside your code
 255 to start it (download vba.s for a ready to use file for GCC):
 256
 257 void monstartup(u32 lowPC, 32 highPC)
 258
 259 This will start profiling for the given address region. If the code was also
 260 compiled with -pg, call graphs will be recorded.
 261
 262 Other calls for fine grain control:
 263
 264 // control profiling
 265 // 0 - stops profiling
 266 // anyother value starts it
 267 void moncontrol(int mode)
 268
 269 // stop profiling and output gmon.out file
 270 void moncleanup()
 271
 272 // record call graph (used by GCC)
 273 // r12 contains previous caller
 274 // r14 contains function that was called
 275 void mcount()
 276
 277 GCC bugs
 278 --------
 279
 280 All versions of GCC previous to the working version 3.3 have bugs when
 281 generating profiling for thumb functions.
 282
 283 The errors are:
 284 - mov\tip,lr not a valid instruction (typo in gcc/config/arm/arm.h)
 285 - LPxx undefined when linking (missing . before LP causes the problem)
 286
 287 You can fix these problems by either recompiling GCC (recommended) or by
 288 modifying cc1.exe to fix the problems.
 289
 290 In the first option, find the given code in gcc/config/arm/arm.h and fix
 291 the typos (remove the extra blackslash from the mov ip,lr instruction and
 292 add the missing dot before LP%d) or change THUMB_FUNCTION_PROFILER to call
 293 ARM_FUNCTION_PROFILER (the recent changes that were performed in CVS).
 294
 295 If you don't want to compile your own GCC, then you can use an hex editor
 296 to fix the problems. Locate cc1.exe under <dir>/lib/gcc-lib/<config>/<version>
 297 and find the mov\tip,lr instruction. Change the extra backslash to a space.
 298 Locate the .LP string just before the mov instruction and change it to
 299 .P instead (make sure to place 0 after the P). Then find the text .word
 300 LP%d and change it to .word .P%d.
 301
 302 Histograms will be output even if the code is not compiled with call graph
 303 support.
 304
 305 Options configuration
 306 ---------------------
 307
 308 All configurable options are accessible from the configuration file
 309 VisualBoyAdvance.cfg.
 310
 311 This file is searched in this order:
 312
 313 - current directory
 314 - user home directory (defined by HOME environment variable)
 315 - user profile directory (Windows only defined by USERPROFILE directory)
 316 - executable directory (either relative or defined by PATH variable)
 317
 318 All options are documented in the file supplied with this distribution.
 319
 320 Command line options (override settings in configuration file)
 321 --------------------------------------------------------------
 322
 323   -1, --video-1x               1x
 324   -2, --video-2x               2x
 325   -3, --video-3x               3x
 326   -4, --video-4x               4x
 327   -F, --fullscreen             Full screen
 328   -G, --gdb=PROTOCOL           GNU Remote Stub mode:
 329                                 tcp      - use TCP at port 55555
 330                                 tcp:PORT - use TCP at port PORT
 331                                 pipe     - use pipe transport
 332   -N, --no-debug               Don't parse debug information
 333   -S, --flash-size=SIZE        Set the Flash size
 334       --flash-64k               0 -  64K Flash
 335       --flash-128k              1 - 128K Flash
 336   -T, --throttle=THROTTLE      Set the desired throttle (5...1000)
 337   -Y, --yuv=TYPE               Use YUV overlay for drawing:
 338                                 0 - YV12
 339                                 1 - UYVY
 340                                 2 - YVYU
 341                                 3 - YUY2
 342                                 4 - IYUV
 343   -b, --bios=BIOS              Use given bios file
 344   -c, --config=FILE            Read the given configuration file
 345   -d, --debug                  Enter debugger
 346   -f, --filter=FILTER          Select filter:
 347       --filter-normal            0 - normal mode
 348       --filter-tv-mode           1 - TV Mode
 349       --filter-2xsai             2 - 2xSaI
 350       --filter-super-2xsai       3 - Super 2xSaI
 351       --filter-super-eagle       4 - Super Eagle
 352       --filter-pixelate          5 - Pixelate
 353       --filter-motion-blur       6 - Motion Blur
 354       --filter-advmame           7 - AdvanceMAME Scale2x
 355       --filter-simple2x          8 - Simple2x
 356       --filter-bilinear          9 - Bilinear
 357       --filter-bilinear+        10 - Bilinear Plus
 358       --filter-scanlines        11 - Scanlines
 359       --filter-hq2x             12 - hq2x
 360       --filter-lq2x             13 - lq2x
 361   -h, --help                   Print this help
 362   -i, --ips=PATCH              Apply given IPS patch
 363   -p, --profile=[HERTZ]        Enable profiling
 364   -s, --frameskip=FRAMESKIP    Set frame skip (0...9)
 365   -t, --save-type=TYPE         Set the available save type
 366       --save-auto               0 - Automatic (EEPROM, SRAM, FLASH)
 367       --save-eeprom             1 - EEPROM
 368       --save-sram               2 - SRAM
 369       --save-flash              3 - FLASH
 370       --save-sensor             4 - EEPROM+Sensor
 371       --save-none               5 - NONE
 372   -v, --verbose=VERBOSE        Set verbose logging (trace.log)
 373                                   1 - SWI
 374                                   2 - Unaligned memory access
 375                                   4 - Illegal memory write
 376                                   8 - Illegal memory read
 377                                  16 - DMA 0
 378                                  32 - DMA 1
 379                                  64 - DMA 2
 380                                 128 - DMA 3
 381                                 256 - Undefined instruction
 382                                 512 - AGBPrint messages
 383
 384 Long options only:
 385       --agb-print              Enable AGBPrint support
 386       --auto-frameskip         Enable auto frameskipping
 387       --ifb-none               No interframe blending
 388       --ifb-motion-blur        Interframe motion blur
 389       --ifb-smart              Smart interframe blending
 390       --no-agb-print           Disable AGBPrint support
 391       --no-auto-frameskip      Disable auto frameskipping
 392       --no-ips                 Do not apply IPS patch
 393       --no-mmx                 Disable MMX support
 394       --no-pause-when-inactive Don't pause when inactive
 395       --no-rtc                 Disable RTC support
 396       --no-show-speed          Don't show emulation speed
 397       --no-throttle            Disable thrrotle
 398       --pause-when-inactive    Pause when inactive
 399       --rtc                    Enable RTC support
 400       --show-speed-normal      Show emulation speed
 401       --show-speed-detailed    Show detailed speed data
 402
 403 Known bugs
 404 ----------
 405
 406 - loading a save state that uses a different sound quality may hang the
 407   emulator. Please only use the 22Khz sound quality save states from the
 408   Windows version with this release
 409 - built-in debugger still has a few bugs
 410 - disassembler contains a few errors. Please report anything wrong you find
 411
 412 LICENSE
 413 -------
 414
 415     VisualBoyAdvance - a Gameboy and GameboyAdvance emulator
 416     Copyright (C) 1999-2003 Forgotten
 417     Copyright (C) 2004 Forgotten and the VBA development team
 418
 419     This program is free software; you can redistribute it and/or modify
 420     it under the terms of the GNU General Public License as published by
 421     the Free Software Foundation; either version 2 of the License, or
 422     (at your option) any later version.
 423
 424     This program is distributed in the hope that it will be useful,
 425     but WITHOUT ANY WARRANTY; without even the implied warranty of
 426     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 427     GNU General Public License for more details.
 428
 429     You should have received a copy of the GNU General Public License
 430     along with this program; if not, write to the Free Software
 431     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 432
 433 This program also contains code developed by the University of
 434 California and is subject to the extra conditions:
 435
 436 Copyright (c) 1991, 1998 The Regents of the University of California.
 437 All rights reserved.
 438
 439 Redistribution and use in source and binary forms, with or without
 440 modification, are permitted provided that the following conditions
 441 are met:
 442 1. Redistributions of source code must retain the above copyright
 443    notice, this list of conditions and the following disclaimer.
 444 2. Redistributions in binary form must reproduce the above copyright
 445    notice, this list of conditions and the following disclaimer in the
 446    documentation and/or other materials provided with the distribution.
 447 3. [rescinded 22 July 1999]
 448 4. Neither the name of the University nor the names of its contributors
 449    may be used to endorse or promote products derived from this software
 450    without specific prior written permission.
 451
 452 Contact
 453 -------
 454
 455 Please don't email unless you found some bug. Requests will be ignored and
 456 deleted. Also, be descriptive when emailing. You have to tell me what version
 457 of the emulator you are writing about and a good description of the problem.
 458 Remember, there are several interfaces (Windows, SDL and GTK+) and
 459 several systems (Windows, Linux, MacOS X and BeOS).
 460
 461 Also, there are still people writing about the old VisualBoy which is no longer
 462 supported. Also remember I am not paid to work on VisualBoyAdvance. This is
 463 just a hobby.
 464
 465 Forgotten (http://vba.ngemu.com/contact.shtml)
 466 kxu <kxu@users.sourceforge.net>
 467
 468 http://vba.ngemu.com
 469 http://sourceforge.net/projects/vba
 470
 471 Special Thanks
 472 --------------
 473
 474 PokemonHacker for all his help improving the emulator.
 475 Costis for his help fixing some of the graphics bugs.
 476 Snes9x developers for the great emulator and source code.
 477 Kreed for his great graphic filters.
 478 SDL team for this amazing library.
 479 And all users who kindly reported problems.