README

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