Sega dreamcast VMU development tools
C O N T E N T S . . . . . . . . . . . . . . Introduction Resources Disassembler Release 1.03 Assembler Simulator VMU-PC transfer CPU Documentation Potato Chip Hardware (memory map) BIOS Operation Hardware protocols Sample Code  Tools (new vmu animator) Future stuff rest of my homepage other systems I've played with . . . . . . . . . . . . . .

Introduction

Why?? Where else can you get a small processor, a decent screen, lots of memory, a serial port, a buzzer in a case for only $25 (including the batteries!)? It's a great little platform for writing mini games and for little hardware projects. And, these games are easy to share with friends over the internet or in person.
 

Resources

Marcus Comstedt has provided the bulk of the tools to the community and has a very useful website. He wrote the assembler and the emulator, and has an excellent description of the VMU assembly language. He also has described some of the software entrypoints as well, and documented how the game files are saved in memory. He also wrote the first game with publicly available source code- tetris. On this page I've got a Windows port of his assembler and instructions on how to get his emulator running under Linux.

Richard Munn has information on his RAMtronics website (if busy, try my mirror) with some Amiga ports, insides pictures, and an unofficial VMU FAQ. You'll see his name mentioned here a bunch.

The VirtuaMUnstaz are a good resource (they put my name in their scrolling demo!). Leo there started another discussion group; this one is more technical than the pages at Booyaka and has less whining. Visit it at http://www.egroups.com/list/vmu-dev.

Sören Gust has been working on connecting a VMU to a PC and has recently released a really great version of minesweeper, complete with well-documented source code. Check out his website.

Rednuht has some neat utilities and a nice space invaders game at www.jumpstation.co.uk and also some neat utilities.

Alessandro Sanasi has an excellent well-documented "hello-world" type program that can serve as a skeleton for future code. He also has a bunch of utilities for dealing different file formats: A .VMS->.DCI/.VMU creator, a .DCI->.VMS converter, a .VMS checksum calculator, and .LCD to textfile (for use in a source code listing), and an .LCD->.VMS converter (similar to Loren's DC Animator website, but not as fancy and doesn't require use of a website. Also generates animated .GIF's). Check it out on Alessandro's web page.

The whole vmu development scene started at booyaka.com (flame suit on!). Loren Peace, who was one of the first to reverse-engineer the unit, wrote an animator program and runs the site. The animator program has a good following and even allows simple interactions (in a choose-your-own-adventure type way) - there are some really good artists out there. Unfortunately, the maturity level of many posters in the discussion sections have gradually decreased and most of the development community has moved to the the vmu-dev list. Christian Newcomer's vmu animator is similar to the animator at booyaka.

Papa adam has a pimp site -- small arms -- that has a section on the VMU. Check out his site for info on other similar machines - the sony pocketstation, the pilot, the on hand pc, etc. The on hand pc is just about the ideal extension of the VMU - lots of memory, multiple program support, serial, IR, good screen, small, manufacturer provided development kit - but, of course, it comes at a hefty price.

Lastly, and importantly, Sega is now providing technical support to unlicensed VMU developers! Engineer Alexander Villagran and Manager John Byrd have fought to win this for us. Here's what Alexander posted (6/27/2000):

Now of course this might still take a while, but Sega has finally grudingly agreed to look at releasing the VMU development kit to the general public.  They are currently contacting Sanyo (Compiler Developer) and Hudson Soft (VMU Emulator), and finding out if there would be any problem if their tools were released publicly.  I have no idea how long that process will take.  If there is no problem with either company, then the tools will be released.

I would like to thank John Byrd at Sega of America Dreamcast for his help in my crusade.  He is the head of Developer Tech Support, and without his assistance all of this wouldn't be possible.  Just having Sega agree that the VMU development community needs these tools is a great win for us.

I would like to personally invite all VMU developers to sign up to a new mailing list.  The e-mail address is:

subscribe-vmu-coders@soadtslist.sega.com This list is being maintained by the folks here at Sega.  Do me proud, and we will try to answer questions.  We are currently limited in only answering questions on information that is already known. Such as what does the OCR register do, but not how to use the VMU Emulator or the Assemblers.  Once everything is publicly released, then of course our response level can change.

Disassembler
My contribution so far is the first (and still only!) publicly released disassembler. This program takes machine-readable code and turns it into a human-readable format. It's useful for dissecting and analyzing programs that have been released without source code, such as officially released games.

Features:
 - Sanyo LC86104C/108C disassembler, plus extra instructions used by the VMU
 - Actually simulates program execution, tracing all jumps and possible branches. This allows:
 -   Automatic determination of code/data space.
 -   Automatic determination of RAM banks accessed (mostly)
 - Special function registers and BIOS entry points are annotated.
 - Some instructions are automatically commented (i.e. branch if 'A' button pressed)
 - Disassembly output has been tested and found accurate.
 - Either easier-to-read or ready-to-assemble code can be generated.
 - User specification of graphic and font areas (which are commented graphically).
 - Portable GPL C code. (with C++ style comments).

The current release [version 1.04a] is in three parts:  The source code, sample output listing (plus bonus hand-annotated boom.lst), and a windows console ap executable. This program has been successfully tested against Marcus's assembler with boom, football, and Chao -- his assembler generates the exact same .vms file that lcdis took as an input, so if there is an error, it is in both of our programs. This long-delayed first release incorporates a few new features over the beta 0.8 version. Most notably, it has a special BIOS disassembly mode (that alters some of the program flow assumptions), new instruction support, and automatic RAM bank determination. Verision 1.04a is exactly the same as version 1.04, except I put some extra disclaimers in the comments.

The sample listings contain output from lcdis (with additional command-line parameters specific to each program; the effects of these are visible in the memory mapping section at the top of the listing). Boom is a DC Animator program -- It has Loren's DC Animator code and graphics provided by Mike Munn. I've done a pretty complete job of hand annotating this program, with the exception of some misaligned data in the frame section which I can't explain. This program doesn't run well on the simulator, so my .vms file may have been messed up to begin with. Hopefully my annotation will be a good learning resource.

Richard Munn has an Amiga port of this as part of his complete Amiga development system. And, yes, he is the big brother of Mike Munn whose graphics I stole -- what a coincidence!  His RAMTronics site is at http://go.to/rvmu or  http://www.munnfamily.demon.co.uk/rvmu or my mirror

Assembler
Marcus has a great VMU assembler. I have a windows port of version 1.9: vmuasm windows console ap; check with Richard for the Amiga version.

It's relatively straightforward; its usage is

vmuasm {-I<include_directory>} {inputfilename...}

I've also compiled a version 1.5 as a linux command line ap. It's a little old, so you might do best building your own version:  the only conversion required is to add "#include <getopt.h>" to the beginning of file main.c (and then ignore a bunch of harmless looking warnings). This is invoked in a similar fashion:

vmuasm {-I <include_directory>} {inputfilename...}

The main difference between the windows version and the linux version is that the linux version requires a space between the -I and the include directory, whereas the windows version requires that there be no space. For help, type "vmuasm -h". Email me if you want my modified source code; otherwise his is a bit easier to read.

Once you get it, the first thing you'll probably want to do is assemble Marcus's tetris code. It's a good framework for development, and is fun to play, too (I feel crazy playing it on a laptop that plays doom well!). Anyway, get tetris.s and sfr.i from Marcus's site and put them in the same directory as the assembler. Use the command

vmuasm tetris.s

and you should end up with a file called tetris.vms. This is the output file, suitable for use with the emulator, or if you build an appropriate .VMI file and put it on a properly configured website (I'm not too sure about what kind of MIME type to make it), you can get it into an actual VMU.

The assembler doesn't have much documentation, but that's why I suggest you follow the tetris code as an example. One thing that isn't obvious from this file is how local labels work: Local labels are ones that start with a period. Unlike global labels, a local label can be defined more than once in a program. Their scope is bounded by global labels, i.e., you cannot access a local label if a global label stands in the way.

Maybe an example is best:

    global1: ld #$10
    .delay   dbnz acc,.delay
             ret

    global2: ld #$20
    .delay   dbnz acc,.delay
             ret

The local label "delay" can be used twice because it is separated by global label "global2". Each of the two dbnz instructions decrement the accumulator and branches back to themselves.

Simulator
Marcus also has a great VMU simulator. It simulates most of VMU hardware -- enough to run all known Sega binaries -- but since every aspect has not been discovered yet, it is limited by our knowledge.

This program was originally written for X Windows (see below for Linux), but thanks to the nice job Marcus did in making it portable, the simulator is available for many platforms.

David Steinberg made a windows port, and Marcus tweaked it for inclusion in his regular distribution (it'll be in version 1.7). My only (minor) complaint with this program is that the window is too small-- I've started a windows version that will hopefully support an in-real-time resizable window, but development on it has taken a backseat to my hardware debugging.

Colm Cox has a really nice DOS port that runs full-screen or in a dos box under windows. His web page can be found at http://www.fortunecity.com/skyscraper/wav/1190/

Richard Munn has an Amiga port and also a complete Amiga development system. He also has some useful scripts for generating asm code out of graphics. His RAMTronics site is at  http://go.to/rvmu or  http://www.rvmu.port5.com/or my mirror.

Richard Bannister has a MacOS port, plus macintosh ports of lots of other emulators.

I used to host the Linux binaries because at first I had trouble getting it to compile (I'm not much of a linux guru). Then I discovered the ridiculously easy way to install it that Marcus provided - it's probably easier to follow these instructions than to install my binary.

Installation instructions (tested with Red Hat 6.1, but pretty generic):
1. Download the file. I downloaded it in windows, booted linux and accessed it with a mounted dos partition. Or you could just download directly into linux. Anyway, my file name was "softvm~1.gz"
1. Un g-zip it: gzip -d softvm~1.gz
2. Untar it: tar -x -f softvm~1
3. Go to the directory it created: cd vms
4. Run the configuration script: ./configure
5. Make it: make

The simulator has only three options, only one of which is really useful:
-h    Displays a help message: Usage: vms [-h] [-V] [-2] game.vms ...
-V   Displays the version number: softvms v1.0 by Marcus Comstedt <marcus@idonex.se>
-2    Runs with 2x size pixels. The screen is small, even at this double size.

A typical usage is: vms -2 tetris.vms
 

CPU Documentation
The VMU uses Sega's own custom Sanyo LC8670 processor, nicknamed "the potato". It uses the same instruction set and some of the same registers as some non-custom parts, such as the LC86104C/108C processors, but also adds some custom (non-documented) stuff.  You can access Sanyo's datasheets through their clunky interface at http://www.elisnet.or.jp/login-sanyo.htm, or you use my LC86104C documentation mirror. The mnemonics are at the end of the document.

The VMU's processor instruction set is pretty close to the the LC86104C, but with five differences (that have been found, so far).  Most notably, the operation of the MUL and DIV instructions are different, although their encoding is the same.

Marcus has also found out that instructions $48-4F and $58-5F map to "BPC d9,b3,r8", which is a "if bit set, clear it and branch" instruction. It's on his page.

The last two undocumented opcodes are $50 and $51, and I'm going to tentatively name them LDF and STF (email me if you have a better name, these aren't supported in the assembler). The $50 instruction reads the flash memory and works like an LDC except that it doesn't add ACC to the address. The 17th address bit is taken from SFR $154. Opcode $51 writes the flash, but it has a safeguard which makes it a bit more difficult to use.

Check out Richard Munn's page for his VMS-ectomty to see the innards and find out why people call it the potato!
 

VMU2PC Parallel Port Loader
Of course, the best simulator is the actual VMU. But getting an assembled file to a VMU has been -- up to now -- difficult to do. The two ways to do this: You could upload your code to a VMU-friendly web server (one that can control MIME types), and then use a dreamcast to dial in to an ISP and get that page and transfer it to the VMU. The other way was through Sören Gust's setup: A special PC board with a custom-programmed microcontroller would translate the 3.3volt synchronous serial protocol of the VMU to an asynchronous protocol used on most computers. The problem with this is that it requires a lot of specialized hardware (but on the plus side, it is compatible with just about any type of computer).

Now, there's a third option: A simple parallel-port adapter to connect a PC to a VMU. Sören's code was pretty modular, so it was easy to modify his code to substitute in PC parallel port-specific routines for his serial port routines. My code is still really ugly; I'll be cleaning it up. And it relies on processor loops for timing (not too good!). Also, since I poll the parallel port to read the VMU's clock, I need 100% of the processor's time... so a lot of the time interrupts are disabled (which makes late-night MP3's sound really bad). There is a timeout so it shouldn't hold the computer up for more than about 10 seconds. Finally, the verbose mode probably doesn't work. That's why I'm calling this an alpha version -- it's not quite ready for prime time. But, these routines work for me and at least two other people, so there is a good chance that they will for you.

Here's my disclaimer. Please read it:

Use at your own risk. You may damage your PC and/or VMU. Not for the faint of heart. I'm assuming that the VMU isn't 5 volt compatible, so make sure you take precautions to not over-drive it. This is especially important on its *outputs* because PCs tend to pull up their inputs to +5 volts (even though they sometimes drive at 3.3v).
Test it! I can't be responsible for any damage! You've been warned!

The adapter should have these connections:

LPT Pin In/Out LPT Signal Name      VMU Pin  VMU Name               #define
------- ------ ---------------      -------  ---------------------  -----------
   2     I/O   Data Bit 0              12     PC2VMU clock          OUT_CLK
   3     I/O   Data Bit 1              10     PC2VMU data           OUT_DATA
   4     I/O   Data Bit 2               4     PC2VMU delayed data   OUT_DLYDATA
   5     I/O   Data Bit 3               6     PC2VMU handshake      OUT_HSK
  10      I     -ACK           ***      3     VMU2PC clock          IN_CLK
  11      I     BUSY           ***      5     VMU2PC data           IN_DATA
  13      I     SLCT           ***     11     VMU2PC delayed data   IN_DLYDATA
18-25    ---    Ground                7,8     Ground
                                      1-14    Make sure these are connected to each other
                                             so that the VMU's drivers are enabled.

*** Also connect these pins through 4.7kohm resistors to ground. You need a total of 3 resistors.
    (note: depending on your parallel port, a different value may be needed. If you want to
    live dangerously, you can omit them (but I didn't and wouldn't recommend it))

I didn't build a connector for the VMU. I opened one up and soldered wires from the inside directly to my DB25 connector. I transfer data to this VMU only, then disconnect my PC and connect up another VMU (one that doesn't have the delicate wires hanging off the end) and transfer the file to that VMU.

Here's the software. I've included the source along with the executables. Please read the source file lowlevel_dosparallel.c -- it has more detailed comments, including deficiencies, future improvements, and a more complete parallel port description.

Enjoy. I had hoped to clean this up and re-integrate it with Sören's original code, but he's beaten me to it-- you may want to download his version. He did a great job figuring out the protocol.
 

Potato Chip Hardware
It's really the hardware that differentiates a computer and not just the instruction set. The disassembler allows us to watch a real life program interact with the hardware registers, and hopefully we can determine what register does what.  This is substantially complete - it has some information on music generation and vmu-vmu communication, but is not complete or 100% tested.

I've started to document all the registers (updated 9/7/00 or so); this data is mostly from Alexander (SFR names), the databook, from disassembling programs, Marcus's experimentation, contributions to the vmu-dev list, and a bit from the sega vmu-coders list.

The computer has 128KB of non-volatile FLASH memory (for game and data storage), 24K of ROM, and 1K of RAM.  The basic computer was only designed to access 64K of code and 256 bytes of RAM, so there is a lot of bank switching that goes on. For a good graphical description, check out the VMU memory map that I made.

BIOS Operation
I've got a page detailing the entry points and variables used by the BIOS.
 

Hardware Protocols
See my page devoted to hardware protocols (sortof outdated, but with a cool picture) and also check out Sören Gust's website.
 

Sample Code
What fun is this all if you don't write neat programs? I thought I'd cut my teeth on a version of pong. It's still in major development, but here's pong beta [version 0.2, now with better "ball feel"]  I've improved it enough that I've got the source code to share. It seems pretty slow on Colm's emulator and on a real VMU, but fast on Marcus's linux port. Apparently even the Sega emulator isn't timing accurate. Currently this program has a lot of delays built into it, so it can be tweaked to run much faster, but I've had problems getting the delay loop to run at the slow speed. I think that's due to the emulator; I don't have the patience and/or time to test it extensively on a VMU.

This demo shows a partially done title screen (with just my name so far)-- press 'a' to continue to the game. The game screen appears; press "A" to serve the first ball. The paddle is moved using the left and right buttons. If you miss, you'll lose a ball, and of course, when you're out of balls the game restarts. You can put english on the ball depending on what part of your paddle is hit -- this feels better than what I had before which required you to be moving the paddle to spin the ball. You may also notice that the ball goes right through the bricks. Let's just say it's a really heavy ball and that the bricks are actually dust bunnies. That's the major thing missing right now- the bricks are inert.

I don't have a .VMI file for the DC, so you'll have to run it on the emulator or use my loader. One high point of the program is my carefully tuned point-plotting routine. (When 99% of the game is moving a ball around, you've got to get it right!) The registers it takes may not be the best for all situations, but it is pretty fast.

A lot of other people have written programs and provide the source code. Alessandro Sanasi has an excellent well-documented "hello-world" type program that can serve as a skeleton for future code, as well as a (yet) undocumented pacman game.  Marcus Comstedt has a classic version of tetris. Antoine 'MORB' Chavasse has a really neat graphics program (a "rotoscope") that shows a spinning pattern. Rednuht has has a really nice space invaders program with enjoyable documentation -- the program also has a set of sprite routines that can be reused.

And Sega has released some code via the vmu-coders list. This code is intended to illustrate serial port communications, but it also clears the screen and prints characters on the screen. It's intended for the Sega's tools-- so it won't work with Marcus's assembler-- but it illustrates the point. The three programs are ghead.asm, sio1.asm, and sio2.asm.
 

Tools (new!)
I was planing on making this section a link to a bunch of development tools, but it's a bit incomplete right now. There are many tools to generate .vms and .vmi files for different platforms.

Christian Newcomer's vmu animator is similar to booyaka's DC Animator, except that it works off-line, allows you to download directly from a PC (via the parallel port), and also outputs assembly-language source so that you can extensively customize the output.

BMP2ASM, written by  NeuroS, is a really nice program for converting a windows .bmp bitmap file into ready-to-use assembly code. It can generate either a vmu game icon, or a general purpose sprite. The code generated is compatible with the Marcus's aslc86k assembler. Source and several examples are included; the executable is for windows.
 

Future Stuff to Figure out
Some things that would be nice to find out. We've accomplished a lot of these things and the list is shrinking!
 

• VMU<->VMU and/or VMU<->dreamcast communication protocol (both electrical and logical)

[marcus has worked on the maple bus (dc-vmu), and Sören and I have worked on the VMU-VMU case]
• Built-in source code listing (aprox. 28K) [you can read the object code from your vmu, working on source!]
• FLASH programming specifications [marcus figured out how to make the built-in firmware do this, I've documented the low-level portion]
• how to build a PC simulator/emulator [done already!]
• how to program a VMU from a PC [Sören has done this, but, with dedicated hardware; my nice parallel port version is in Alpha]
• more info on the VMU's serial port (vmu-to-vmu) interface  [sega was nice enough to give example code]
• more info on the VMU's maple (dreamcast) interface [marcus has taken the lead on this]
• how to enable the 3D holographic display (maybe that's just a vicious rumor)
• more about the VMU MP3 player. It's not supposed to be able to play mini games, but then again, VMUs were only supposed to play Sega-made games.

my homepage

last updates: 5/7/00 [VMU2PC Alpha Release (who-hoo!)], 6/31/00 [wow- it hasn't been updated in a while! I added vmu-coders info and more info on the serial port], 7/26/00 [welcome people from my old site... sorry about not posting links to the new improved site sooner; vmuasm 1.9; more potato info], 9/7/00 [updated some links], 12/15/00 [Added tool section & bmp2asm, shameless link to vista page, top of this page is now a table], 4/14/01 [Added Christan Newcomer's vmu animator], 7/1/01 just a bit of touchup. Wow it's been a lot of fun! Too bad sega is getting out of the hardware market. 1/21/2001, A little more touchup.  6/24/2005, added O'Reilly book link below.

A good overview of the VMU programming scene  (and a bit more information on newer applications developed after I stopped playing with the VMU) can be found in the O'Reilly book "Gaming Hacks: 100 Industrial-Strength Tips & Tools."  A free chapter (in PDF format) is available for download from the official book website: Hack 52: Hack the Dreamcast Visual Memory Unit.

legal: this page is not affiliated with Sega .  And this page is not affiliated with  , Transmeta, or , either. Use this information at your own risk. "Sega" and "Dreamcast" are trademarks of Sega Enterprises, Ltd. Also, this notice was written without legal counsel and may be totally ineffective at warding off lawsuits and/or amway distributors. The theory here is that you'll email me and I'll fix whatever-it-is before you sue me. One really interesting court case concerning reverse engineering of software is Sega v. Accolade 977 F2d 1510 (9th Cir. 1992) and is worth the read.