-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
479 lines (384 loc) · 17.3 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
Welcome to version 1.8.0 of VisualBoyAdvance [SDL].
This is a GB/GBC/GBA emulator for Windows, Linux, MacOS X and BeOS.
Features
--------
- configurable GB/GBA keys, including joystick support
- option to use BIOS file
- zip/gzip file support
- directory selection for save state, battery and screen capture
- fullscreen mode (selectable resolution)
- video sizes 1x, 2x, 3x and 4x
- graphic filters Normal, TV Mode, 2xSaI, Super 2xSaI and more
- interframe blending support
- 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)
- auto frameskipping and throttle
- AGBPrint support for development
- RTC support
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.
Per game settings
-----------------
Version 1.5 introduced the support for per game settings for GBA games. You
can defined the following settings on a per game basis by using an INI file
called vba-over.ini in the same directory as the emulator:
rtcEnabled=<0 for false, anything else for true>
flashSize=<65536 or 131072>
saveType=<0 for automatic, 1 for EEPROM, 2 for SRAM, 3 for Flash or 4 for
EEPROM+Sensor>
Use the 4 letter game code to separate settings for each game. Example:
[ABCD]
rtcEnabled=0
flashSize=65536
saveType=0
[ABC2]
rtcEnabled=1
flashSize=131072
saveType=0
Support
-------
Please support VisualBoyAdvance by making a donation. You can donate money
using PayPal (www.paypal.com). Use the contact form to find how you can
send donations. Also, it is recommended that you use the VisualBoyAdvance
forum on www.ngemu.com message board.
FAQ
---
See online FAQ for more information: http://vba.ngemu.com/faq.shtml
Please don't email about what you think it is problem before consulting
the FAQ.
System requirements
-------------------
Windows: PIII 500Mhz machine for GBA emulation. GB emulation requires far less.
Linux, MacOS X, BeOS:
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
- Ctrl+B: rewind (if enabled and available)
- 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: S
- 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
Profiling
---------
VisualBoyAdvance has profiling support. It produces output in the format
supported by GPROF. You need a cross-compiled binary of GPROF (binutils
GNU package) compiled with --target=arm-thumb-elf (or similar).
The output will always contain the histogram of PC positions at the specified
frequency even if the code is not compiled with call graph support.
In order to enable profiling, you need to add a call inside your code
to start it (download vba.s for a ready to use file for GCC):
void monstartup(u32 lowPC, 32 highPC)
This will start profiling for the given address region. If the code was also
compiled with -pg, call graphs will be recorded.
Other calls for fine grain control:
// control profiling
// 0 - stops profiling
// anyother value starts it
void moncontrol(int mode)
// stop profiling and output gmon.out file
void moncleanup()
// record call graph (used by GCC)
// r12 contains previous caller
// r14 contains function that was called
void mcount()
GCC bugs
--------
All versions of GCC previous to the working version 3.3 have bugs when
generating profiling for thumb functions.
The errors are:
- mov\tip,lr not a valid instruction (typo in gcc/config/arm/arm.h)
- LPxx undefined when linking (missing . before LP causes the problem)
You can fix these problems by either recompiling GCC (recommended) or by
modifying cc1.exe to fix the problems.
In the first option, find the given code in gcc/config/arm/arm.h and fix
the typos (remove the extra blackslash from the mov ip,lr instruction and
add the missing dot before LP%d) or change THUMB_FUNCTION_PROFILER to call
ARM_FUNCTION_PROFILER (the recent changes that were performed in CVS).
If you don't want to compile your own GCC, then you can use an hex editor
to fix the problems. Locate cc1.exe under <dir>/lib/gcc-lib/<config>/<version>
and find the mov\tip,lr instruction. Change the extra backslash to a space.
Locate the .LP string just before the mov instruction and change it to
.P instead (make sure to place 0 after the P). Then find the text .word
LP%d and change it to .word .P%d.
Histograms will be output even if the code is not compiled with call graph
support.
Options configuration
---------------------
All configurable options are accessible from the configuration file
VisualBoyAdvance.cfg.
This file is searched in this order:
- current directory
- user home directory (defined by HOME environment variable)
- user profile directory (Windows only defined by USERPROFILE directory)
- executable directory (either relative or defined by PATH variable)
All options are documented in the file supplied with this distribution.
Command line options (override settings in configuration file)
--------------------------------------------------------------
-1, --video-1x 1x
-2, --video-2x 2x
-3, --video-3x 3x
-4, --video-4x 4x
-F, --fullscreen Full screen
-G, --gdb=PROTOCOL GNU Remote Stub mode:
tcp - use TCP at port 55555
tcp:PORT - use TCP at port PORT
pipe - use pipe transport
-N, --no-debug Don't parse debug information
-S, --flash-size=SIZE Set the Flash size
--flash-64k 0 - 64K Flash
--flash-128k 1 - 128K Flash
-T, --throttle=THROTTLE Set the desired throttle (5...1000)
-Y, --yuv=TYPE Use YUV overlay for drawing:
0 - YV12
1 - UYVY
2 - YVYU
3 - YUY2
4 - IYUV
-b, --bios=BIOS Use given bios file
-c, --config=FILE Read the given configuration file
-d, --debug Enter debugger
-f, --filter=FILTER Select filter:
--filter-normal 0 - normal mode
--filter-tv-mode 1 - TV Mode
--filter-2xsai 2 - 2xSaI
--filter-super-2xsai 3 - Super 2xSaI
--filter-super-eagle 4 - Super Eagle
--filter-pixelate 5 - Pixelate
--filter-motion-blur 6 - Motion Blur
--filter-advmame 7 - AdvanceMAME Scale2x
--filter-simple2x 8 - Simple2x
--filter-bilinear 9 - Bilinear
--filter-bilinear+ 10 - Bilinear Plus
--filter-scanlines 11 - Scanlines
--filter-hq2x 12 - hq2x
--filter-lq2x 13 - lq2x
-h, --help Print this help
-i, --ips=PATCH Apply given IPS patch
-p, --profile=[HERTZ] Enable profiling
-s, --frameskip=FRAMESKIP Set frame skip (0...9)
-t, --save-type=TYPE Set the available save type
--save-auto 0 - Automatic (EEPROM, SRAM, FLASH)
--save-eeprom 1 - EEPROM
--save-sram 2 - SRAM
--save-flash 3 - FLASH
--save-sensor 4 - EEPROM+Sensor
--save-none 5 - NONE
-v, --verbose=VERBOSE Set verbose logging (trace.log)
1 - SWI
2 - Unaligned memory access
4 - Illegal memory write
8 - Illegal memory read
16 - DMA 0
32 - DMA 1
64 - DMA 2
128 - DMA 3
256 - Undefined instruction
512 - AGBPrint messages
Long options only:
--agb-print Enable AGBPrint support
--auto-frameskip Enable auto frameskipping
--ifb-none No interframe blending
--ifb-motion-blur Interframe motion blur
--ifb-smart Smart interframe blending
--no-agb-print Disable AGBPrint support
--no-auto-frameskip Disable auto frameskipping
--no-ips Do not apply IPS patch
--no-mmx Disable MMX support
--no-pause-when-inactive Don't pause when inactive
--no-rtc Disable RTC support
--no-show-speed Don't show emulation speed
--no-throttle Disable thrrotle
--pause-when-inactive Pause when inactive
--rtc Enable RTC support
--show-speed-normal Show emulation speed
--show-speed-detailed Show detailed speed data
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-2003 Forgotten
Copyright (C) 2004 Forgotten and the VBA development team
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
This program also contains code developed by the University of
California and is subject to the extra conditions:
Copyright (c) 1991, 1998 The Regents of the University of California.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. [rescinded 22 July 1999]
4. Neither the name of the University nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
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, there are several interfaces (Windows, SDL and GTK+) and
several systems (Windows, Linux, MacOS X and BeOS).
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 (http://vba.ngemu.com/contact.shtml)
kxu <[email protected]>
http://vba.ngemu.com
http://sourceforge.net/projects/vba
Special Thanks
--------------
PokemonHacker for all his help improving the emulator.
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.