Assembler/Disassembler for the Dreamcast VMU

This project is maintained by wtetzner


waterbear is an assembler/disassembler for the Dreamcast VMU.

It aims to be a robust, easy-to-use tool, and meant to make VMU programming bit more approachable.

The error messages are designed to make it easy to find out what went wrong where:

% waterbear assemble example.s -o example.vms
[ERROR] Failed to assemble example.s

✘ Name already exists: my_var

The name found here...
  my_var = $49
  ^^^^^^^^^^^^ Duplicate

...was already declared here
  my_var = $48
  ^^^^^^^^^^^^ Original

Additionally, waterbear has a macro system.

%macro  Safe_8bit_Add   %op
  ; Adds an 8bit number to acc and prevents overflow by maxing acc
  ; if detected
  add     %op
  bn      psw, 7, .no_carry%
  mov     #$ff, acc

The error message will help with macro expansion as well, walking you through which macro expansions occured to generate the invalid code.

% waterbear assemble example.s -o example.vms
[ERROR] Failed to assemble example.s

✘ Wrong arguments for instruction add.

          add     %op, 7
  | ...expanded from
  | example.s:16:2-20
  |     Safe_8bit_Add %val
  |     ^^^^^^^^^^^^^^^^^^
  | ...expanded from
  | example.s:19:0-14
  |   Foo 100 + 1000
  |   ^^^^^^^^^^^^^^

Allowed forms for instruction add:
  add #i8
  add d9
  add @Ri

In this example, you can see the ...expanded from sections, showing each step of multiple nested macro expansions.


You can download prebuilt binaries from here: waterbear latest release.


To assemble a file, use the waterbear assemble command:

waterbear assemble example.s -o example.vms



These are people who have either directly or indirectly helped with the development of waterbear.

Name Contribution
Falco Girgis ElysianVMU - VMU Emulator
Kresna Susila VMU assembly programmer/game developer
Marcus Comstedt Author of the aslc86k assembler, softvms emulator, hardware documentation, and tetris VMU game
John Maushammer Author of the lcdis disassembler

Copyright © 2015-2019 Walter Tetzner