Welcome to version 1.2 of VisualBoyAdvance-SDL. This is a GB/GBC/GBA
emulator for Windows, Linux and BeOS.

Features:
---------

- configurable GB/GBA keys, including joystick support
- option to use BIOS file
- directory selection for save state, battery and screen capture
- fullscreen mode
- video sizes 1x, 2x, 3x and 4x
- graphic filters Normal, TV Mode, 2xSaI, Super 2xSaI and Super Eagle
- 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)

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.

Support
-------

Please support VisualBoyAdvance by making a donation. You can donate money
using PayPal (www.paypal.com). Send donations to vb@emuhq.com. If you want
to make other kind of donations (hardware, etc...), please contact me.

System requirements
-------------------

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

Linux: minimum requirement should be similar to Windows version. 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
- 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: X
- 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

Options configuration
---------------------

All configurable options are accessible from the configuration file
VisualBoyAdvance.cfg. This file should be placed in the same directory
as the emulator or it should reside in the current directory where the
emulator is started from.

All options are documented in the file supplied with this distribution.

Command line options (override settings in configuration file)
--------------------------------------------------------------

  -1 1x
  -2 2x
  -3 3x
  -4 4x
  -F Full screen
  -G<protocol> GNU Remote Stub mode:
    tcp        - use TCP at port 55555
    tcp:<port> - use TCP at port <port>
    pipe       - use pipe transport
  -N Don't parse debug information
  -Y<type> Use YUV overlay for drawing:
    0 - YV12
    1 - UYVY
    2 - YVYU
    3 - YUY2
    4 - IYUV
  -b<bios file> Use given bios file
  -d Enter debugger
  -f<filter> Select filter:
    0 - normal mode
    1 - TV Mode
    2 - 2xSaI
    3 - Super 2xSaI
    4 - Super Eagle
    5 - Pixelate (experimental)
    6 - Motion Blur (experimental)
  -s<frameskip> Set frame skip (0...9)
  -t<type> Set the available save type
   0 - Automatic (EEPROM, SRAM, FLASH)\n");
    1 - EEPROM
    2 - SRAM
    3 - FLASH
    4 - EEPROM+Sensor
  -v<verbose> Set verbose level (add flags values for multiple):
      1 - SWI
      2 - Unaliagned memory access
      4 - Illegal memory write
      8 - Illegal memory read
     16 - DMA 0
     32 - DMA 1
     64 - DMA 2
    128 - DMA 3

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-2002 by Forgotten

    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

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, thre is a SDL version, a Windows version and a Linux version. 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 (vb@emuhq.com)
http://vboy.emuhq.com

Special Thanks
--------------

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.
