VMU development

From dreamcast.wiki
Jump to navigation Jump to search
Various different faces of the VMU

Developing standalone games for the Sega Dreamcast's Visual Memory Unit or "VMU" (also known as VMS) is both a challenging and rewarding development feat. On one hand, it's not the easiest embedded device to target, given that it doesn't have a C compiler and has its own set of hardware eccentricities. On the other hand, the device features a rich instruction set, 3 different clock sources, a FAT filesystem, and many different peripherals which can be leveraged by a developer, making it something of a Sega Saturn of little 8-bit gaming devices.

While there is an active and ongoing effort within the scene to lower the barrier of entry into VMU development and to get more high-quality tutorials and materials out there for newbies, this page will hopefully serve as an entry point based on what is currently available and will be updated every time a new resource is found or new discovery is made.

Hardware

VMU's multiple segmented and banked address spaces
VMU System Block Diagram

A high-level overview of the VMU's technical specifications can be found here. A good initial look at application-development for the device can be found at Marcus Comstedt's VMU Programming Site or the ElysianVMU Hardware Docs. A combination of these sites and the official VMU Development Manual is typically what is referenced while programming for the VMU. Between the two, a developer should have all of the hardware documentation necessary to cover the following concepts:

  • Address Spaces, memory segments and banks
  • Opcodes and instructions
  • Addressing modes
  • System vs application execution
  • Built-in firmware routines
  • Special Function Registers (SFRs)
  • Interrupt service routines and their configuration
  • Controlling clock and oscillator circuits
  • Driving the LCD display by writing to XRAM
  • Reading/Writing to extra Working Memory (WRAM)
  • Controlling the Base Timer, and 2 Timer/Counter peripherals
  • Driving the piezoelectric Buzzer for sound output
  • Detecting button presses on Port 3
  • Low-battery detection circuit and configuration
  • Serial communications via the 2 SIO interfaces

Programming

Since there is no C compiler for the VMU's 8-bit Sanyo CPU, development is traditionally done in Sanyo LC86k assembly language; however, it is now also possible to write C code indirectly targeting the device via emulation of the ARM Cortex M23 CPU.

C

Thanks to the uM23 emulator, it is now possible to indirectly write C code for the VMU. The code is cross-compiled for the ARM Cortex M23 target, and the resulting binary image is then loaded onto the VMU as a "DATA" file. The uM23 emulator, which must be loaded onto the device as the main "GAME" file, will then allow you to select an ARM binary image to run from its menu. More information can be found here.

LC86k Assembly Code

waterbear

The waterbear assembler/disassembler is the favored tool for creating VMU binaries, as it is cross-platform, is feature-rich, supports all undocumented opcodes and SFRs, and is still under active development.

LibPerspective

Due to the non-contiguous, banked nature of XRAM, it is actually a nontrivial engineering feat to blit an image to the LCD screen. LibPerspective is a simple rendering library developed to aid in such tasks. It is frequently used in modern VMU homebrew and will enable you to work with rendering bitmaps to the display much more quickly. More information can be found here. A newer, maintained version of the LibPerspective codebase can be found here, already featuring a couple bugfixes.

Beginner's Tutorials
Screenshot from Marble_Grainite's first VMU Dev Lesson

Candle-Electric, aka "Marble_Granite" has begun working on a series of beginner-focused tutorials which can be found on GitHub. Unlike many of these resources, this set of tutorials is brand new, is using the latest recommended tools (LibPerspective, Waterbear, ElysianVMU). It walks you through the process from using the tools and assembling code to drawing to the framebuffer and getting input, with more tutorials on the way.

VMS Tetris
Marcus Comstedt's "VMU Tetris"

The source code to Marcus Comstedt's VMU version of Tetris serves as a a great beginner resource, as it is well-commented and is a fairly complex game. The source code can be found here.

Audio Driver (ADVM)

jvsTSX has released an audio driver called ADVM open source on github. This is some pretty advanced buzzer usage with well-written code including comments, most likely the deepest the homebrew scene has gone with this peripheral. Definitely something to be checked out for doing any sort of audio signal generation on the device.

Tiny3D Engine
Tiny3D Engine in Action

Tiny3D Engine is a full-fledged 3D rendering engine, complete with OpenGL-style matrix stack, matrix/vector transformations, perspective matrix and division, line rendering and clipping, and 16-bit fixed point math routines. It was developed by The Rockin'-B and was originally released as a demo ROM featuring the engine with a menu that allowed for the configuration of the underlying 3D primitive and transformation matrix. The ROM and full source code can be found here.

Scrolling Text Demo

The source to a scrolling text tech demo by VirtuaMUnstaz can be found here: File:Scrolling Text Tech Demo.zip.

Raining Squares

Raining Squares is a tech demo which serves as a great example for newbies to the platform. More information can be found here.

Skeleton Application

The code for an example skeleton VMU application by Tyro can be found here: File:Skeleton VMU Application.zip

VMU Racketball
VMU Racketball Screen Capture

VMU Racketabll is an open-source VMU minigame developed by pxcla (Shirobon), which has been made available on github. It contains fantastic comments and has been developed with the intention of serving as a kind of tutorial/learning tool for VMU developers as well.

Advent Wreath

Advent Wreath is a VMU application developed by Marble_Granite, that was released to commemorate the 24th anniversary of the Dreamcast and the 1st day of Advent. It demonstrates button input, impressive animations, and grayscale effects. Its source code can be found here.

Official Demos

An assortment of (older) tools and demos adapted from the official documentation has been compiled by frozenbinarystudio from the DCEmu forums and is available here: File:VMU Development Resources.gz

BIOS Disassembly

An ongoing effort to completely document the BIOS and firmware routines can be found here. This is how many discoveries were made about features and behaviors which were intentionally left undocumented within the Developer Manual.

VMU Script

A long-lost and forgotten VMU-specific pseudo scripting language which was around at the time of the Dreamcast's commercial lifespan and was used in at least one shipping commercial game. Unfortunately the language and tools have been lost to time.

These pages that were saved in the Wayback Machine appear to be the only bits of VMUScript left on the internet:

LIME

Dream Animator Tool for creating VMU Animations

Another lost VMU-specific language. Again, there are some pages preserved in the Wayback Machine:

Dream Animator

While not technically code or a programming language, the VMU Animator tool allowed for the easy creation of VMU animations or movies. These animations could then be exported to a VMS GAME file which could then be played on the actual device. Many of these animations are circulating around today, and the Booyaka website was an entire community based around them. Unfortunately the tool is rather dated and may not run under modern Windows. It can be found here: File:VMU Animator.zip. Note that the ElysianVMU emulator can play the intermediate .LCD files but cannot create or modify them.

Amiga VMU Devkit

A sample screenshot of the Amiga VMU development kit.

This was a complete development kit for the AmigaOS systems, it included well known development tools such as the Aslc86k assembler, SoftVMS emulator and LCDis the disassembler. It also includes tools suited to the Amiga's workflow, Such as AREXX scripts for auto-launching SoftVMS from Workbench when you have double clicked a VMS/VMI file, Amiga CD32 controller support for SoftVMS, Personal Paint Macros for creating VM graphics and icon data, a selection of icons to match in with the various makeovers that Workbench received. It can be found here.

DC Anim

DC Anim is another tool that allows you to edit and create your own VMU animations, supporting the same file format used by Dream Animator. It is available both as a Windows XP binary and as the source code.

BMOVIE

BMOVIE Promo

BMOVIE was an incredibly ambitious, technically impressive video encoder for the VMU, created by a homebrew VMU and Sega Saturn developer who went by "Rockin-B." It could create highly compressed animations for the device which could be exported then embedded into other applications. It supported extremely long animations, playback in reverse, and later on emulated grayscale effects via pixel ghosting. While it unfortunately seems as though the actual encoder tool, playback code, and documentation are lost to time, several tech demo videos still survive today as ROMs which prove it was more than just a myth. Rockin-B has since disappeared from the VMU and Saturn scenes without a trace, and any attempts to contact him have been in vain. What's left of his site can be found here.

Testing

Emulators

ElysianVMU's Flash Editor and Filesystem Manager

The favored emulator for VMU development and testing is the ElysianVMU emulator, as it is cross-platform, is ranked top for features and accuracy, and is still actively developed. The emulator also has an explicit goal of offering a debugging environment to facilitate development. Much of the debugger is still under active development; however, just features like the RAM and flash memory explorer widgets can be of great use during development. More information on EVMU as well as other VMU emulators can be found here.

Physical Device

Before publishing or distributing your game, it is highly recommended that you still test on physical hardware. There are various ways through which one can get a GAME file onto the actual device depending on your Dreamcast's configuration and peripherals.

  • VMU Tool (AKA Dream Explorer)
  • DreamShell
  • Web Browser
  • Nexus Memory Card
  • KOS VMU Game Loader Example

Tips and Tricks

Grayscale Graphics

Several VMU games emulate grayscale graphics by alternating a pixel between black and white, where the resulting shade of gray that is produced is a function of the alternation frequency. This is possible due to the physical hardware characteristics of the LCD screen, as a pixel is not instantaneously lit, but rather has a small "fade-in" period. The ElysianVMU emulator attempts to emulate this behavior with the "pixel ghosting" option.

Serial Communications

VMU-to-VMU serial connectivity

Serial communications are the indie holy grail of the VMU, representing one of its final frontiers which has been virtually completely unexplored. Even commercial releases very rarely utilized it. The official Sega documentation contains several examples for driving VMU-to-VMU serial communications, and we are in the process of creating our own documentation here.

Unconstrained Flash Access

While the BIOS-provided flash operations constrain reads and writes to within the boundaries of the GAME file, it is possible to write and read directly to and from flash using the STF and LDF undocumented VMU instructions (supported by Waterbear) respectively. These instructions are what the BIOS uses to implement the higher-level firmware calls. Several homebrew games and applications have leveraged these to access other files stored within the VMU. One example is Dmitry's uM23 emulator using LDF to read ARM binaries as separate "DATA" files on the same filesystem.

USB-Powered VMU Mod

If you're constantly finding yourself in need of replacement CR2032 batteries during development, consider doing the USB Powered VMU Hack on a spare VMU.

AA Battery VMU Mod by Jeff Chen

AA Batter-Powered VMU Mod

Another fantastic modification you can do to save yourself CR2032 batteries is the modification to power the device with a pair of AA type batteries, thanks to Jeff Chen. More information can be found here.

Sublime Text Syntax Definition

A syntax Sublime Text syntax definition for the LC86k assembly flavor, including instructions and SFRs can be found here. This makes Sublime Text a pretty decent development environment for working with VMU assembly.

PC to VMU

Testing your software on a physical VMU can be quite challenging, there have been a number of different attempts to achieve this. Currently most people place their .VMS on an SD card and load on the Dreamcast with the Serial SD card adapter and a copy of Dreamshell.

Before the SD card adapter however, developers used dcload-serial and Dcload-ip to test their software on real hardware. There was even some attempts to create a cable to link the VMU to the PC directly either by using a serial port or a parallel port, you can read more about this here.

6Mhz VMU

The VMU actually contains an incredibly fast 6Mhz CF oscillator circuit, which is only enabled when the VMU is plugged into the Dreamcast controller, supplying it with external 5v power. The purpose of this oscillator is to power the BIOS implementation of the Maple stack, which has to service requests from the Dreamcast to read/write flash, play tones, check input, and display images, all done in software.

Recently, it has been discovered that this CF oscillator can be enabled even while the VMU is in standalone GAME mode by setting bit 4 of OCR to '1', with bit 0 reset to '0'. This will allow you to do substantially more with the VMU's CPU; however, it will destroy its battery life. Fortunately, we now have power supply mods which can power the VMU via sources such as USB or AA batteries, offsetting the additional power consumption. To date, no application has ever taken advantage of this clock; however, jvsTSX has constructed a demonstration of this in his SPEEDTEST.

Dual-Tone Buzzer Audio

Despite the fact that the hardware documentation claims that Timer 1 mode 1 is "typically" used for tone generation, and despite the fact that every known game/app for the VMU with buzzer output uses this method, new research has shown that Timer 1's mode 3 "variable length pulse generator" is actually capable of producing a much larger variety of more impressive sounding tones. Mode 3 allows you to configure two separate square waves, one with a larger period, and one with a smaller period, which are combined together for PWM output into the buzzer. This allows you to conceptually create a high and a low tone simultaneously with a single PWM output pin. A demonstration of this has been created by jvsTSX and can be found in his SOUND3_TEST.

Community

If you have any questions, want to share your work, would like to contribute in any way, or would like to hang out with a community of other people interested in VMU and Dreamcast development, try the following links:

  • DCEmulation Forums - One of the biggest, most prolific Dreamcast web forums, with a technical goldmine of information
  • Simulant Discord - The main hangout spot for Dreamcast developers within the scene
  • Elysian Shadows Discord - The main hangout spot for developers of the VMU "subscene," including the authors of WaterBear, ElysianVMU, uM23, etc

References

Retrieved from "https://dreamcast.wiki/wiki/index.php?title=VMU_development&oldid=3176"