Light GameBoyAdvance (also LGBA) is a light game boy advance emulator.
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
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 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).
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 |
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
Each window can get focus. When a window is focused, its borders become green-ish.
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 |
The next instruction is 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 |
| 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 |
| 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 |
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 |
| 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 |
Same as registers window, but overwrites byte value as soon as 2 characters are written.
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 |
| 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 |
Same as registers and memory edit mode
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,$,&,>,<,=,!,[,],,}
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
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 |