README

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