# GXemul: Dreamcast emulation

Back to the index.

This page contains information about the Dreamcast emulation mode in GXemul. My main goal with Dreamcast emulation is to let NetBSD/dreamcast run, similar to how it runs on a real machine. I am also experimenting with other programs, such as Linux and simple demo programs that use KOS, and Marcus Comstedt's tutorial programs. These sometimes work to a certain degree.

Games (especially commercial games) are very unlikely to run.

### Running raw binaries (IP.BIN and 1ST_READ.BIN):

(Note: This is very experimental, as GXemul's Dreamcast emulation is very incomplete, but in principle it could be used as a help when you are developing your own code to run on the Dreamcast. For example, it may be easier to debug things in the emulator than on the real Dreamcast.)

According to http://mc.pp.se/dc/ip.bin.html, the Dreamcast loads files from the last data track (from track session 2?). The data track should be an ISO9660 file system, with the first 0x8000 bytes used by a Dreamcast-specific boot block.

When a Dreamcast boots up, the ROM loads the boot block and first file as follows:

- The first 0x8000 bytes from the data track (usually called IP.BIN, but it has no name on the actual CD) is a boot block, which is loaded to virtual address 0x8c008000. This contains executable SH4 boot code, but also some text strings, and the name of the first file to run, usually "1ST_READ.BIN".
- 1ST_READ.BIN (or whatever the boot block said) is loaded from the regular ISO9660 file system on the CD, to virtual address 0x8c010000. For CDs (note: not GD-ROMs), the file is block-scrambled in a specific way.

Execution first starts at 0x8c008300, 0x300 bytes into the boot block, and the code here displays the SEGA logo and waits for a while. The code then returns to the ROM, using a system call. The ROM code then calls 0x8c00b800. In GXemul, this is currently only done when booting from a CDROM image (or by forcing this mode by jumping to 0x8c000140), so to boot manually, it's easier to skip the SEGA logo display.

When loading files directly from the host's file system, the examples below assume that the binary TEST.BIN is an unscrambled binary, since it is read straight into GXemul's emulated memory. If you have a scrambled binary, 1ST_READ.BIN, making a complete ISO may be the best way to go. This can then be booted (or attempted to be booted) in GXemul using the `-d name_of_image.iso` option.)

There are several ways to start running binaries:

To manually start at 0x8c008300, i.e. show the logo:

    	gxemul -XEdreamcast 0xac010000:TEST.BIN 0x8c008000:0:0x8c008300:IP.BIN

To manually start at 0x8c00b800 (Bootstrap 1), i.e. skip the logo and allow bootstrap code to jump to 0x8c010000:

    	gxemul -XEdreamcast 0xac010000:TEST.BIN 0x8c008000:0:0x8c00b800:IP.BIN

Starting at 0x8c000140 fakes a boot from CDROM, i.e. the emulated ROM calls 0x8c008300 first, and then when that code returns, it calls 0x8c00b800:

    	gxemul -XEdreamcast 0xac010000:TEST.BIN 0x8c008000:0:0x8c000140:IP.BIN

This does not always work very well, though, because graphics may be initialized in a way which is not understood by GXemul yet.

Note that IP.BIN is loaded last, because that also sets the initial program counter.

And last, but not least, skip the IP.BIN part alltogether and just run the binary you are interested in:

    	gxemul -XEdreamcast 0xac010000:TEST.BIN

See http://mc.pp.se/dc/ip.bin.html for more details on IP.BIN and 1ST_READ.BIN

Almost none of the Dreamcast's hardware is actually emulated by GXemul so far (sound, textured graphics, etc), but a simple 256-byte demo works:

To run the roto demo:

- Go to http://www.pouet.net/prod.php?which=7050 and download http://www.boob.co.uk/files/roto.zip.
- Extract roto.bin from the zip file.
- Start GXemul like this:

      	# Starting using bootstrap code in IP.BIN:
      	gxemul -XEdreamcast 0xac010000:roto.bin 0x8c008000:0:0x8c00b800:IP.BIN

      	# or easier: starting the raw binary by itself:
      	gxemul -XEdreamcast 0xac010000:roto.bin

Another example is Marcus Comstedt's "Serial upload slave" program. Extract IP.BIN from http://mc.pp.se/dc/files/serial_slave.tar.gz. Then launch it in the emulator like this:

    	gxemul -X Edreamcast 0x8c008000:0:0x8c000140:IP.BIN

According to Marcus' page, `?` prints out the version number (V103 in this case), and it handles `S0`, `S3`, and `S7` SREC line entries. `S7` causes it to print `OK` and start the uploaded program. Here is a screenshot where a hobby operating system kernel (YCX5/dreamcast) is launched this way, by pasting the SREC entries into the window called "SH4 SCIF":

Here is another example with a 3D test program ("gltest.bin") from the KOS examples, which more or less works:

### Experimenting with ROM dumps from your own machine:

As mentioned above under the Running raw binaries section, the emulation of Dreamcast hardware is not correct enough to run things that really rely on the hardware functioning properly such as games. Even more picky about the hardware is the original ROM itself. Even though running an original Dreamcast ROM in the emulator does not really work, it can be fun and/or interesting to experiment with.

The first step is to dump the ROM contents (and possibly flash memory) of your Dreamcast.

- `0x00000000 - 0x001fffff`: ROM bios (2 MB)
- `0x00200000 - 0x003fffff`: Flash (256 KB) (128 KB according to http://mc.pp.se/dc/flashmem.html)

There are several ways to dump these. I wrote a simple program which displayed memory contents as white and black squares on the screen, and recorded it with a web cam, and then wrote another program to look at those images and dump the resulting bytes into a file:

(Here shown running in the emulator rather than on real hardware.)

If you don't feel like writing your own dumping program, there are programs already written by others that can e.g. send the contents of memory over http over ethernet (see https://www.youtube.com/watch?v=DVowfmrifN8 for an example). Nomatter how you dump your Dreamcast's ROM bios and flash memory, they should end up in two files. Common names on the Internet seem to be `dc_bios.bin` and `dc_flash.bin`, so let's call them that.

In principle, to start GXemul and load your BIOS and Flash memory images, the following command line should be used (-Q means to not do PROM emulation in software):

    	gxemul -X -Q -E dreamcast 0x200000:dc_flash.bin 0x0:dc_bios.bin

Unsurprisingly, one of the first things the ROM BIOS boot code does is to copy itself from ROM (physical address range `0x00000000 - 0x001fffff`) into RAM (virtual address range `0x8c000000 - 0x8c1fffff`). However, some of the ROM memory range (`0x00004300 - 0x000052fc` I think) is still accessed later on.

It is also possible to attempt to launch a BIOS in RAM only, skipping the ROM-to-RAM copying, by setting the initial PC to use after loading the BIOS image. For the specific BIOS image in my Dreamcast, the PC to use is 0x8c000120. GXemul does not currently emulate the hardware well enough to get past a never ending loop at the start, so I also have to use the following `put` command to patch the BIOS in memory to get past that point.

    	gxemul -X -Q -E dreamcast -c 'put h 0x8c0d7df6,0x8800' 0x8c000000:0:0x8c000120:dc_bios.bin

After getting past the never ending loop, the "set date/time" dialog appears. Presumably it finds a mismatch between what it sees in the Flash memory (stored date/time) and the emulated RTC chip's date/time. After pressing "U" (for "left") and "A" on the keyboard, the main menu is reached.

The graphics is wrong; it is a work in progress, everything has to be reverse-engineered and double-checked both with the BIOS and with homebrew programs and developer examples. Wire-frames can be turned on by defining `DEBUG_RENDER_AS_WIRE_FRAME` in `dev_pvr.cc`. It is also exceedingly slow, since it is done in software. (A possible future enhancement could be to make use of the host's OpenGL hardware.)

The following keyboard keys correspond to controller inputs:

    	             8 Up                          A B C D X Y Z = Buttons
    	4 or U Left               6 or O Right     S             = Start button
    	             2 or K Down

There are no analog inputs yet.

### NetBSD/dreamcast GENERIC_MD:

It is possible to run NetBSD/dreamcast in GXemul. A NetBSD ramdisk kernel can reach userland, however, no network interface is emulated yet, so root-on-nfs is not possible.

The photo on the right shows NetBSD/dreamcast running both on a real Dreamcast, and in the emulator. Unfortunately without a keyboard...

Download the kernel here:

    	ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-8.0/dreamcast/binary/kernel/netbsd-GENERIC_MD.gz
    	ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-8.0/dreamcast/binary/kernel/netbsd-GENERIC_MD.symbols.gz (optional)

If you downloaded the symbols, gunzip them before proceeding.

Start NetBSD/dreamcast using the following command line:

    	# Without symbols:
    	gxemul -XEdreamcast netbsd-GENERIC_MD.gz

    	# With symbols (makes single-stepping and tracing more meaningful):
    	gxemul -XEdreamcast netbsd-GENERIC_MD.symbols.gz netbsd-GENERIC_MD.gz

### NetBSD/dreamcast Live CD:

According to http://mail-index.netbsd.org/port-dreamcast/2005/04/25/0000.html, Rui Paulo has made available a NetBSD/dreamcast Live CD. It can run in GXemul:

The image is available here:

    	http://netbsd.student.utwente.nl/rpaulo/

NOTE (February 2007): The ISO image seems to have been removed from the server, but you should be able to create one from scratch using instructions available at various locations on the Internet.

Only the ISO9660 filesystem image is needed:

    	http://netbsd.student.utwente.nl/rpaulo/livecd.raw.bz2

Uncompress the CD image (using bunzip2), and type the following command to attempt to boot directly from the image:

    	gxemul -XEdreamcast -d co23965696:livecd.raw

(The `c` disk image option is necessary to treat the raw file as a CDROM image, and the `o` part is needed because the ISO9660 filesystem in the image is offset by 11702 sectors, i.e. 2048 bytes each, and GXemul was unable to guess the offset by looking at the ISO header.)

At the `root device:` prompt, type `gdrom0`. For `dump device`, `file system`, and `init path`, just press Enter.

### Linux/dreamcast Live CD:

A Linux/dreamcast Live CD ISO image can be found here:

    	http://ftp.riken.go.jp/pub/misc/Japan/m17n.org/super-h/CD-R/lc2000.iso

NOTE (August 2014): The ISO image seems to have been removed from the server!

Once you have downloaded the ISO image, type the following command to boot directly from the image:

    	gxemul -XEdreamcast -d lc2000.iso

(It seems that this specific iso image was built using instructions from http://www.anytux.org/doc.php?doc_id=1.)