Menu

Tree [cd5e40] master /
 History

HTTPS access


File Date Author Commit
 example-src 2023-06-13 Andress Barajas Andress Barajas [91830f] Fix style/spacing and some warnings (#15)
 host-src 2023-11-16 Falco Girgis Falco Girgis [dce9e9] Fixed build issue + preexisting warning
 make-cd 2023-06-13 Andress Barajas Andress Barajas [91830f] Fix style/spacing and some warnings (#15)
 minilzo-2.10 2023-06-18 Tim Riemann Tim Riemann [4d2855] Use MiniLZO v2.10 (#12)
 target-inc 2023-06-13 Andress Barajas Andress Barajas [91830f] Fix style/spacing and some warnings (#15)
 target-src 2023-06-18 Tim Riemann Tim Riemann [4d2855] Use MiniLZO v2.10 (#12)
 .gitignore 2023-02-25 Andress Barajas Andress Barajas [61cb53] Fixes to linker script and macOS building.
 CHANGES 2023-02-25 Andress Barajas Andress Barajas [348ea7] Update version/README.
 COPYING 2006-05-25 Dan Potter Dan Potter [344cf0] Import dcload, ps2, and navi trees from CVS.
 Makefile 2023-02-21 Andress Barajas Andress Barajas [c7df5d] Improving Makefile system to support FreeBSD, C...
 Makefile.cfg 2023-08-17 Tchan0 Tchan0 [910f91] Add baudrate 230400 and its speedhack. (#16)
 Makefile.hostdetect 2023-02-21 Andress Barajas Andress Barajas [c7df5d] Improving Makefile system to support FreeBSD, C...
 README.md 2023-09-04 Tchan0 Tchan0 [da35b5] Add termios2 for linux, explain SH-4 custom bau...

Read Me

dcload-serial 1.0.6

dcload is a Sega Dreamcast (DC) serial loader written originally by
Andrew Kieschnick, a.k.a.
ADK/Napalm. It is currently maintained as a part of
KallistiOS (KOS).

dcload 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. To be used, you must have a way to
connect your Dreamcast console to your computer, it can be one of the following:

  • A Coders Cable (a serial cable, the historical way to do that). It can be
    a cable with the classical RS-232/DE-9 connector or with a
    USB-Serial module.
  • A Broadband Adapter, ref. HIT-400, often shortened as BBA, a
    10/100Mbits Ethernet network card.
  • A LAN Adapter, ref. HIT-300, a 10Mbits Ethernet network card.

If you have a Coders Cable, you have to use dcload-serial. For the Broadband
Adapter or LAN Adapter, you have to use dcload-ip.

dcload is split in two components:

  • dcload, the server part, meant to be run on the Dreamcast;
  • dc-tool, the client part, executed from your computer.

Features

  • Load elf, srec and bin (binary transfers are compressed).
  • PC I/O (read, write from/to the PC).
  • Exception handler.
  • Debug Dreamcast programs remotely by using the GDB-over-dcload feature.

Building

  1. You should have a working
    KallistiOS (KOS) environment and
    of course the sh-elf toolchain installed (if you have installed KOS, you
    already have everything ready).
  2. Edit the Makefile.cfg file for your system and then run make.

Installation

dc-tool (client part)

Run make install: this will install dc-tool-ser on your computer (default in
/opt/toolchains/dc/bin).

dcload (server part)

For the Dreamcast part, you have two options.

  • Directly burn to a disc by using cdrecord:
  • Navigate to make-cd.
  • Edit the Makefile.
  • Insert blank CD-R.
  • Run make. If the 1ST_READ.BIN file hasn't been built yet, this
    Makefile will build it.

  • Create a Padus DiscJuggler (CDI) image to burn later (requires
    the mkisofs and cdi4dc tools):

  • make -C ./host-src/misc (build the miniLZO binary)
  • make -C ./target-src (build the 1ST_READ.BIN)
  • mkisofs -C 0,11702 -V dcload-serial -G ./make-cd/IP.BIN -joliet -rock -l -o temp.iso ./target-src/1st_read/1st_read.bin
  • cdi4dc temp.iso dcload-serial.cdi

Testing

Everything is located in the example-src directory.

  • dc-tool-ser -x console-test: tests some PC I/O
  • dc-tool-ser -x exception-test: generates an exception

KOS GDB-over-dcload

You have the possibility to use dcload to debug remotely Dreamcast binaries.
To run a GNU debugger session over the dcload connection:

  1. Build/obtain an sh-elf targetted GNU debugger (can be made with dc-chain
    utility from KallistiOS).
  2. Put a gdb_init() call somewhere in the startup area of your
    KOS-based program (e.g. it's a good idea to put this call in your main()),
    then add the #include <arch/gdb.h> statement in that file.
  3. Build your program with the -g GCC switch to include debugging info.
  4. Launch your program using dc-tool-ser -g -x <sh-executable>.
  5. Launch sh-elf-gdb and connect to the dc-tool using target remote :2159.
  6. Squash bugs.

Notes

  • dcload, both IP and Serial, are maintained by the KOS
    team. Please join the KallistiOS list
    for help with these tools.
  • Tested systems: Debian GNU/Linux 2.2; Gentoo/Linux 2.6.7; Cygwin;
    Mac OSX 10.3.5 (Panther); macOS 10.15.2 (Catalina), MinGW/MSYS,
    DreamSDK, MinGW-w64/MSYS2.
  • To attain the highest speeds with dcload-serial, you need to select a USB-Serial module that matches the baudrates that the Dreamcast's SH-4 cpu can generate. Above 115200, the SH-4 cpu generates the following baudrates: 223214, 260416, 312500, 390625, 520833, 781250, 1562500.
  • Silicon Labs CP2102N-based chips have a good match with the SH-4, so you're pretty much guaranteed to attain the highest speed, 1562500.
  • FTDI FT232*-based chips do no match the SH-4 baudrates closely enough, so 781250 will work, but 1.56M will depend on your specific chip (ie, chip luck)
  • Examples of how to launch a program:
  • Linux: dc-tool-ser -t /dev/usb/tts/0 -b 1500000 -x <sh-executable>
  • Windows: dc-tool-ser -t COM4 -b 500000 -x <sh-executable>
  • macOS: dc-tool-ser -t /dev/cu.usbserial-A50285BI -b 1500000 -x <sh-executable>
  • As of 1.0.4, little-endian byte order is enforced in the host so dc-tool
    now runs on big-endian systems like a Mac.
  • As of 1.0.3, serial speed is changed at runtime rather than compile time.
  • 115200 works fine in most cases but 57600 baud is the standard baud.
    There is an -e option that will enable an alternate 115200 which may work
    better in some rare cases. Use this only if the regular 115200 is unstable.
  • 234000 will probably only work with the -e option enabled.
  • Patches and improvements are welcome.

Modern macOS Notes

  • This was tested on Catalina 10.15.2 only, however it should work on pretty
    much any version of macOS.
  • Of course some sort of USB serial adapter must be used. The standard
    FT232RL USB-Serial boards from China that are sold pretty much everywhere
    work great and are super cheap.
  • Modern macOS supports the same speeds as the other platforms, currently
    up to 1.56M baud (-b 1500000). This was tested using Catalina and an
    FT232RL.
  • Compilation on macOS requires libelf, which can be easily installed using
    the Homebrew package manager: brew install libelf
  • The static compilation option cannot be used on macOS due to the way GCC
    works on macOS. However, when building the standard dynamically linked build,
    only libSystem is linked (confirmed with otool -L) which is available on
    all macOS systems, so the binary should still be just as portable.

Credits

  • miniLZO was written by
    Markus Oberhumer.
  • There are some various files from newlib-1.8.2 here and video.s was
    written by Marcus Comstedt.
  • Win32 porting and implementation of -t by Florian 'Proff' Schulze.
  • Bugfix and implementation of -b by The Gypsy.
  • Fixes for Cygwin by Florian 'Proff' Schulze.
  • Minor initialization fix in dcload for gcc-3.4.x and Serial protocol endian
    fixes by Paul Boese a.k.a. Axlen.
  • Fixes for Mac OSX (and testing) by Dan Potter.
  • Fixes for libbfd segfaults by Atani.
  • Tons of improvements and fixes by SiZiOUS.
  • Modern macOS testing by Ben Baron a.k.a. einsteinx2.
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.