| blob | 29562e8c9ab5eb0cdf42bb55805f9846ce2294e0 |
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.
6 Features
7 --------
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
29 Compiling the sources
30 ---------------------
32 run autoreconf -i to generate the configure script,
33 then ./configure, make, make install as usual.
35 Installing
36 ----------
38 The easiest installation is to place all files in the distribution in the
39 same directory.
41 Per game settings
42 -----------------
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:
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>
53 Use the 4 letter game code to separate settings for each game. Example:
55 [ABCD]
56 rtcEnabled=0
57 flashSize=65536
58 saveType=0
60 [ABC2]
61 rtcEnabled=1
62 flashSize=131072
63 saveType=0
65 Support
66 -------
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.
73 FAQ
74 ---
76 See online FAQ for more information: http://vba.ngemu.com/faq.shtml
78 Please don't email about what you think it is problem before consulting
79 the FAQ.
81 System requirements
82 -------------------
84 Windows: PIII 500Mhz machine for GBA emulation. GB emulation requires far less.
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
90 Key combinations during emulation
91 ---------------------------------
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
105 Emulation key settings
106 ----------------------
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
123 GDB support
124 -----------
126 VisualBoyAdvance now provides GDB remote debugging support. This gives
127 developers the full power of GDB to debug GBA applications.
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).
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).
137 The emulator provides two transport protocols for remote debugging:
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.
146 Using TCP transport
147 -------------------
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:
154 target remote <hostname>:<port number>
156 where hostname is the host where the emulator is running and port number is the
157 printed port number.
159 Using PIPE transport
160 --------------------
162 To use the PIPE transport, start GDB with the .elf file to be debugged. Connect
163 to the emulator by using the command:
165 target remote |<full path to VBA>/VisualBoyAdvance -Gpipe
167 Debugging with GDB
168 ------------------
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.
176 After connecting and optionally loading the file into the debugger, you can
177 start debugging: add breakpoints, step, etc...
179 While using GDB, any console output (see below) will show up in GDB's console.
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.
184 You can also detach GDB from the emulator.
187 Console Output
188 --------------
190 There are two forms of console output in this version:
192 - Mappy style dprint: use the following code (from Mappy's documentation)
193 to get output:
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 }
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.
218 Built-in debugger enhancements
219 ------------------------------
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
239 Options configuration
240 ---------------------
242 All configurable options are accessible from the configuration file
243 VisualBoyAdvance.cfg.
245 This file is searched in this order:
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)
252 All options are documented in the file supplied with this distribution.
254 Command line options (override settings in configuration file)
255 --------------------------------------------------------------
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
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
337 Known bugs
338 ----------
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
346 LICENSE
347 -------
349 VisualBoyAdvance - a Gameboy and GameboyAdvance emulator
350 Copyright (C) 1999-2003 Forgotten
351 Copyright (C) 2004 Forgotten and the VBA development team
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.
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.
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
367 This program also contains code developed by the University of
368 California and is subject to the extra conditions:
370 Copyright (c) 1991, 1998 The Regents of the University of California.
371 All rights reserved.
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.
386 Contact
387 -------
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).
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.
399 Forgotten (http://vba.ngemu.com/contact.shtml)
400 kxu <kxu@users.sourceforge.net>
402 http://vba.ngemu.com
403 http://sourceforge.net/projects/vba
405 Special Thanks
406 --------------
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.