INTRODUCTION
============

AGD is a Gameboy Advance(R) emulator and debugger with a number of 
advanced features for tracking down difficult bugs.  This version of the 
software is beta.  What that means is that I am presently near the limit 
of my ability to do meaningful testing, so I am making the product 
available to you with the understanding that not all features are 
implemented yet, and bugs are known to exist.  It is my hope that by 
making this available to you, you will be able to use the existing 
features to do effective debugging, and in return your constructive 
feedback (and bug reports) will enable me to polish and finish this 
product.

This beta version is free.  It can only be redistributed in its 
entirety, and without alteration.  You can help bring this product to 
completion in one of two ways:

(1)  Concise bug reports will be of great help to me.  If you have 
experience with software development, you probably know how to state the 
minimum number of steps needed to reproduce a problem.  Please do not 
send bug reports regarding commercial games; to fix bugs in commercial 
games may require me to reverse-engineer them to some degree, and that 
is illegal.  Also, if you're writing the source code that causes the bug 
in AGD, it will be far easier to pinpoint the problem.  If you feel that 
you have a bug report worth consideration, please email it to 

agd@emuunlim.com

(2)  If you're able to afford it, and if you really want to see AGD take 
off, then please send me a reasonable contribution of money.  This is my 
first emulator, and it will be my first shareware title (when I finish 
it!)  There are a lot of features that I want to implement, and I wanted 
to finish tuning the emulator, but I decided to release this beta to see 
what kind of feedback I get.  If you're up for sending me a 
contribution, you can send me money through www.paypal.com to my email 
address:

jpanettiere@earthlink.net

or you can send a check (please - no cash!) payable in US currency to:

John Panettiere
2829 Tilghman Street
Allentown, PA 18104-4265
USA

When this product is stable enough to be considered "post-beta", I 
intend to sell it as shareware with a $35US registration fee.  If you 
send me a contribution before then, I will count your money towards the 
registration price (just MAKE SURE you send your name and email address 
along with your payment).  If you send $25US or more, I will consider 
you pre-registered for the basic finalized version of AGD - that's a 
savings of $10.

If there is a significant interest in AGD, I intend to implement 
source-level debugging and a profiler, and perhaps other features; but I 
may charge extra for these advanced features as they are non-trivial.


GETTING STARTED
===============

Before launching AGD, you will need to get a copy of the GBA BIOS ROM 
(some people have written their own implementations of the BIOS, these 
can be used too).  Name it "gba.rom", and place it in the directory 
containing AGD.  I cannot supply you with this ROM because it is 
copyrighted material.

To debug an application, first launch agd.exe.  You will see a screen 
with 3 "windows", each window has a row of tabs at the top that lets you 
select between different "panels".  The top window is called the code 
window, the bottom-left is called the data window, and the bottom-right 
is called the app window.  You'll notice that the code window has a tab 
labeled "load", if you select this (left-click on it) you get a file 
browser through which you can load in a ROM.

----------------------------------
|                                |
|          CODE WINDOW           |
|                                |
|                                |
|                                |
|                                |
----------------------------------
|    DATA WINDOW    | APP WINDOW |
|                   |            |
|                   |            |
----------------------------------

The "disassembly" panel allows you to view your application's 
disassembled code.  In the data window, there is a "memory" panel that 
lets you view program memory.  The app window has a "registers" panel 
that lets you view the ARM registers.  These are the primary panels you 
will use when debugging your code.

Sometimes, to see all of the contents of a panel, you will need to 
scroll up or down within that panel.  The pgup/pgdn keys, and the cursor 
up/down keys, can be used to scroll up or down in the active panel in 
the code window.  To scroll in the active panel in the data window, hold 
down the "shift" key and use pgup/pgdn, or cursor up/down.  None of the 
app window panels presently require scrolling.  Sometimes, you need to 
jump to a specific location - for instance, a particular address in the 
disassembly panel or memory panel, or a specific line number in the help 
panel.  Pressing the "g" key pops up a requestor that asks you which 
line number to jump to.  Enter the value, and the active panel in the 
code window jumps to that location.  If you press "shift-g", you will 
get the same requestor, and the active panel in the data window jumps to 
the location you specify.

To set a breakpoint, press "b".  This pops up a requestor that asks you 
to specify the breakpoint.  It expects the breakpoint in the format:
[rwx] [address]
where you must specify at least one of the letters "rwx" to indicate 
whether you want the break to occur on a read-from, write-to, or 
execute-at the indicated address.  Any combination of the three letters 
is permitted.  After you enter the breakpoint, it will be listed in the 
"breakpoints" panel in the data window.  You can then alter the "rwx" 
settings by clicking on the associated checkboxes.  You can also click 
on the "max count" field to specify a countdown for the breakpoint, or 
the "range" field to specify how many bytes you want the breakpoint to 
cover, or the "address" field to change the base address of the 
breakpoint.  Right-clicking on a breakpoint will delete it.  One nice 
feature about AGD is that performance is not impeded by breakpoints, you 
can set a read breakpoint on the entire I/O space, for instance, and 
suffer no performance penalty.  Setting 800 breakpoints, for instance, 
would also incur no penalty.  If you specify a countdown, though, there 
is a minor performance hit every time that breakpoint is encountered.

When specifying any values for the breakpoints, remember that it expects 
them in hex, without any leading "0x".

Presently, there are four options for stepping through code:

F5 -	Executes the program, stopping only when a breakpoint is met or 
		when you press F5 again.  While the program is executing, you 
		can press "ctrl-F5" to freeze the action without returning to 
		the debugger.
F7 -	This is the "step-over" command that executes the next 
		instruction, but steps over subroutines.
F8 -	This command executes the next instruction until it retires.  
		That is, this is the "step-into" command.
F9 -	This command will advance the program by a single atomic 
		operation.  For load-multiple instructions, you will have to 
		press F9 once for each memory transfer.  If an interrupt occurs 
		before the next instruction, you will be redirected to the 
		interrupt vector.

If you press ctrl plus F7, F8 or F9, AGD will repeat that command 
("animate") until you press F7, F8 or F9 to stop it.

When you hit F5, the GBA controls are emulated using the following 
hard-coded keys:

ALT					A
CTRL				B
SPACE				SELECT
ENTER				START
CURSOR KEYS			D-PAD
S					R
A					L


API FOR DEBUGGING FACILITIES
============================

AGD recognizes certain NOP opcodes as being user messages to the 
debugger that you can use for software-controlled debugging.  Just 
encode MOV R0,R0 in ARM or Thumb without setting the condition codes, 
and AGD will interpret the contents of R0 as a command (0=user 
breakpoint, 1=null-terminated ascii text, 2 and higher are reserved).  
In the case of text messages, R1 contains the address of a 
null-terminated text string, and the output is sent to the "user" panel 
in the code window.  If the string exceeds 256 characters in length, it 
is truncated.


MISCELLANEOUS FEATURES
======================

During program execution, you can toggle the BG layers 0-3 off or on by 
pressing the keys '0' through '3'.  You can toggle the display of OAM 
(sprites) with the 'S' key.

If you don't like AGD switching to fullscreen mode when you press F5, 
you can go to the options panel and deselect the "App runs in 
full-screen mode" checkbox.

You can press "d" to do an assembly dump to a file, or "shift-D" to do a 
memory dump to a file.  The assembly dump uses the current machine state 
(thumb or arm) in deciding how to disassemble the addresses you provide.  
The memory dump uses the current memory format specified in the options 
panel.  In both cases, you must specify two addresses (low first, then 
high) separated by a space; this is the range of addresses that will be 
dumped.

During program execution, you can press the X button to toggle a grid 
that breaks the screen up into 16x16 tiles; pressing X again breaks it 
up into 8x8 tiles, and pressing X again removes the grid.

F4 can be used to reset (reboot) the GBA.  Every time you load a ROM, 
the GBA is rebooted.

To exit AGD at any time, type "alt-Q".

Nintendo, Gameboy and Gameboy Advance are registered trademarks of 
Nintendo.

AGD was developed by John Marco Panettiere.  I reserve all rights to the 
product, but you are permitted to redistribute this beta version freely, 
so long as you do not alter it and you must redistribute it in its
entirety.
