Project status / accepting contributions?

[netrunner01]

Hi! I've been doing some work to get USBDDOS running cleanly on a few targets it doesn't currently support, and I have a few patches I'd like to upstream if the project is still accepting contributions.
Noticed the last commit was February 2024, so figured I'd check before opening any PRs.
Three categories ready to go:

1. Build cleanups (zero behavioral change) — fix 8 mixed-case #include paths across 7 files so the tree builds on case-sensitive filesystems (Linux DJGPP cross / Open Watcom v2 on Linux).
2. Optional debug instrumentation — flip the COM1 _LOG #if 0 to #if 1 in dbgutil.c:142 so debug builds emit traces over serial for headless testing. One-line change.
3. OHCI compatibility quirks — two narrow fixes mirroring behavior Linux already has:

OHCI UnrecoverableError handler implementing the OHCI 1.0a §5.3.1.1 recovery sequence (currently a //TODO no-op in OHCI_ISR)
ALi M5237 HcFmInterval-access skip, matching Linux's no_fminterval flag in drivers/usb/host/pci-quirks.c

All three are tested in QEMU regression (5/5: OHCI/UHCI/EHCI init, OHCI HID, OHCI MSC). Real-hardware verification for the OHCI quirks is pending — I'd note that clearly in any PR descriptions.
If you're still accepting contributions, I'd start with (1) as the lowest-risk and move through. If you consider USBDDOS complete or have moved on, no worries — I'll maintain a fork and just wanted to ask before submitting anything.
Thanks for the driver — it's exactly what I needed for a 386/486-era rescue floppy project I'm working on.

[crazii]

Thank you for helping on USBDDOS.
Yes, any help/contribution is gratefully accepted, and USBDDOS is far from complete.
You can create PRs as you consider fit, and like your way it's better to isolates different functions/fixes to different commits/PRs.

[crazii]

And I forgot to mention, just be free to add your changelog & contributor info in the README.md.

[netrunner01]

Sorry. I thought that you wouldn't respond. I created my own fork here: https://github.com/netrunner01/USBDDOS . I am a GitHub noob. Please let me know how you want to proceed. Thanks.

[crazii]

Sorry I wasn't online for a long time.
I am not quite familiar with git/github either, I don't use it in my work. AFAIK you can cherry pick you changes excluding the REAME.md to a new branch, and edit the README on your new branch. There is a "#xx commits ahead of" link on your project branch, click it and there will be PR links.

I just found I can create PR from your repo too, at least the link works for me, but I never used that.
There is another simple way that you just create your full PR and I will edit the README.md.

[stanwebber]

i am watching with rapt attention.

[netrunner01]

@stanwebber While we sort this out, you can grab a copy of my updated driver and see if that helps with the hub issue. I've lost track, but I'm pretty sure that was one of the patches. I would really appreciate the testing on real silicon. https://github.com/netrunner01/USBDDOS/releases/download/v1.0.0-alpha.1/usbddos-v1.0.0-alpha.1-binaries.zip

[crazii]

I have merge the PRs from both of you.

Thanks very much!

@netrunner01 I guess there is an left PR from you. Look forward to it.

[netrunner01]

Sorry about the mess. There was a cherrypick conflict. Should be cleaned up now. You should see one new PR now.

[crazii]

They're 6 PRs, gap 1 2 3 4 8 and hcd remove device, right?
It's 4:00 AM here and I've turned off my PC and I'm typing on the phone, I will merge those tomorrow, thank you!

[netrunner01]

yes, that's correct. thanks!

[stanwebber]

@netrunner01 so far i'm not having any luck with your v1.0.0 alpha build. on a kt133a system with a 4-port usb 2.0 hub plughed into an nec µPD720101 pci card, usbddos /hid is locking up while detecting (or immediately after) the devices on the hub. i have a usb microphone, bluetooth dongle, trackball (detected as keyboard + mouse) and a keyboard/trackpad combo plugged into the hub. it detects both trackball devices and both keyboard/trackpad combo devices before freezing. there are no issues with the functioning of any of the hub devices under win98se or linux q4os.

i also compiled a usbddos debug build from commit afb2b84 of https://github.com/netrunner01/USBDDOS.git, but i'm not sure where to start.

[netrunner01]

Sorry to hear that, but thank you for testing. Please try booting up with only the hub itself connected. If that works, plug in one thing at a time, starting with keyboard, until it freezes. thx!

[netrunner01]

instructions · MD

Copy

How to collect a debug log with USBDDOS.EXE (alpha)

Thanks for testing! This document walks you through capturing diagnostic output from the debug build of USBDDOS, which writes per-step log messages to COM1. Without this log, debugging any failure is guesswork; with it, the maintainer can usually pinpoint which OHCI/UHCI/EHCI register access failed.

The whole process is: connect a serial cable, run a terminal program on a second machine, load USBDDOS.EXE on the DOS machine, capture everything.

---

What you need

• The DOS machine with the USB controller you want tested.
• A second "capture" machine running anything modern (Windows, Linux, Mac, or another DOS box).
• A null-modem serial cable connecting the DOS machine's COM1 (DB-9 male typically) to a serial port on the capture machine. If the capture machine has no native serial port, a USB-to-serial adapter works fine — FTDI, Prolific (PL2303), or CH340 chipsets are all confirmed to work.
• A terminal program on the capture machine. Common choices:
  • Windows: PuTTY (free, https://putty.org), TeraTerm
  • Linux: minicom, screen, moserial
  • macOS: CoolTerm, screen
• USBDDOS.EXE from the v1.0.0-alpha.1 release — the 94,380-byte debug Watcom build (NOT USBDDOSP.EXE, which has no log output). Download: https://github.com/Netrunner01/USBDDOS/releases/tag/v1.0.0-alpha.1

---

Serial settings (memorize these — both ends must match)

Setting | Value -- | -- Baud rate | 9600 Data bits | 8 Parity | None Stop bits | 1 Flow control | None (NOT XON/XOFF, NOT RTS/CTS)

---

Thanks again for testing. Real-hardware reports are the single most useful thing right now — works-fine reports are just as valuable as bug reports, since both inform the alpha-to-beta promotion.

instructions · MDCopyHow to collect a debug log with USBDDOS.EXE (alpha) Thanks for testing! This document walks you through capturing diagnostic output from the debug build of USBDDOS, which writes per-step log messages to COM1. Without this log, debugging any failure is guesswork; with it, the maintainer can usually pinpoint which OHCI/UHCI/EHCI register access failed. The whole process is: connect a serial cable, run a terminal program on a second machine, load USBDDOS.EXE on the DOS machine, capture everything.

What you need

The DOS machine with the USB controller you want tested.
A second "capture" machine running anything modern (Windows,
Linux, Mac, or another DOS box).
A null-modem serial cable connecting the DOS machine's COM1
(DB-9 male typically) to a serial port on the capture machine.
If the capture machine has no native serial port, a USB-to-serial
adapter works fine — FTDI, Prolific (PL2303), or CH340 chipsets
are all confirmed to work.
A terminal program on the capture machine. Common choices:

Windows: PuTTY (free, https://putty.org/), TeraTerm
Linux: minicom, screen, moserial
macOS: CoolTerm, screen

USBDDOS.EXE from the v1.0.0-alpha.1 release —
the 94,380-byte debug Watcom build (NOT USBDDOSP.EXE, which has
no log output). Download:
https://github.com/Netrunner01/USBDDOS/releases/tag/v1.0.0-alpha.1

Serial settings (memorize these — both ends must match)
SettingValueBaud rate9600Data bits8ParityNoneStop bits1Flow controlNone (NOT XON/XOFF, NOT RTS/CTS)
The shorthand is "9600 8-N-1, no flow control."

Setup
On the capture machine

Connect the cable and identify which COM/serial device it shows up
as on the capture machine (Windows: Device Manager → Ports; Linux:
dmesg | tail after plugging in, look for /dev/ttyUSB0 or
/dev/ttyS0).
Start your terminal program and open the serial port at 9600 8-N-1,
flow control off.
Enable session logging:

PuTTY: in the setup dialog → Session → Logging → "All session
output" → choose a log file name → click Open
minicom: launch with -C logfile.txt flag, or press Ctrl-A then
L after connecting to enable capture
screen: launch with screen -L /dev/ttyUSB0 9600 — creates
screenlog.0 in the current directory
CoolTerm: Connection → Capture to TextFile → Start

On the DOS machine

Boot to a DOS prompt. Note your exact DOS variant (FreeDOS version,
MS-DOS 6.22, PC-DOS, DR-DOS, etc.) — this matters for the bug report.
Set COM1 to the correct speed:

MODE COM1: 9600,N,8,1
You should see something like COM1: 9600, N, 8, 1, -- confirming.
3. Quick connectivity test before loading the driver:
ECHO Hello from the DOS machine > COM1
You should see Hello from the DOS machine appear in the terminal
on the capture machine. If you don't, the serial connection isn't
working — fix it before continuing. Common causes: wrong COM port
on capture machine, baud mismatch, flow control still enabled,
cable not a true null-modem (some "serial cables" are
straight-through and need a null-modem adapter).
4. Place USBDDOS.EXE somewhere in PATH (or run from its directory).

Run the test
In the terminal program on the capture machine, type a marker line so
the log has a clear start (this won't appear in PuTTY's local view but
will be in the log file):
=== START OF TEST: <today's date> ===
Now on the DOS machine:

Load USBDDOS with the flags for the device class you're testing:

USB keyboard / mouse: USBDDOS /hid
USB mass storage: USBDDOS /disk
RetroWave OPL3: USBDDOS /RW
Combine flags: USBDDOS /hid /disk

The driver should print initialization messages (which also go out
COM1).
Plug in your USB device (if it wasn't already attached).
Watch the terminal — enumeration messages should appear.
Try to use the device — type keys if it's a keyboard, list a
directory if it's a USB stick, etc.
If the system hangs or behaves strangely, that's the most
interesting data — let it sit for ~30 seconds, then note that the
system hung at this point in the log.
If everything works fine, run a quick smoke test (a few keystrokes,
list a directory if storage, etc.) and capture that too.

When done, in the capture terminal type another marker:
=== END OF TEST ===
Save the log file.

What to include in the bug report
Open an issue at https://github.com/Netrunner01/USBDDOS/issues with:

Title: short summary, e.g.
Tested on Compaq Evo N600c (ALi M5237) — works for keyboard, hangs on USB stick
Hardware:

Motherboard / system make and model
USB controller chip (run a DOS PCI inspector if you have one —
PCISLEEP, pciscan, lspci.exe from FreeDOS, or check the
motherboard manual). Specifically the PCI vendor:device ID for
each USB controller, e.g. 10B9:5237 for an ALi M5237.
CPU / RAM

BIOS version and any USB-related BIOS settings (USB Legacy
Support: enabled/disabled? USB controller: enabled/disabled?
USB keyboard support: enabled/disabled?)
DOS environment: variant and version
USB device tested: brand/model, USB version, if it works with
another driver (Bret Johnson's USBDOS, native BIOS support, etc.)
Command run: e.g. USBDDOS /hid /disk
What happened: works / fails / hangs / system crash / etc.
Specific symptoms — be detailed.
Attach the COM1 log file (drag-and-drop onto the GitHub
comment box). If GitHub blocks .log/.txt extensions you can put it
in a .zip first.

If posting a log inline (rather than as a file attachment), wrap it
in triple backticks so it renders correctly:

<paste log here>

Quick troubleshooting
ProblemLikely causeNothing in terminal at allWrong COM port on capture side, or cable not connectedGarbage characters in terminalBaud mismatch (try other speeds) or wrong line settingsECHO > COM1 works but USBDDOS produces no outputYou're running USBDDOSP.EXE (release build) instead of USBDDOS.EXE (debug build). Re-download from the release page — file size should be 94,380 bytes.Terminal stops receiving after a few secondsFlow control is enabled — disable itUSBDDOS fails to load with "DPMI host required"You have USBDDOSP.EXE instead of USBDDOS.EXE. USBDDOS.EXE (debug Watcom build) has built-in protected-mode entry and needs no DPMI host.

Thanks again for testing. Real-hardware reports are the single most
useful thing right now — works-fine reports are just as valuable as
bug reports, since both inform the alpha-to-beta promotion.

[netrunner01]

@netrunner01 so far i'm not having any luck with your v1.0.0 alpha build. on a kt133a system with a 4-port usb 2.0 hub plughed into an nec µPD720101 pci card, usbddos /hid is locking up while detecting (or immediately after) the devices on the hub. i have a usb microphone, bluetooth dongle, trackball (detected as keyboard + mouse) and a keyboard/trackpad combo plugged into the hub. it detects both trackball devices and both keyboard/trackpad combo devices before freezing. there are no issues with the functioning of any of the hub devices under win98se or linux q4os.

i also compiled a usbddos debug build from commit afb2b84 of https://github.com/netrunner01/USBDDOS.git, but i'm not sure where to start.

BTW, I don't think that there is audio or BT support in the driver. So, you may need to skip those for now.

[netrunner01]

@stanwebber You can just use USBDDOS.EXE from https://github.com/Netrunner01/USBDDOS/releases/tag/v1.0.0-alpha.1. That binary has all the patches. Your compiled version should be the same code. Worth a shot if you want to make sure of your test results before moving on to testing the hub and peripherals one at at time. Thanks again for helping out. Very much appreciated.