README.md

gvasm

Assembler and disassembler designed specifically for Game Boy Advance homebrew.

The assembler works for ARM and Thumb code, and has features like conditional compilation, defined constants and functions, struct layout, compile-time scripts, literal pools, and incremental builds.

The disassembler is experimental, and includes a partially implemented ARM emulator.

Install

You'll need to install deno on your operating system.

Then run:

# install the latest release of deno
deno upgrade

# install the latest release of gvasm
deno install -g --allow-read --allow-write --allow-run -f -r \
  https://raw.githubusercontent.com/velipso/gvasm/main/gvasm.ts

If this is your first time running deno install, you will need to add the deno binary directory to your path. See the page on deno install for more information.

In order to upgrade, simply run the above command again -- it will redownload the latest version and install it.

You can verify everything installed correctly by running the internal test suite:

gvasm itest

Every test should pass!

Assembler

Read the assembler manual.

Start by initializing a new file:

gvasm init MyGame.gvasm

This will create MyGame.gvasm in your current directory with a small example program.

You can build this file via:

gvasm make MyGame.gvasm

This will output MyGame.gba, which can be ran inside emulators. The example program just sets the background color to green.

Disassember and Emulator [WIP]

If you want to play with the disassembler, you can try:

gvasm dis gba_bios.bin

The emulator can run code, which is useful for quickly debugging a section of code. For example, this works:

// test.gvasm
.thumb
ldr   r0, =300
again:
_log  "r0 = %d", r0
subs  r0, #1
cmp   r0, #250
bne   again
_log  "done"
_exit
.pool

Then:

gvasm run test.gvasm

This will execute the code, along with debug statements like _log and _exit, producing the output:

r0 = 300
r0 = 299
...
r0 = 251
done

Installing Older Version

If your project uses the older gvasm v1, you can still install the latest release prior to v2 by using the v1.9.4 tag:

deno install --allow-read --allow-write -f -r \
  https://raw.githubusercontent.com/velipso/gvasm/v1.9.4/gvasm.ts

References

• Assembler Manual
• GBA Instruction Set

GBA Technical Docs

• ARM7TDMI Tech Spec (mirror)
• ARM7TDMI Data Sheet (mirror)
• ARM7TDMI Instruction Set (mirror)
  • Error on PDF page 18 (labeled "Page 16"), it gives the incorrect encoding for CMN instruction
• CowBite Hardware Spec (mirror)
• GBATEK No$GBA (mirror)

Flash Cart Docs

• M29W128GH/M29W128GL (mirror)
• S29GL128N/S29GL256N/S29GL512N (mirror)
• M36W0R6030T0/M36W0R6030B0 (mirror)
• M58WR064FT/M58WR064FB (mirror)
• CFI Publication 100 (mirror)