Useful information and tutorials

This section is a collection of useful information and how-to. These may be interesting depending of your requirements and needs.

How to generate dcload-serial and dcload-ip disc images

dcload/dc-tool is a set of programs made to send and receive data from your Sega Dreamcast system. The classic use of this tool is to send programs to the Dreamcast in order to run and debug them.

Introduction

To use dcload/dc-tool, you must have a way to connect your Sega Dreamcast to your computer, it can be one of the following:

This program, dcload/dc-tool, originally developed by ADK/Napalm and now full part of the KallistiOS library is split in two components:

Depending on the method chosen you must use the right version of the program:

This applies on the client part as well, which is called dc-tool, but the DreamSDK package will make abstraction of that. Depending of the choice made in the DreamSDK Manager tool, the dc-tool wrapper specific to the DreamSDK package will call the right version, i.e. dc-tool-ser for the Coders Cable or dc-tool-ip for the LAN Adapter or Broadband Adapter version. In clear, you have to choose the right version in the DreamSDK Manager tool and just call the dc-tool command from the DreamSDK Shell. An example is shown here.

Please note, dc-tool is displayed as Dreamcast Tool in the DreamSDK Manager tool, this is just a cosmetic name for dc-tool.

Generate the dcload-serial or dcload-ip image

Now, you know everything about the dcload/dc-tool components, it's time to show you how to generate the dcload image, which is intended to be run on the Sega Dreamcast.

Please note, this will work only if you installed Make ISO File System and CDI4DC additional tools when installing DreamSDK!

From the DreamSDK Shell, enter the following:

cd /opt/toolchains/dc/dcload/dcload-<mode>/make-cd
mkdir cd_root
scramble ../target-src/1st_read/1st_read.bin cd_root/1ST_READ.BIN
makedisc dcload-<mode>-1.0.5.cdi cd_root IP.BIN DCLOAD_<mode>_105

Replace the <mode> keyword by serial or ip, depending of your connection mode.

Open now the make-cd directory in the Windows Explorer, enter the following in the DreamSDK Shell:

browse

Below an example of commands entered:

Making dcload

Now in the make-cd directory, you should have a dcload-serial-1.0.5.cdi or dcload-ip-1.0.5.cdi file. This file should be burn on a blank CD-R or put in a SD card if you are using a GDEMU, USB GD-ROM module or a DreamShell SD Loader:

dcload image

Please also note, the client part, dc-tool-ser and dc-tool-ip program binaries, are automatically generated when building KallistiOS through DreamSDK Manager, so you don't have any other action to do except configure it.

Basic usage of the dcload/dc-tool programs

Now that you have prepared the dcload you'll need and configured dc-tool in the DreamSDK Manager tool, it's time to explain how to use these set of tools:

  1. Insert the dcload CD in your Sega Dreamcast, or copy the dcload Padus DiscJuggler (CDI) image to your SD card if you are using a GDEMU, USB GD-ROM or DreamShell SD Loader.
  2. Plug the Sega Dreamcast:
  3. Power on your Sega Dreamcast. You should have the dcload screen displayed. It should be black if you are using the serial kind or blue if you are using the ip kind.
  4. You can now start to work by executing the dc-tool command through the DreamSDK Shell or use the Code::Blocks IDE.

How to debug a Sega Dreamcast program directly from the DreamSDK Shell

To use the KallistiOS GDB-over-dcload feature in order to debug your Sega Dreamcast program using the GNU Debugger (GDB):

  1. Put the gdb_init() call at the beginning of your main() entry point function in your program;
  2. Build your program with the -g GCC switch to include debugging info;
  3. Launch your program using dc-tool -g -x <prog.elf>;
  4. From another DreamSDK Shell session, launch sh-elf-gdb <prog.elf> and connect to the dc-tool using target remote :2159;
  5. Squash bugs!
dcload debug

Of course using GNU Debugger (GDB) from the command line isn't really user-friendly, so you have the possibility to use Code::Blocks instead. Click here to learn more.

Note: Sometime, the debugger will take a little delay to step in/step out, this is normal, just wait. This behaviour happens in the Code::Blocks IDE too.

How to release your Sega Dreamcast program

So after finishing the development of your Sega Dreamcast project (well done!) comes the following question: How to release your Sega Dreamcast program?

This is a good question and unfortunatelly, the KallistiOS library won't help you much, but as you are using DreamSDK, the answer is detailed here!

Before starting reading this section, you should be aware of ELF, unscrambled and scrambled files, this is explained in the FAQ.

The first thing to know is there is 3 ways to package a Sega Dreamcast program:

The package kind will depends of your needs. Below you'll find an explanation of each kind.

Plain files

Plain files is the simplest form of packaging. Basically, it just a Zip (or any other compressed format) file which contains the raw binary and required files of your program (such textures images, etc.).

This package kind will usually contains an ELF program (e.g. hello.elf), a raw unscrambled binary (e.g. hello.bin) and/or a scrambled binary (usually 1ST_READ.BIN). The end-user will deal with your files himself, i.e. using them as-is (through Sega Dreamcast emulator which have binary support, like nullDC or Demul) or making a selfboot disc image (see below).

Plain files are good for emulators or any other program that should be customized by the end-user, such adding ROM files, music (MP3, Ogg...) files, etc. But in that case, you should write a little README file to teach the end-user how to use your program... basically, the content of the next chapter!

Of course, your program should be compiled/built in Release mode (if using Code::Blocks) and, very important, without the gdb_init() call!

Selfboot disc image

Selfboot disc image (also known as Autoboot disc image) is the most common form of packaging and should be the one you are looking for. This form is basically a disc image, in Padus DiscJuggler (CDI) or Alcohol 120% (MDS/MDF), which may be burnt on a blank CD-R and startup like a genuine GD-ROM on any (almost) Sega Dreamcast hardware.

DreamSDK includes everything to make these kind of packages.

The steps are:

  1. Compile your program in Release mode, without debugging symbols and without the gdb_init() call.
  2. Converting the ELF file to a scrambled binary.
  3. Making a bootstrap file (usually called IP.BIN).
  4. Making the selfboot image.

It can be summarized like:

Selfboot Image Summary

The commands to enter in the DreamSDK Shell are:

cd <your_program_dir>
mkdir cd_root
make
make dist
elf2bin <prog.elf>
scramble <prog.bin> cd_root/1ST_READ.BIN
ipcreate -silent
makedisc <prog.cdi> cd_root IP.BIN [PROG_NAME]
browse

Please note, this will work only if you installed Make ISO File System and CDI4DC (or even MDS4DC) additional tools when installing DreamSDK!

Adapt the commands to your context.

To compile in Release mode, if you are using Code::Blocks, you just have to select the Release target and click Build. If you are using KOS Makefile, just enter make followed by make dist in the DreamSDK Shell. Please note, if make dist isn't defined in your Makefile, you can ignore the error as the elf2bin tool will do the necessary for you. Then, in the bin\Release folder (if using Code::Blocks) or in the project folder (if using KOS Makefile), enter elf2bin <prog.elf>. You should have a new file: <prog.bin>. This is the unscrambled binary. In the screenshot below, you will see the hello.bin file, which is the output of the elf2bin command.

elf2bin

It's time to scramble the binary. Enter the following (the mkdir command may not be necessary):

mkdir cd_root
scramble <prog.bin> cd_root/1ST_READ.BIN

This will generate the scrambled binary, usually called 1ST_READ.BIN.

Now generate the bootstrap loader: ipcreate -silent. The ipcreate tool has interesting options, like inserting a custom logo which will displayed in the Sega License Screen shown when booting up the Dreamcast.

Finalize by generating the selfboot image: makedisc <prog.cdi> cd_root IP.BIN [PROG_NAME]. [PROG_NAME] will be the CD label. It can be whatever and it's completely optional: if you don't specify something, it will be set to the Game Title field value from the bootstrap file (IP.BIN). If you want to generate an Alcohol 120% image (MDS/MDF) rather than a Padus DiscJuggler image (CDI), enter <prog.mds> instead of <prog.cdi>.

Your selfboot image is now ready! Below you will find an example of all commands entered:

Selfboot commands

Now, you just have to enter browse to open the current directory in the Windows Explorer:

Selfboot final commands

Your image is now ready and can be distributed!

Selfboot final file

Selfboot Inducer (SBI) packages

The third form available to distribute Sega Dreamcast programs is called Selfboot Inducer (SBI) packages. It's a special format made for putting several programs on the same CD. A menu is shown when this kind of disc is booted from the Sega Dreamcast, this menu is called DreamInducer.

To generate SBI packages, you will use the SBI Builder tool. The end-user will need to use Selfboot Inducer to use your packages in order to generate the disc image he wants.

These tools aren't part of the DreamSDK package, but you can find them here.