VBA-SDL-H is a modified version of the Gameboy Advance emulator VisualBoyAdvance which includes enhanced debugging facilities.
This release of VBA-SDL-H is a complete rewrite based on the official VBA 1.7.2 codebase. Most significantly, expression evaluation has been added, robust code tracing functionality is available and the memory access breakpoint system has undergone a major overhaul.
If you need to contact me, you can do so via ROMHacking.net. If you need support, have a bug report or feature request, you can post y in this thread.
This software is open source and licensed under the GPL. If you want to make any additions or alterations, you can make a feature request, or just do it yourself. I'm maintaining a Mercurial repository at ShareSource for those of you who want to grab the latest code.
VBA-SDL-H, like VBA-SDL, is a command-line program. You can start the program from the command prompt ('$' is the prompt) e.g.:
$ VisualBoyAdvance-SDL-H.exe name_of_rom.gba
Or (in Windows) drag the ROM onto the executable file in explorer, or right-click the ROM, select 'Open with', and select the executable.
VBA-SDL-H is designed to be used in conjunction with 'normal' VBA, so it is advised that you set the programs up so that they share the same configuration file, or have their configurations pointing to the same ROM, save directories, etc.
VBA-SDL-H can be compiled from source in the same way as VBA. See COMPILING for detailed instructions. For Windows users, a Solution file for Visual C++ Express (free download from MSDN) has been included. For Linux users, you'll need the standard tools. The only extra dependency for Linux not listed in the documenation is GNU readline, which is optional, but highly recommended.
All of the useful stuff in VBA-SDL-H is done via the debugging-console. This can be accessed by pressing 'F11' whilst the game is running. This stops the execution of the ROM. In the console window you will now see the debugger> prompt. This is where you type in commands.
R00=0000001a R04=00000001 R08=00000000 R12=00000000 R01=00000007 R05=030000a4 R09=00000000 R13=03007ee0 R02=80000000 R06=00000f55 R10=00000000 R14=020002db R03=00000080 R07=00000000 R11=00000000 R15=02000244 CPSR=4000007f (.Z...FT Mode: 1f) 02000240 d107 bne $02000252 (last executed instruction) > 02000242 2200 mov r2, #0x0 (current instruction - will be executed next) 02000244 4288 cmp r0, r1 (instruction following the current one - will not necessarily be executed if the current instruction is a branch) debugger>
To return to the game, you use the command c. To quit, you can press ESC whilst the game is running, or use the q command from the console.
This section lists the commands available at the debugging console. Although limited help is provided within the program (use the command h), this may not be very detailed (especially for commands that have sub-commands, like 'var' and 'trace').
Additionally, commands prefixed with an 's' ( slocals, sbreak, sradix, sprint, ssymbols, strace and swhere are symbolic debugging commands, and are only useful for use with ROMs that have symbolic debugging information included.
Arguments listed in [brackets] are optional. Arguments listed in {braces} take expressions (described below)
Expressions can be used as arguments to commands to reduce typing. However, when used as an argument, they cannot contain whitespace unless surrounded by quotation marks.
Numbers prefixed with a '$', '0x', or have a leading zero, are interpreted as hexadecimal.
Numbers without a leading zero are interpreted as decimal.
debugger> eval $AB =$000000AB debugger> eval 0xABC =$00000ABC debugger> eval 0ABCD =$0000ABCD debugger> eval 099 =$00000099 debugger> eval 99 =$00000063
The values contained in registers can be substituted in by using the special variables 'r0', 'r1', etc... as well as 'sp', 'lr' and 'pc' for r13, r14 and r15.
R00=00000004 R04=00000003 R08=00000000 R12=00000000 R01=00000004 R05=00030000 R09=00000000 R13=03007bc8 R02=00000048 R06=03001d50 R10=00000000 R14=080188bf R03=03001d98 R07=03001d58 R11=00000000 R15=08018906 CPSR=8000003f (......T Mode: 1f) > 08018904 2809 cmp r0, #0x9 debugger> eval r3 =$03001D98 debugger> eval r06 =$03001D50 debugger> eval sp =$03007BC8
User defined variables can be created with the var set command. Once defined they can be used in expressions like a normal literal. Variables can also be loaded from/saved to a file using var load and var save.
debugger> var set foo 42 foo = $0000002a debugger> eval foo =$0000002A
Values from memory locations can be accessed using brackets. 'b[expr]' will be replaced by the evaluator with the byte at the address represented by expr. Likewise, 'h[expr]' and 'w[expr]' are replaced by the halfword, and word at expr respectively. expr can be any expression - nesting of addressing operations is also allowed.
debugger> mb 080000a0 080000a0 41 44 56 41 4e 43 45 57 41 52 53 50 41 57 52 50 ADVANCEWARSPAWRP 080000b0 30 31 96 00 00 00 00 00 00 00 00 00 00 37 00 00 01...........7.. ... debugger> eval b[080000a0] =$00000041 debugger> eval h[080000a0] =$00004441 debugger> eval w[080000a0] =$41564441
All standard math operators are support, with their usual precedence. They are (from highest to lowest):
| () | grouping |
| * / | multiplication/division |
| + - | addition/subtraction |
| << >> | bitwise shift |
| & | bitwise AND |
| ^ | bitwise XOR |
| | | bitwise OR |
debugger> eval b[080000a0]*2-1 =$00000081 debugger> eval $42>>1+1 =$00000022 debugger> eval $42>>(1+1) =$00000010 debugger> eval $42>>(1|2) debugger> eval ((($42<<8)*3-0321fe)/3)^0x5ef94cde =$0BADC0DE
ba {address}
Adds an ARM breakpoint on the instruction at {address}
bt {address}
Adds a Thumb breakpoint on the instruction at {address}.
bl
Lists all execution breakpoints
bd <n>
Delete breakpoint <n>
c
Continues execution of the ROM (disables debugging console)
n
Execute the next instruction.
rtt {address}
Execute until the Thumb instruction at {address}
rta {address}
Execute until the ARM instruction at {address}
rt {address}
Execute until the instruction at {address} (assumes current mode)
var set <name> {value}
Defines a variable <name> equal to {value}
var list
Lists all currently defined variables
var load <file>
Load variables from <file>
var save <file>
Saves variables to <file>
eval {expr}
Prints the value of {expr}.
bpr {address} {count}
Adds a read breakpoint on {count} bytes starting at {address}
bprc
Clear all read breakpoints
bpw {address} {count}
Adds a write breakpoint on {count} bytes starting at {address}
bpwc
Clear all write breakpoints
eb {address} {value}
Change the byte at {address} to {value}
eh {address} {value}
Change the halfword at {address} to {value}
ew {address} {value}
Change the word at {address} to {value}
er <n> {value}
Change the contents of register <n> to {value}
mb {address}
Show memory contents at {address} as bytes
mh {address}
Show memory contents at {address} as halfwords (16-bit)
mw {address}
Show memory contents at {address} as words (32-bit)
io
Shows the status of some I/O registers
r
Shows contents of processor registers
q
Quits the program.
load <n>
Loads savestate <n>
save <n>
Saves to savestate <n>
dload <file> {address}
Load raw data dump from <file> into {address}
dsave <file> {address} {size}
Save {size} bytes of data at {address} to <file>
fh {start} [<max-result>] <hex-string>
Search memory for hex-string
ft {start} [<max-result>] <string>
Search memory for ASCII-string
fr [<max-result>]
Resume current search
trace file <file>
Set tracer output to <file> (default is trace.log)
trace start
Start trace
trace stop
Stop trace
trace once on|off
When enabled, instructions are only logged to the output file the first time they are executed.
A lot of people have contributed over the years to make VBA what it is today. Without their efforst, VBA-SDL-H would not exist.
VBA-SDL-H, like VBA, is licensed under the GPL (v2). See COPYING for the full text.