https://github.com/sizious/dcload-ip
A Dreamcast ethernet loader originally by ADK/Napalm — This project is part of KallistiOS. [⚠️ Unofficial, Most Advanced, Experimental Version ⚠️]
https://github.com/sizious/dcload-ip
developer-tools development-tools dreamcast homebrew-launcher sega sega-dreamcast
Last synced: 17 days ago
JSON representation
A Dreamcast ethernet loader originally by ADK/Napalm — This project is part of KallistiOS. [⚠️ Unofficial, Most Advanced, Experimental Version ⚠️]
- Host: GitHub
- URL: https://github.com/sizious/dcload-ip
- Owner: sizious
- License: gpl-2.0
- Created: 2018-10-11T10:25:49.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-03-21T06:02:48.000Z (about 1 month ago)
- Last Synced: 2025-03-21T07:20:21.304Z (about 1 month ago)
- Topics: developer-tools, development-tools, dreamcast, homebrew-launcher, sega, sega-dreamcast
- Language: C
- Homepage: https://github.com/KallistiOS/dcload-ip
- Size: 351 KB
- Stars: 45
- Watchers: 4
- Forks: 16
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES
- License: COPYING
Awesome Lists containing this project
- awesome-dreamcast - Dcload-ip - Launch game through your BBA. Classic program by Sizious. (Testing and Debugging)
README
# dcload-ip 2.0.1
A Dreamcast ethernet loader originally by [Andrew Kieschnick](http://napalm-x.thegypsy.com/andrewk/dc/).
Updated and overhauled by Moopthehedgehog
## Features
* Load `elf`, `srec`, and `bin`
* PC I/O (read, write, etc to PC - compatible with original dcload)
* Exception handler
* Extremely fast
* Now works on 100mbit
* Supports both the **Broadband Adapter** (HIT-0400) and **LAN Adapter** (HIT-0300)
in a single binary
- DHCP support (use an IP address of 0.0.0.0 in `Makefile.cfg` to enable it)
- NTSC 480i, PAL 576i, and VGA display output modes supported
- Dumping exceptions over the network if the dcload console is enabled
## Building
1. Edit `Makefile.cfg` for your system and network, and then run `make`.
NOTE: GCC 4.7.x users using the KOS 2.1.0 build environment must ensure
``USING_KOS_GCC`` is enabled in `Makefile.cfg`. Disabling that flag uses compile
options meant for a portable copy of GCC 9.2/Binutils 2.33.1 compiled with an
``sh4-elf-`` prefix, which won't work with the KOS 2.1.0 compiler.
## Installation
1. PC - run `make install` (installs dc-tool)
2. DC
a. `cd make-cd`, edit `Makefile`, insert blank cd-r, run `make`. If
`1st_read.bin` hasn't been built yet, this `Makefile` will build it
or
b. take `target-src/1st_read/1st_read.bin` and stuff it on a cd yourself
(please use the `IP.BIN` from the `make-cd` directory if you are going
to distribute either cds or cd images).
## On-screen display
* If you see the message `NO ETHERNET ADAPTER DETECTED!`, something has
gone wrong. The background of the screen will be red.
* The correct display is something like:
`dcload-ip 2.0.1` <- name/version
`Broadband Adapter (HIT-0400)` <- adapter driver in use
`00:d0:f1:02:ab:dd` <- dc hardware address
`192.168.1.92` <- dc ip address
`idle...` <- status
The background of the screen will be blue (Broadband Adapter) or green (LAN Adapter).
* If the status line reports `link change...` and does not change back to
`idle...` within a short period of time, you may have a cable problem.
dcload-ip will not work while `link change...` is displayed, or before it is
displayed the first time. The `link change...` message normally is seen when
you start dcload-ip, when you execute `dc-tool -r`, and when you disconnect
the ethernet cable.
* If an exception is caught while a loaded program is running, the screen
will turn lighter blue and display the exception info for a time set by
`EXCEPTION_SECONDS` in Makefile.cfg (default is 15 seconds). dcload-ip should
be active again after that point. See the Exception Dumping section of this
README for what happens if an exception occurs while the dc-tool console is used.
## Testing
1. `cd example-src`
2. `dc-tool -x console-test` (tests some PC I/O)
3. `dc-tool -x exception-test` (generates an exception)
4. `dc-tool -x gethostinfo` (displays the Dreamcast's ip, and the ip and port of
the dc-tool host)
## KOS GDB-over-dcload
To run a GNU debugger session over the dcload connection:
1. Build/obtain an sh-elf targetted GNU debugger
2. Put a `gdb_init()` call somewhere in the startup area of your
KOS-based program
3. Build your program with the `-g` GCC switch to include debugging info
4. Launch your program using `dc-tool -g -x `
5. Launch sh-elf-gdb and connect to the dc-tool using `target remote :2159`
6. Squash bugs
## Maple Passthrough
You can send packets to various maple devices attached to the Dreamcast by using
the MAPL command. Simply send a command packet to the Dreamcast that is formatted
as follows:
```
typedef struct __attribute__ ((packed)) {
unsigned char id[4]; // MAPL
unsigned int address; // Ignored, set to 0
unsigned int size; // The length of Maple packet data (the data[] member)
unsigned char data[];
} command_t;
```
Maple command data format:
- Maple Command (1 byte)
- Maple Port # (1 byte)
- Maple Slot # (1 byte)
- Maple data in 4-byte increments (1 byte)
- Any data to be sent with the command (multiple of 4 bytes)
You will get a similarly formatted response in return.
## Performance Counter Control
Newly added is the ability to control Dreamcast/SH7091 performance counters over
the network. These were a previously hidden aspect of the Dreamcast's CPU, and
this program uses one of them to keep track of DHCP lease time across loaded
programs. There are two of them, and they are both 48-bit. See perfctr.h/.c for
details (they are from https://github.com/Moopthehedgehog/DreamHAL).
Similarly to the Maple packets, the format of a performance counter control packet
is as follows:
```
typedef struct __attribute__ ((packed)) {
unsigned char id[4]; // PMCR
unsigned int address; // Ignored, set to 0
unsigned int size; // Length of data[]. This field isn't actually checked, though...
unsigned char data[];
} command_t;
```
For anyone making a program to take advantage of this functionality, the packet
payload data essentially just needs to conform to this struct, and "id" should
be "PMCR" (without null-termination).
Regarding the data field, it should be formatted according to the following information:
The 6 performance counter control functions are:
```
// (I) Clear counter and enable
void PMCR_Init(unsigned char which, unsigned char mode, unsigned char count_type);
// (E) Enable one or both of these "undocumented" performance counters
void PMCR_Enable(unsigned char which, unsigned char mode, unsigned char count_type, unsigned char reset_counter);
// (B) Disable, clear, and re-enable with new mode (or same mode)
void PMCR_Restart(unsigned char which, unsigned char mode, unsigned char count_type);
// (R) Read a counter
unsigned long long int PMCR_Read(unsigned char which);
// (G) Get a counter's current configuration
unsigned short PMCR_Get_Config(unsigned char which);
// (S) Stop counter(s) (without clearing)
void PMCR_Stop(unsigned char which);
// (D) Disable counter(s) (without clearing)
void PMCR_Disable(unsigned char which);
```
The command is the first letter of the function name (capitalized), followed by
each of the function's parameters. Note that restart's command letter is 'B'--read
is 'R', so restart is 'B' (think reBoot). The command letters are included in
parentheses for each function in the above comment block.
- Sending command data of 'D' 0x1 (2 bytes) disables ('D') perf counter 1 (0x1)
- Sending command data 'E' 0x3 0x23 0x0 0x1 (5 bytes) enables ('E') both perf
counters (0x3) to elapsed time mode (0x23) where count is 1 cpu cycle = 1 count
(0x0) and continue the counter from its current value (0x1)
- Sending command data 'B' 0x2 0x23 0x1 (4 bytes) restarts ('B') perf counter 2
(0x2) to elapsed time mode (0x23) and count is CPU/bus ratio method (0x1)
...
etc.
Notes:
- Remember to disable before leaving dcload-ip to execute a program if dcload's
counter is needed by that program.
- See perfctr.h for how to calculate time using the CPU/bus ratio method, in
addition to the available counter modes (and for loads of other information)
- PMCR_Init() and PMCR_Enable() will do nothing if the perf counter is already running!
## Exception Dumping
Another new feature is the ability to send a full register dump to a host PC
running dc-tool-ip with the console enabled (i.e. not invoked with the `-n`
command line option).
In the event of an exception, dcload will print a full register dump on the
screen and to the dc-tool console. It will also make a file called
`dcload_exception_dump.bin` in the directory that the terminal is currently in.
The format of the dump binary is as follows:
```
// Exception struct
struct _exception_struct_t {
unsigned char id[4]; // EXPT
unsigned int expt_code; // Exception code
unsigned int pc;
unsigned int pr;
unsigned int sr;
unsigned int gbr;
unsigned int vbr;
unsigned int dbr;
unsigned int mach;
unsigned int macl;
unsigned int r0b0;
unsigned int r1b0;
unsigned int r2b0;
unsigned int r3b0;
unsigned int r4b0;
unsigned int r5b0;
unsigned int r6b0;
unsigned int r7b0;
unsigned int r0b1;
unsigned int r1b1;
unsigned int r2b1;
unsigned int r3b1;
unsigned int r4b1;
unsigned int r5b1;
unsigned int r6b1;
unsigned int r7b1;
unsigned int r8;
unsigned int r9;
unsigned int r10;
unsigned int r11;
unsigned int r12;
unsigned int r13;
unsigned int r14;
unsigned int r15;
unsigned int fpscr;
unsigned int fr0;
unsigned int fr1;
unsigned int fr2;
unsigned int fr3;
unsigned int fr4;
unsigned int fr5;
unsigned int fr6;
unsigned int fr7;
unsigned int fr8;
unsigned int fr9;
unsigned int fr10;
unsigned int fr11;
unsigned int fr12;
unsigned int fr13;
unsigned int fr14;
unsigned int fr15;
unsigned int fpul;
unsigned int xf0;
unsigned int xf1;
unsigned int xf2;
unsigned int xf3;
unsigned int xf4;
unsigned int xf5;
unsigned int xf6;
unsigned int xf7;
unsigned int xf8;
unsigned int xf9;
unsigned int xf10;
unsigned int xf11;
unsigned int xf12;
unsigned int xf13;
unsigned int xf14;
unsigned int xf15;
} __attribute__ ((__packed__));
```
## Notes
* You can use `arp` instead of setting the Dreamcast's IP in `Makefile.cfg`.
On Windows, you may use the `netsh` command which is more reliable (e.g. `netsh
interface ip add neighbors "Ethernet" 192.168.10.1 AA-BB-CC-DD-EE-FF)`. In that
case, don't forget to specify an IP address in the Ethernet card of your computer.
Please set the Dreamcast's IP in `Makefile.cfg` to be in the range 169.254.xxx.xxx
when using this method, as 0.0.0.0 is used by the DHCP protocol for network
discovery purposes (actually the entire 0.x.x.x range is).
* Tested systems: Debian GNU/Linux 2.2-3.0, Cygwin, MinGW,
[DreamSDK](https://www.dreamsdk.org), Windows Subsystem for Linux v2 (Debian)
* Many, many bugs have been squashed and much of the code overhauled
* Patches and improvements are welcome; please raise an issue here in the "Issues"
section for that
## Credits
* [SiZiOUS](https://www.github.com/SiZiOUS) for maintaining this program
* rtl8139 code based on code by Dan Potter
* LAN Adapter driver code, originally derived from early KOS, majorly overhauled by Moopthehedgehog
* DHCP support, exception dumping, perf counters, performance improvements by Moopthehedgehog
* DHCP retry functionality by darcagn
* There are some various files from `newlib-1.8.2` here
* `video.s`, `maple.c`, and `maple.h` were written by Marcus Comstedt
* initial win32 porting and implementation of -t by Florian 'Proff' Schulze
* win32 bugfix by The Gypsy
* fixes for cygwin by Florian 'Proff' Schulze
* rx config bug pointed out by Slant
* horridly buggy nature of 1.0.1 + 1.0.2 pointed out by Dan Potter
* Fixes for `libbfd` segfaults by Atani
* Inspiration for `MAPL` packet by Tim Hentenaar