Dreamcast KOS Project Template

This repository provides a template for developing Dreamcast homebrew applications using the KallistiOS (KOS) framework. It includes a pre-configured development environment, build system, and example code to help you get started quickly.

Features

• Pre-configured Toolchain: Uses a CMake-based build system with a Dreamcast-specific toolchain.
• Devcontainer Support: Includes a development container configuration for a consistent development environment.
• GitHub Actions Integration: Automates builds using a pre-configured GitHub Actions workflow.
• Example Code: A simple 3D cube rendering example using raylib and KOS.
• ROMDISK and CDI Generation: Automatically generates ROMDISK and CDI images for Dreamcast testing.
• No In-Source Builds: Enforces clean build practices.

Prerequisites

Before using this template, if you are not planning to use the configured devcontainer, ensure you have the following installed:

• KallistiOS (KOS) installed and configured.
• Different tools for building and testing:
  • mkdcdisc (for creating CDI images from elf file).
• CMake (minimum version 3.11.0).

Else, you can use the provided devcontainer configuration to set up a consistent development environment.

• Visual Studio Code (with the Dev Containers extension).
• Docker (for the development container).

Getting Started

1. Clone the Repository

git clone https://github.com/your-username/dreamcast-template.git
cd dreamcast-template

2. Configure the Development Environment

Option 1: Using Devcontainer (Recommended)

1. Open the project in Visual Studio Code.
2. Install the Dev Containers extension.
3. Reopen the project in the container when prompted.

Option 2: Manual Setup

If you prefer not to use the devcontainer, ensure the following tools and dependencies are installed and configured on your system:

1. KallistiOS (KOS)

   • Install and configure KallistiOS (KOS), the Dreamcast homebrew development framewor;, along with the toolchain.

2. Kos-Ports

   • Install and configure Kos-Ports, a collection of libraries and tools for KOS development.

3. CMake

   • Install CMake (minimum version 3.11.0) for managing the build process.

4. Mkdcdisc

   • Install mkdcdisc, a tool for creating CDI images from ELF files. This tool is typically included with the KallistiOS installation.

5. Other tools

   • You may refer to this Dockerfile for other tools provided in the devcontainer.
     • Ensure the MKDCDISC tool is available in your system.

6. Source the KOS environment setup script:

source /opt/toolchains/dc/kos/environ.sh

3. Build the Project

Project Structure

dc-template/
├── .devcontainer/         # Devcontainer configuration
├── .github/workflows/     # GitHub Actions workflow
├── .vscode/               # VS Code settings and CMake kits
├── build/                 # Build output directory (ignored by Git)
├── cmake/                 # CMake modules
├── src/                   # Source code
│   └── my_module/         # Example module
│       ├── main.cpp       # Example application
│       └── romdisk/       # ROMDISK assets
├── toolchains/            # Dreamcast toolchain file
├── out/                   # Output directory for CDI images
├── LICENSE                # License file
├── Makefile               # Makefile for additional targets (lint, run dc-tool-ip)
└── README.md              # Project documentation

Example Code

The included example (src/my_module/main.cpp) demonstrates:

• Initializing a 3D rendering window with raylib.
• Handling Dreamcast controller input.
• Rendering a rotating 3D cube.

GitHub Actions

This template includes a GitHub Actions workflow (.github/workflows/github-actions.yml) to automate builds. The workflow:

1. Runs in a containerized Dreamcast development environment.
2. Builds the project using the provided toolchain.
3. Outputs the build artifacts.

License

This template is licensed under the MIT License.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to improve this template.

Resources

• KallistiOS Documentation
• Dreamcast Development Wiki
• raylib Documentation
• GitHub Actions Documentation
• CMake Documentation

Debugging Dreamcast Network Connection (DHCP Setup)

To allow your Dreamcast to get an IP address automatically over Ethernet (via BBA), you’ll need to set up a lightweight DHCP server using dnsmasq.

1. Install dnsmasq

sudo apt install dnsmasq

---

2. Configure dnsmasq

Create a configuration file specifically for the Dreamcast setup:

sudo nano /etc/dnsmasq.d/dreamcast.conf

Add the following content:

interface=<your-dreamcast-interface>
bind-interfaces

dhcp-range=192.168.0.50,192.168.0.150,12h
dhcp-option=3,192.168.0.1
dhcp-option=6,8.8.8.8,1.1.1.1

🔁 Replace <your-dreamcast-interface> with the name of your Ethernet-to-USB adapter or relevant NIC (e.g., enxa0cec85e02d8).
You can find it using:

ip addr

Look for the interface that is connected to the Dreamcast (usually shows as DOWN when unplugged, UP when plugged in).

---

3. Restart dnsmasq

sudo systemctl restart dnsmasq

---

4. Find the Dreamcast IP

While your Dreamcast is booted into dcload-ip (or a network-enabled app/game):

sudo journalctl -u dnsmasq -f

Look for a block like:

DHCPDISCOVER(enx...) ...
DHCPOFFER(enx...) 192.168.0.85 ...
DHCPREQUEST ...
DHCPACK ...

The IP address offered (e.g., 192.168.0.85) is the one you’ll use with tools like dc-tool-ip.

Connection Troubleshooting

Check the journal for dnsmasq

It provides useful information about the DHCP process and any potential issues.

sudo journalctl -u dnsmasq -f

Issue : dnsmasq.service failed to start

If you see an error like this:

Apr 22 22:55:33 daoliangshu-ux430uq dnsmasq[36544]: unknown interface <you-interface>
Apr 22 22:55:33 daoliangshu-ux430uq dnsmasq[36544]: FAILED to start up

It means that the interface is not available when dnsmasq starts.

The interface is not up

It can means that the is not up. Checks with:

ip addr show <your-dreamcast-interface>

Example output:

$ ip addr show enxa0cec85e02d8
17: enxa0cec85e02d8: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether a0:ce:c8:5e:02:d8 brd ff:ff:ff:ff:ff:ff

Here we see the interface exists, but is down. In that case, you can bring it up with:

sudo ip link set enxa0cec85e02d8 up

Then restart dnsmasq:

sudo systemctl restart dnsmasq

The interface does not exist

Check if the interface name is correct in /etc/dnsmasq.d/dreamcast.conf (or whatever name you used for the configuration file). Check if your device is connected to the Dreamcast and your laptop.

Issue : dcload-ip is not receiving an IP address

If your Dreamcast isn’t being assigned an IP address, you can check what's going wrong by inspecting the system journal:

sudo journalctl -u dnsmasq -f

If you see a message like this:

HCP packet received on <your-dreamcast-interface> which has no address

It means that your Dreamcast is sending a DHCP request, but your network adapter (usually the USB-Ethernet interface) doesn’t have an IP address assigned to it — so dnsmasq can’t respond.

To fix this, assign a static IP address to the adapter:

sudo ip addr add 192.168.0.1/24 dev <your-dreamcast-interface>
sudo ip link set <your-dreamcast-interface> up

Then restart dnsmasq

sudo systemctl restart dnsmasq

Finally, verify that the IP address has been correctly assigned:

ip addr show <your-dreamcast-interface>

Summary of useful commands for debugging the connection to dc-tool-ip

1. Read the logs

sudo journalctl -u dnsmasq -f

2. Try to bring up the interface, assign an IP address

sudo ip link set enxa0cec85e02d8 up
sudo ip addr flush dev enxa0cec85e02d8
sudo ip addr add 192.168.0.1/24 dev enxa0cec85e02d8 # replace with your interface

3. Restart dnsmasq:

sudo systemctl restart dnsmasq