Introduction

Light GameBoyAdvance (also LGBA) is a light game boy advance emulator.

If you have problems installing the program, give a look at the Installation Notes that come with your distribution.

To get a list of available arguments and options run ./LGBA -h in the folder of the executable. In general to start the emulator loading a rom run ./LGBA myRom.gba if myRom.gba is your file.

To use the emulator you have to have the original bios of the GBA, which is not distributed along with the program. The default name of the bios is gba_bios.bin inside the folder of the application. Other names can be used, but you have to tell LGBA so with ./LGBA -b myBios.bin myRom.gba

Continuous Drawing Mode

The -c option enables continous drawing which allows the PPU thread to draw even during VBLANK (the moments in which the cpu writes to VRAM). It causes graphical glitches, but it is useful to see how things are written into vram/pram/oam.

LGBA Modes

LGBA can run in two modes: Normal Mode and Debug Mode. To enable Debug Mode you have to run LGBA with the option "-d". Normal Mode is pretty much faster than Debug Mode (it hasn't to look for debugger approval and breakpoints before executing each instruction).

Normal Mode

In Normal Mode you just have a window with the video output of the emulator. You can write to the input register through these keys

KEY	Binding
Z	A GBA Key
X	B GBA Key
A	L GBA Key
S	R GBA Key
C	Select GBA Key
V	Start GBA Key
UP	Up GBA Key
DOWN	Down GBA Key
LEFT	Left GBA Key
RIGHT	Right GBA Key

Debug Mode

In Debug Mode both the video output window and the debugger window can get control over what's happening. To switch control from the video output window to the debugger pres B. To give control to the video output window press F12 or '*' while in the terminal window. When a break condition is hit the control will automatically be given to the debugger window.

The debugger will be visually located in the terminal window you used to start the process. It is composed of 6 zones. Something like this

+-------------------------+-----------------------------------------------+
|                         |                                               |
|   DISASSEMBLY WINDOW    |                 MEMORY WINDOW                 |
|                         |                                               |
+----------+-----------+--+----------+------------------------------------+
|          |           |             |                                    |
|REGISTERS |   STACK   | BREAKPOINTS |            IO REGISTERS            |
|  WINDOW  |   WINDOW  |    WINDOW   |               WINDOW               |
|          |           |             |                                    |
+----------+-----------+-------------+------------------------------------+

Each window can get focus. When a window is focused, its borders become green-ish.

Debugger Window Global Controls

These keys are global and work prior to focus.

KEY	EFFECT
F1	Focus Disassembly Window
F2	Focus Registers Window
F3	Focus Stack Window
F4	Focus Memory Window
F5	Focus Breakpoints Window
F6	Focus IOReg Window
F7	Execute 1 instruction
F8	Execute 500 cycles
F9	Execute 5000 cycles
F10	Execute 50000 cycles
F12	Give control to video output window
*	Give control to video output window
SPACE	Execute 1 instruction
ESCAPE	Exit LGBA

Disassembly Window Controls

The disassembly window contains the dissassembled instructions of a memory zone (usually the one that is being executed). The instructions are written in a sligthly modified ARM syntax (e.g. since there're no labels every time a label is expected in standard ARM, an address is written in the disassembly with the from 0xNNNNNNNN).

The next instruction has blue background colour Breakpoints instructions are in red

KEY	EFFECT
UP	See lower address instructions
DOWN	See higher address instructions
PAGEUP	See lower address instructions (more offset than UP)
PAGEDOWN	See higher address instructions (more offset than DOWN)
-	Center currently executed instruction
b	Add break point in the upper visible instruction

Registers Window

SELECT MODE

KEY	EFFECT
UP	Select prev register
DOWN	Select next register
LEFT	Select prev register (if rn is selected selects r(n-9))
RIGHT	Select next register (if rn is selected selects r(n+9))
ENTER	Starts Edit Mode

EDIT MODE

KEY	EFFECT
ENTER	If nothing is written, return to select mode
ENTER	If something is written, overwrites selected register
BACKSPACE	If something is written, deletes 1 character
BACKSPACE	If nothing is written, return to select mode
HEX DIGIT	Writes an hex digit to the buffer. When 8 digits are written, automatically overwrites the selected register value

Stack Window

The stack pointer pointed location is in yellow

KEY	EFFECT
UP	See lower address stack memory
DOWN	See higher address stack memory
PAGEUP	See lower address stack memory (more offset than UP)
PAGEDO	See higher address stack memory (more offset than DOWN)
-	Set the offset so that the SP is the first visible

Memory Window

SELECT MODE

KEY	EFFECT
RIGHT	Select next byte
LEFT	Select prev byte
UP	Select prev byte row
DOWN	Select next byte row
PAGEUP	Same as UP
PAGEDOWN	Same as DOWN
z	Same as UP
x	Same as DOWN
+	Increment the number of bytes in a row
-	Decrement the number of bytes in a row (useful to put for instance 0x20 bytes in each row, instead of 0x23 that would create a mess)
1-8	If n is the number pressed, goes to the address 0x0n000000
ENTER	Starts Edit Mode

EDIT MODE

Same as registers window, but overwrites byte value as soon as 2 characters are written.

NOTES

Remember that in GBA the address space is like this

ADDRESS	ZONE
0x00000000	BIOS
0x02000000	External Working RAM (Slow Ram, 256KB)
0x03000000	Internal Working RAM (Fast Ram, 16KB)
0x04000000	IO Registers
0x05000000	Palette Ram (1KB)
0x06000000	Video Ram (96 KB)
0x07000000	OAM Ram (Sprites RAM, 1KB)
0x08000000	Cartridge ROM
0x0E000000	Cartridge additional FRAM/SRAM/FLASH MEMORY/EEPROM or whatever

Breakpoints Window

SELECT MODE

KEY	EFFECT
UP	Selects prev break rule
DOWN	Selects next break rule
BACKSP	Deletes selected break rule
ENTER	If the selected rule is the "ENTER HERE TO ADD RULE", starts edit mode

EDIT MODE

Same as registers and memory edit mode

HOW TO DEFINE BREAK RULES

The grammar to define break rules is something like this (in Chomsky Normal Form) Our alphabet is {0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F,a,b,c,d,e,f,r,R,$,&,>,<,=,!,[,],,}

<break_rule> -> <hexnumber>,<condition>|$|<hexnumber>,<condition>
<condition>  -> [<hexnumber>]<operation><hexnumber>|<regsymbol><regID><operation><hexnumber>
<operation>  -> &|==|!=|>|<|>=|<=
<hexnumber>  -> <hexdigit><hexnumber> | <hexdigit>
<regID>      -> <digit>|10|11|12|13|14|15
<hexdigit>   -> <digit>|A|B|C|D|E|F|a|b|c|d|e|f
<digit>      -> 0|1|2|3|4|5|6|7|8|9

The first part is the address in which the break rule is valid. '$' means that every address is valid. The second part is optional. If omitted, as soon as the address becomes the new PC the execution is broken. A break rule of "$" means that whatever happens it will break. If the second part is present it represents the break condition. It is composed of the value of an address or a register, an operator and operand. If the condition is true and we are in the address defined then the execution breaks.

Some examples

080000CC        ;breaks execution when PC==080000CC
$,r1&080        ;breaks execution when bit7 of R1 is set
$,[04000006]>76 ;breaks execution when [04000006] is more than 0x76
080000CC,r1==2  ;breaks execution when PC==080000CC AND r1==2

Io Registers Window

Here some informations about io registers are made understandable.

KEY	EFFECT
LEFT	Selects previous page
RIGHT	Selects next page

The pages are as follows

ID	PAGE
0	Video Registers
1	Background registers
2	Sound Registers
3	DMA Registers
4	General Registers (Interrupt+Input)
5	Timers Registers