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