Dreamcast GameDev with KOS and Bash on Windows

Posted August 1, 2016 10:00 AM Categories: Dreamcast | GameDev | Gaming | Windows 10

Many years ago, an open-source Sega Dreamcast SDK known as KallistiOS (KOS) was started and is still being updated today.  I used this SDK awhile ago to create a few emulators that were published, and a variety of unfinished games that were not...

KOS is easy to get up and running on a variety of platforms, but on Windows this always required setting up Cygwin.  But, with the addition of the Linux Subsystem for Windows (LXSS) in Windows 10 Anniversary Update, one can now run Ubuntu and the Bash shell natively in Windows 10, and that means one can easily setup KOS, the SH4 toolchain and (almost) everything else required to develop and deploy apps to a Sega Dreamcast.  Here's how…


  • A Sega Dreamcast capable of booting MIL-CDs...this is any machine manufactured prior to October 2000.
  • A Dreamcast Broadband Adapter (HIT-0300 or HIT-0400 both work)
  • The Dreamcast plugged into your network via Ethernet
  • The Linux Subsystem for Windows installed and configured

Updating LXSS

Make sure you upgrade the subsystem by issuing these two commands:

sudo apt-get update
sudo apt-get upgrade

Downloading and Building the Toolchain and KOS

Once completed, you will need to install a few packages required to retrieve and build the SDK and tools:

sudo apt-get -y install git make gcc texinfo libjpeg-dev libpng-dev subversion genromfs libelf-dev

Now that the appropriate packages are installed, make sure you're in your home directory and then download the KOS repos:

git clone git://git.code.sf.net/p/cadcdev/kallistios kos
git clone git://git.code.sf.net/p/cadcdev/kos-ports

Next, you need to download and unpack the toolchain bits used to build the Dreamcast toolchain:

cd ~/kos/utils/dc-chain/

That unpacking process will not display any output and may take a long time, so don't cancel!

With the packages unpacked, you can now build the toolchain.  This process builds a compatible compiler (gcc) and other tools for the Dreamcast's SH4 CPU.  While in the same directory as above, run:

sudo make

This will take a while, so be patient...

With that complete, you now need to setup your Bash environment so the SDK and tools can be found and used.  First, copy the following file and change its permissions:

cp ~/kos/doc/environ.sh.sample ~/kos/environ.sh
chmod 777 ~/kos/environ.sh

Next, edit the environ.sh file we just copied to point it at the tool location.  To do this, I use use nano, but any other text editor is fine:

nano ~/kos/environ.sh

Look for the entry exporting KOS_BASE and set it to the following:


Obviously, replace YOUR_USERNAME with your username.  Mine looks like this:

export KOS_BASE="/home/brian/kos"

Next, look for the entry exporting KOS_LOADER and add the following prior to the -x argument:


...where IP_ADDRESS is a valid, unused IP address on your network.  Mine looks like this:

export KOS_LOADER="dc-tool -t -x"

A note on the IP address:  You cannot choose any IP in the world...it must be valid in your own subnet (probably 192.168.X.X or 10.X.X.X or similar), and it must not be used by any other device on your network.  Check your router for valid choices and more information.

Finally, edit the .bashrc file in your home directory:

nano ~/.bashrc

...and at the very bottom, add this line so the environ.sh file you just edited gets run at login:

. ~/kos/environ.sh

Don't forget the period as the first character!

Now, exit and restart Bash on Windows.  To make sure the environment is setup, use the printenv command and you should see a variety of environment variables listed starting with KOS_ listed.

Next, KOS itself needs to be built.  To do this, change into the kos directory and run the make command:

cd ~/kos

Once completed, build the kos-ports project:

cd ~/kos-ports/utils/

And finally, build the KOS example projects:

cd ~/kos/examples

A few of these examples may not build but don't worry about that for now.

Downloading and Building dcload-ip

Next up, you will need to download and build the dcload-ip tool.  This is what will allow you to deploy a game to a retail Dreamcast over the Broadband Adapter (BBA).  Change back to your home directory, run the following:

cd ~
git clone git://git.code.sf.net/p/cadcdev/dcload-ip
cd dcload-ip
sudo make install

You may see an error about /usr/local/bin existing on the final step, which is safe to ignore.

Now, you will need to burn the host dcload program to a CD so we can run it on the physical Dreamcast machine and upload our binary.  But, here we have to cheat.  Because the Linux Subsystem for Windows doesn't yet have hardware support, it can't talk to a CD-R drive.  But, I have put together a quick package that contains the required tools and the cygwin libraries to run them.  You can download that package here:

dcload-disc.zip (1.42 mb)

Unzip this somewhere on your machine, then open an admin Windows command prompt (not Bash) and navigate to the files.  Then, run the following:

wodim -scanbus

This will return some information about every drive it finds.  In the output, look for your recordable drive in the list and make a note of the 3 comma-delimited digits that identify the bus and location of the drive.  Mine looks like this:

        0,0,0     0) 'HL-DT-ST' 'BD-RE  WH16NS40 ' '1.02' Removable CD-ROM
        0,1,0     1) *
        0,2,0     2) *
        0,3,0     3) *
        0,4,0     4) *
        0,5,0     5) *
        0,6,0     6) *
        0,7,0     7) HOST ADAPTOR

So, the 3 digits for me are "0,0,0".  For these next steps, replace the X,X,X with your values.

Insert a blank CD-R into your drive and burn the first part of the disc, the audio track, as follows:

wodim dev=X,X,X -multi -audio -tao audio.raw

Now, burn the data track:

wodim dev=X,X,X -xa -tao -multi data.raw

With those two items burned, you now be able to eject the CD, pop it in your Dreamcast, and it will run.

Running a Sample

With dcload-ip running on your Dreamcast, you should see a MAC address displayed.


We need to tell our Windows machine how to find that device by an IP address.  If you recall, earlier you selected an IP for your Dreamcast.  You will need that here.

Open an admin command prompt (not Bash, but standard command prompt) and run the arp command as follows:


Replace IP_ADDRESS with the one selected above, and MAC_ADDRESS with the one seen on screen, but use hyphens instead of colons.  Here's an example:

arp -s 00-d0-f1-02-3f-07

This command must be run after every reboot...it will not be saved by Windows.

You may need to exit and restart the Bash on Windows after running this command so it will know about the change.

Now, you can run the 2ndmix (or any other) sample:

cd ~/kos/examples/dreamcast/2ndmix
make run

If all goes to plan, this should build, deploy, and execute the 2ndmix demo on your Dreamcast!


Next Steps

Now that you have a configured and working toolchain and SDK, you can start building your own Dreamcast games.  Take a look at all of the examples in the kos directory to learn more about the API.  Additionally, here are a few links with more information:

My Info

  • View Brian Peek's profile on LinkedIn

Sponsored Ad

My Book

Sponsored Ad