Skip to content
yeokm1Public

About

A generic USB 3.x, USB4, Thunderbolt host controller driver targeting Windows 98 SE, ME, 2000, XP, Vista, 7, 8 and 10.

Resources

Stars

157 stars

Watchers

5 watching

Forks

Repository files navigation

xhci98

xHCI98 is a USB host controller driver (HCD) for xHCI (USB 3.x) controllers on Windows 98 SE, ME, 2000, XP (x86/x64), Vista (x86/x64) and 7 (x86/x64).

Experimental support for USB4 and Thunderbolt 3/4 is also included, on those systems and on Windows 8, 8.1 and 10 (x86/x64), where the USB drivers are an optional install beside it.

Supported:

  • SuperSpeed devices and hubs:
    • USB 3.2 Gen 1, 5 Gbit/s
    • SuperSpeedPlus: USB 3.2 Gen 2 and Gen 1x2 (10 Gbit/s), and Gen 2x2 (20 Gbit/s)
  • USB 2.0 and 1.1 (High, Full and Low Speed) devices and hubs
  • UAS (USB Attached SCSI) storage via xhciuas.sys
  • Thunderbolt 3 and USB4 via xhcicm.sys

It is built to Intel's xHCI specification. Other vendors' controllers carry no guarantee, though best effort has been made for the quirks of Fresco Logic, ASMedia, AMD, TI, Etron, VIA and some Intel controllers, even ones built to the xHCI 0.96 draft standard.

This is a solo human's project with AI assistance, so bugs are not unexpected. Please report them.

Contents: Motivation - SuperSpeed and UAS - Thunderbolt 3 and USB4 - Installation Steps (Downloads, SETUP.EXE, by hand) - Tuning - Tested on - The package - Reporting a bug - Known limitations - Building - Repository Layout - Documentation - AI usage - References - Licensing

My 2020 ThinkPad P14s Gen 1 on Windows 98 SE with a USB 3.0 hub, two UAS drives, USB Ethernet, USB Audio and a mouse. All run on the xHCI controller, the drives at SuperSpeed.

CrystalDiskMark on the same machine, on an NVMe drive over Thunderbolt 3, with sequential speed 1020 MB/s read, 891 MB/s write.

Windows 98 SE on a real USB4 desktop, the ASUS ROG Crosshair X870E Apex. The xHCI98 USB Tree shows the ASMedia ASM4242 router running the USB4 software connection manager. The ORICO USB4 NVMe enclosure is approved on a 40 Gbit/s link, with its PCIe tunnel up. The NVMe drive is D: on Stor98, and CrystalDiskMark reads about 1 GB/s.

Motivation

PCs from the mid-2010s onwards have xHCI-only USB chipsets. Windows 98 shipped with USB 1.1 (UHCI/OHCI) drivers and gained USB 2.0 (EHCI) through NUSB's back-ported stack; Windows 2000 gained EHCI in SP4. Windows 7 has no USB 3 stack of its own either.

Without xHCI support, even keyboards, mice and flash drives need the BIOS's legacy support, cannot be hotplugged, and devices such as Ethernet and audio do not work at all. This project fills that gap.

SuperSpeed and UAS

The P14s Gen 1 under Windows 98 SE with NUSB: the MSSU10-128GSR flash drive at SuperSpeed through xhciuas.sys. ATTO Disk Benchmark (Direct I/O) gives about 201 to 215 MB/s write and 196 to 221 MB/s read from 512 KB transfers upward.

  • A UAS-capable drive gets UAS; anything else gets Windows' own usbstor.sys (Bulk-Only), at whatever speed it connects. A drive that offers both can be forced to Bulk-Only (XhciForceBulkOnly, see Tuning).
  • Device Manager and other Windows tools on these systems may show a SuperSpeed device as High Speed at most: the interface they read predates SuperSpeed.

Device Manager names USB 3 controllers by manufacturer and product as per list below.

Controller PCI ids In Device Manager
Intel 8 Series 8086:8C31 xHCI98 USB 3 Controller (Intel 8 Series)
Intel 500 Series 8086:43ED xHCI98 USB 3 Controller (Intel 500 Series)
AMD 500 Series 1022:43EE xHCI98 USB 3 Controller (AMD 500 Series)
AMD 800 Series 1022:43FC, 1022:43FD xHCI98 USB 3 Controller (AMD 800 Series)
Renesas uPD720202 1912:0015 xHCI98 USB 3 Controller (Renesas uPD720202)
ASMedia ASM1142 1B21:1242 xHCI98 USB 3 Controller (ASMedia ASM1142)
ASMedia ASM3242 1B21:3242 xHCI98 USB 3 Controller (ASMedia ASM3242)
VIA VL805/VL806 1106:3483 xHCI98 USB 3 Controller (VIA VL805/VL806)
Fresco Logic FL1100 1B73:1100 xHCI98 USB 3 Controller (Fresco Logic FL1100)
Etron EJ188/EJ198 1B6F:7052 xHCI98 USB 3 Controller (Etron EJ188/EJ198)

Thunderbolt 3 and USB4

xhcicm.sys brings Thunderbolt 3 and USB4 docks, enclosures and NVMe cases to these systems. Devices inside them (an NVMe drive, a dock's USB controller or network adapter) appear in Device Manager within seconds of the plug, with no Refresh, and leave on unplug. A device the BIOS connected at power-on is kept as it is.

  • Intel Thunderbolt 2 and 3 controllers, and USB4-generation Intel ones while their firmware runs its own connection manager: the driver approves each device the firmware announces.
  • USB4 hosts whose firmware has no connection manager (AMD, ASMedia ASM4242, Intel Lunar Lake and later, Barlow Ridge), the driver is the connection manager and builds the tunnels.

Device Manager names each controller by its generation, then its manufacturer and product: Thunderbolt 2 and Thunderbolt 3 (TB2, TB3) controllers, and USB4 Routers (the USB4 host router).

Controller PCI ids (8086: unless named) In Device Manager
Falcon Ridge (Thunderbolt 2) 156A, 156C xHCI98 TB2 Controller (Intel Falcon Ridge)
Alpine Ridge (Thunderbolt 3) 15BF, 1575, 1577, 15D2, 15D9 xHCI98 TB3 Controller (Intel Alpine Ridge)
Titan Ridge (Thunderbolt 3) 15E8, 15EB xHCI98 TB3 Controller (Intel Titan Ridge)
Ice Lake 8A0D, 8A17 xHCI98 TB3 Controller (Intel Ice Lake)
Maple Ridge 1134, 1137 xHCI98 USB4 Router (Intel Maple Ridge)
Tiger Lake, Alder Lake, Raptor Lake, Meteor Lake 9A1B, 9A1D, 9A1F, 9A21; 463E, 466D; A73E, A76D; 7EB2, 7EC2, 7EC3 xHCI98 USB4 Router (Intel Tiger Lake), (Intel Alder Lake), (Intel Raptor Lake), (Intel Meteor Lake)
Lunar Lake, Panther Lake, Wildcat Lake A833, A834; E333, E334, E433, E434; 4D33 xHCI98 USB4 Router (Intel Lunar Lake), (Intel Panther Lake), (Intel Wildcat Lake)
Barlow Ridge 5781, 5784 xHCI98 USB4 Router (Intel Barlow Ridge)
AMD Pink Sardine 1022:1668, 1022:1669 xHCI98 USB4 Router (AMD Pink Sardine)
ASMedia ASM4242 1B21:2425 xHCI98 USB4 Router (ASMedia ASM4242)
Any other USB4 host PCI class 0C0340 xHCI98 USB4 Router

Before you start: 64-bit Windows

On Vista x64 to 10 x64, keep test-signing mode on for as long as the Thunderbolt 3 / USB4 support is installed, even with nothing plugged in: without it the support does not load, and its devices and the USB controllers this package runs show Code 52 (Code 39 on Vista).

Before you start: the BIOS

  • Boot in legacy (CSM) mode, as for every system here.
  • Thunderbolt BIOS Assist off. With it on, the BIOS switches the controller off when nothing is attached at power-on, and the driver cannot switch it back on (on the P14s Gen 1 the controller disappears altogether).
  • Security level User Authorization or No Security. Secure Connect, DisplayPort-only and USB-only are not supported.
  • Pre-boot support (boot from Thunderbolt) may be on or off. When on, a device attached at power-on keeps working under the driver.
  • Above 4G Decoding. Off for 32-bit OS, on for 64-bit.

Approving and removing

  • Names: on Windows 2000 to 7 the controller's PCI ports show as "xHCI98 Thunderbolt PCI Bridge" or "xHCI98 USB4 PCI Bridge", an ASM4242's downstream ports as "xHCI98 USB4 PCI Bridge (ASMedia ASM4242)" (Windows' own bridge driver with this package's filter).
  • Approval: by default (XhciCmApprove 1) every device plugged in is approved at once. A device with a PCI Express tunnel can read and write all of the machine's memory, and these systems cannot stop it. Where untrusted people can reach the port, set XhciCmApprove to 0: only devices the BIOS connected at power-on then work.

Removing a device safely. Close its open files first, then:

Windows How
2000 Stop it in "Unplug or Eject Hardware", then unplug. Without the stop, Windows 2000 shows "Unsafe Removal of Device".
XP, Vista, 7 Stop it in "Safely Remove Hardware", then unplug.
98 SE, ME No such dialog lists them (ME's "Unplug or Eject Hardware", and NUSB 3.3's on 98 SE, list USB storage only): use the xHCI98 USB Tree or INSTALL /console /eject. Until you unplug, Device Manager's Refresh can start the device again.
  • A dock is listed under a generic PCI bridge name; stopping it stops everything in the dock.
  • A device missing from Windows' list (its first plug, or after a disable and enable or a driver update): stop it in the USB Tree run as an administrator. Otherwise close every program using it, unplug it and plug it in again; Windows lists it from then on.
  • For scripts: INSTALL /console /devices and INSTALL /console /eject (tools\xhciinst\readme.txt).

NVMe drives

An NVMe drive in an enclosure needs an NVMe driver. Stor98, shipped with this package, is that driver where Windows has none, or where Windows' own one handles an unplug badly. xhcicm.sys runs the tunnel; Stor98 runs the drive.

Windows Driver of a tunnelled NVMe drive Why
98 SE, ME, 2000, XP, Vista, 8 Stor98 no NVMe driver of its own
7 Stor98 its stornvme comes only with update KB2990941
8.1 Stor98 (internal drives keep stornvme) its stornvme hangs a write for good on an unplug without Safely Remove
10 Windows' own stornvme; Stor98 is opt-in stornvme handles an unplug cleanly

Use Safely Remove before unplugging a drive, on every system.

Stor98 is only for NVMe drives behind a Thunderbolt or USB4 port, not internal ones. SETUP.EXE puts it only on tunnel drives.

On 2000 to 8, its INF matches only the id the connection manager gives a tunnel drive, so Windows never offers it for an internal one.

On 8.1 and 10 Windows' own stornvme keeps an internal drive.

On 98 SE and ME Windows may offer it for an internal NVMe drive with no driver: decline. An internal drive that already runs Stor98 keeps it, and the uninstall leaves it there.

  • SETUP.EXE installs Stor98 with the Thunderbolt 3 / USB4 support (its box, ticked with it) and updates an earlier Stor98. By hand: Update Driver on the drive's NVMe controller -> Have Disk -> the stor98\ folder of 98-me\, nt-x86\ or nt-x64\.
  • On 98 SE and ME, S98VSD.VXD lets reads and writes of up to 2 MiB reach Stor98 whole, for much faster transfers. SETUP.EXE installs it with Stor98.
  • Stor98's settings and limits: stor98-readme.txt beside it, and the release notes.

Thunderbolt networking

Two computers joined by one Thunderbolt or USB4 cable can share a network connection, file sharing included, in the frame format Linux's Thunderbolt networking uses. It is off unless you tick "Thunderbolt networking" on the installer's Thunderbolt and USB4 page.

On 98 SE and ME, install Thunderbolt networking through SETUP.EXE. A manual Have Disk install of the network adapter needs xhcinet.sys copied to the Windows SYSTEM folder first.

Installation Steps

Downloads

Each release has three zips. Each holds everything in the one before it, so pick one:

Download What it holds
xhci98-<version>.zip The xHCI98 drivers (USB 3, UAS, Thunderbolt 3 / USB4), Stor98, the installer and the tools. Also NUSB 3.3's seven Windows 98 SE storage files in USBDRV\NUSB33\, which the installer offers on 98 SE when NUSB is not installed.
xhci98-<version>-free.zip Adds the free USB class drivers (audio, webcam, Ethernet, printing and more) from usb-wdm-free in USBDRV\FREE\. Experimental: they may not work with every device and can make Windows unstable.
xhci98-<version>-nonfree.zip Adds the manufacturers' Ethernet, HID, serial and audio drivers from usb-wdm-nonfree in USBDRV\NONFREE\, not this project's work. Wi-Fi drivers are not in this download. Get them from the usb-wdm-nonfree release.

Nothing from USBDRV\ is installed unless you tick it on the installer's Free USB drivers or Non-free USB drivers page (each shown when the download carries that set).

On Windows 98 SE and ME the free and non-free drivers are copied to the install directory, and the ones ticked are also added to the hardware wizard's search path, so Windows finds them at the first plug. When the hardware wizard asks for a driver, point it at the package's folder, USBDRV\FREE\<class>\<package>\<folder> (or USBDRV\NONFREE\...) in the install directory.

Requirements

Windows What to install first
98 SE Nothing. NUSB 3.3 installed beforehand is acceptable, otherwise it is not needed: the setup package carries the necessary files.
ME Nothing. UAS drives need storage drivers to be copied beforehand. This can be done automatically by connecting an ordinary Bulk-Only USB disk for the first time, so that Windows ME copies the drivers.
2000 SP4, XP SP3 Nothing.
XP x64 SP2, Vista SP2, 7 SP1 (x86/x64) Nothing. Vista x64 and 7 x64 need test-signing mode (or F8 at every boot).
8, 8.1, 10 (x86/x64) Secure Boot off in the firmware setup; the x64 editions also need test-signing mode. Windows' own USB 3 driver stays unless you tick the USB drivers.
  • On an xHCI-only 98 SE or ME machine, have the Windows CD (or its files) at hand: Windows may ask for files.

Install with SETUP.EXE

You can also install by hand from Device Manager (the release notes' Installing).

  1. Unzip the whole package.
  2. Double-click SETUP.EXE in its top directory (on 2000 and XP as an administrator, on Vista and later answer Yes when Windows asks).
  3. Go through the pages: Welcome, Components, Thunderbolt and USB4 (when that support is ticked), Free USB drivers and Non-free USB drivers (when the download carries them) and Summary. Help, or F1, explains the page you are on. The driver's options are under Settings; the tools go to C:\XHCI98. Nothing changes until you click Install.
  4. Answer Windows' unsigned-driver questions. If the Finish page lists steps left for you (a Found New Hardware window, for instance), do them and run SETUP.EXE again. Restart if it offers.

To uninstall, use Remove in Add/Remove Programs (Programs and Features on Vista and later). Every run writes XHCIINST.LOG at the root of the system drive, or, on 98 SE and ME, in the temp folder if that file cannot be written; Setup shows the path. Attach it to a bug report about an install. For scripted installs, see tools\xhciinst\readme.txt.

The controller in Device Manager on the P14s Gen 1 under Windows 98 SE.

64-bit Vista to 10: test-signing mode

The 64-bit drivers are test-signed, so Vista x64 to 10 x64 run them in test-signing mode (or with F8, "Disable Driver Signature Enforcement", at every boot). On 8, 8.1 and 10, turn Secure Boot off in the firmware setup first. Then, once:

  1. Open an elevated Command Prompt (Start, type cmd, right-click, Run as administrator).
  2. Run bcdedit /set testsigning on. It stays on for every boot until turned off.
  3. Restart. "Test Mode" shows on the desktop (bottom right on 7 and later, in the corners on Vista).
  4. Install the driver. Windows still says it cannot verify the publisher: choose "Install this driver software anyway". The Driver tab then says "Not digitally signed". Both are expected.
  • Check: bcdedit /enum {current} shows testsigning Yes.
  • Turn off: bcdedit /set testsigning off and restart. The driver then needs F8 again, or the controller shows Code 39 (Vista) or Code 52 (7).
  • With BitLocker on the system drive, suspend it before changing the boot setting, or the next boot asks for the recovery key.
  • This is not Microsoft signing: the certificate is the project's own, which no Windows trusts by itself. F8 still works for one boot without test mode.

Installing Windows 2000 or XP, or using the Recovery Console

For a machine whose keyboard or install medium is on the xHCI controller:

  1. Copy the files at the root of nt-x86\ (nt-x64\ for XP x64), without its subfolders, to the root of a floppy.
  2. Windows 2000 only: from the I386 folder of your Windows 2000 CD, copy USBD.SY_, HIDCLASS.SY_ and HIDPARSE.SY_ to the floppy's root, unchanged (do not expand or rename). The package does not carry them.
  3. Press F6 when text-mode Setup offers it, then S, and pick "xHCI98 USB 3 Controller (32-bit Windows 2000/XP)" (the x64 entry on XP x64), or on Windows 2000 the second entry, "xHCI98 USB 3 Controller (32-bit Windows 2000, files from CD)".
  • Windows 2000: with a USB keyboard, mouse or stick used during Setup, the first entry leads to STOP c000026c at the first start; the second entry without the three files stops Setup asking for them in drive A: (F3 quits). Plug the USB keyboard and stick in before Setup starts.
  • XP and XP x64: have a PS/2 or built-in laptop keyboard at hand. Later in Setup the USB keyboard does not work until a step that first asks about this unsigned driver.
  • Pressing F6 needs the BIOS's own USB keyboard support.
  • A USB floppy drive works for F6 only if it is one Setup knows: Mitsumi 03EE:6901, Y-E Data 057B:0000 or TEAC 0644:0000 (VID:PID). No INF can add another; otherwise use a floppy drive on the floppy controller.
  • A UAS-only disk is not usable until GUI-mode Setup; a flash stick, or a UAS disk that also offers Bulk-Only (most do), is.
  • A USB drive present at the partition screen takes C:. Unplug the USB drives you do not need.
  • Recovery Console (2000 and XP): the same floppy and F6, then R at the Welcome screen (on 2000, then C). The USB keyboard works throughout.

Details and limits: the release notes' F6 section.

Tuning

The easiest way to change a setting is the xHCI98 USB Tree: View > Settings... shows the drivers' settings and changes them. Setup's Settings dialog and "Advanced..." set them at install.

  • Each value is a DWORD in the driver (software) key below.
  • The same value in the machine-wide key HKLM\System\CurrentControlSet\Services\USB wins for every controller (tuning).
  • Restart Windows after a change. For XhciCm* values, disabling and enabling the controller also works.
  • An update keeps any value you changed.

On Intel 7/8/9-series boards, the driver moves the blue USB 3 ports from EHCI to itself when installed via the Setup program. If you slipstreamed the driver into an ISO, the default is not to move to avoid switching problems during Windows Setup. After Windows Setup completes, use xHCI98 USB Tree to change this setting, View > Settings..., select XhciIntelPortSwitch, choose '1 - on' and Apply, and restart Windows.

Driver Windows Key (NNNN is the subkey whose DriverDesc names the controller)
xhci98.sys 98 SE, ME HKLM\System\CurrentControlSet\Services\Class\USB\NNNN
xhci98.sys 2000 to 10 HKLM\SYSTEM\CurrentControlSet\Control\Class\{36FC9E60-C465-11CF-8056-444553540000}\NNNN
xhcicm.sys 98 SE, ME HKLM\System\CurrentControlSet\Services\Class\System\NNNN
xhcicm.sys 2000 to 10 HKLM\SYSTEM\CurrentControlSet\Control\Class\{4D36E97D-E325-11CE-BFC1-08002BE10318}\NNNN
Value What it does Default
XhciLogVerbosity The driver's log level, read by the USB Tree (0 to 4; 0 off) 2 (fresh install; an update keeps the value there)
XhciLogDebugView The log sent to DebugView as well 0
XhciInterruptMode How events arrive: 0 automatic, 1 interrupt line, 2 polling, 3 message-signalled interrupt only 0
XhciSelectiveSuspend 1 suspends idle devices when Windows asks 0
XhciResumeKeep 1 keeps a device on a root port (its drive letter and open files) across a resume that starts the controller afresh; 0 removes it and finds it again 1
XhciMaxTransferKB The largest UAS command, 64 to 2048 KiB 1024
XhciForceBulkOnly 1 uses Bulk-Only instead of UAS 0 (1 if the value is absent)
XhciBulkOnlyOwnId 1 gives a drive that offers UAS and Bulk-Only a Device Manager entry of its own where it is used as Bulk-Only; 0 one entry everywhere, as before 3.4.2.0 1
XhciIntelPortSwitch Intel 7/8/9-series port switchover: 1 on, 0 off, 2 any Intel controller at your own risk 0 (Setup writes 1 at a first install on these boards; an update keeps the value there)
XhciCmMode Thunderbolt/USB4: 0 off, 1 automatic (2 and 3 are at your own risk) 1
XhciCmApprove 1 approves every device, 0 none (see approval) 1
XhciCmSafeEject 1 offers tunnelled devices for safe removal (98 SE and ME: in the USB Tree and INSTALL /console /eject only) 1
XhciCmBridgeNumbering 98 SE and ME: 1 sets up PCI bridges behind a tunnel plugged in after start (else Code 29 until restart) 1
XhciCmLogVerbosity The Thunderbolt driver's log level, read by the USB Tree (0 to 4) 2
XhciCmLogDebugView The Thunderbolt driver's log sent to DebugView as well 0
XhciCmNet 1 turns on Thunderbolt networking 0

docs/using/tuning.md has every value of both drivers, its range and its effect, including polling periods, interrupt moderation, controller-fault handling, the per-controller fixes, the Linux-derived controller quirks and the XhciCm* values.

Tested on

Machine Controller Tested by
2012 Lenovo B490 Intel Ivy Bridge, Panther Point HM77 (7-series) PCH, with EHCI beside it. xHCI 1.0. Me
2012 HP EliteBook 2570p Intel Ivy Bridge, Panther Point QM77 (7-series) PCH, with EHCI beside it. xHCI 1.0. Community
2012 HP EliteBook 8470p Intel Ivy Bridge, Panther Point QM77 (7-series) PCH, with EHCI beside it. xHCI 1.0. Me
2015 Dell Latitude E7250 Intel Broadwell-U, Wildcat Point-LP (9-series) PCH, with EHCI beside it. xHCI 1.0. Me
2016 ThinkPad E460 Intel Skylake, Sunrise Point-LP (100-series) PCH. xHCI 1.0. Me
2018 HP EliteBook 850 G5 Intel Sunrise Point-LP, xHCI 1.0. Community
2020 ThinkPad P14s Gen 1 Intel Comet Lake PCH-LP (400-series). xHCI 1.1. Me
ASUS ROG Crosshair X870E Apex AMD 800-series chipset and Ryzen (Raphael) xHCI controllers; ASMedia ASM4242 USB4 host. Me
Omores' Intel and AMD desktops H110, B360, B550, X570, X670 Omores
VMware Workstation 26 (virtual hardware 21), Windows XP SP3 guest VMware's virtual xHCI (15AD:077A), a USB 3.0 stick at SuperSpeed Community

The package

The drivers are in one folder per Windows family: 98-me\ (98 SE, ME), nt-x86\ (2000, XP, Vista, 7, 8, 8.1 and 10, 32-bit) and nt-x64\ (XP x64 and Server 2003 x64, Vista to 10, 64-bit). Each holds what its Windows installs, and nothing for another.

Path Contents
98-me\, nt-x86\, nt-x64\ The drivers to install (below)
INTEGRATE.TXT Which folder to give nLite, NTLite or DISM, and the F6 disk
SETUP.EXE The installer: double-click it to install or update
USBDRV\ Other USB drivers the download carries: NUSB33\, plus FREE\ in the -free download, and FREE\ and NONFREE\ in the -nonfree one (Downloads)
INSTALL.BAT, tools\xhciinst\ For command-line and scripted installs (tools\xhciinst\readme.txt is the reference), and the programs both run (XHCIWIZ.EXE, XHCIWZ64.EXE, XHCIINST.EXE, XHCIIN64.EXE, and on 98 SE and ME the device install helper XHCIDI.EXE)
tools\xhcitr\ The xHCI98 USB Tree, also the driver's log and snapshot reader
tools\xhcimark\ XHCIMARK.EXE, XHCIMK64.EXE: the Thunderbolt safe-removal mark service, which the installer puts in place on 2000 to 10 with the Thunderbolt 3 / USB4 support
tools\xhciqual\ DOS: XHCIQUAL.EXE and QUALREP.BAT
tools\silent\ 98 SE and ME: the silent install's list and switch
readme.txt The release notes in plain text

Each family folder holds:

  • At its root
    • xhci98.sys/.inf: the controller driver
    • xhciuas.sys/.inf: UAS storage
    • nt-x86\ only: xhcihlpr.sys, a helper that 32-bit 2000, XP, Vista and 7 use for a finer timer while polling, and on Vista and 7 for a message-signalled interrupt
    • nt-x86\ and nt-x64\: txtsetup.oem, for F6 during Windows 2000 or XP Setup (the folder's root files are the F6 floppy)
  • cm\: Thunderbolt and USB4
    • xhcicm.sys/.inf: the connection manager
    • nt-x86\ and nt-x64\: its PCI-port filter, xhcicmf.inx, which SETUP.EXE installs and no integration tool takes
    • cm\tbnet\: the Thunderbolt networking driver, xhcinet.inf and xhcinet.sys
      • nt-x86\ and nt-x64\ also: xhcinet6.sys
      • nt-x64\ also: xhcinet.cat
    • nt-x86\ only: a second copy of xhcihlpr.sys, for the connection manager's own install
    • XHCIPFW, which closes the USB4 ports' memory windows above 4 GB at Windows start (see the BIOS):
      • 98-me\: XHCIPFW.VXD
      • nt-x86\: XHCIPFW.SYS, for 32-bit 2000 to 8.1
  • stor98\: the bundled NVMe driver (see NVMe drives)
    • 98-me\ also: stor98.mpd and S98VSD.VXD
  • nt-x64\ only: the test signatures
    • xhci98-test.cer: the public half of the x64 drivers' test certificate (no need to import it)
    • a test-signed catalog (*.cat) for each driver, which 64-bit 8, 8.1 and 10 need

Reporting a bug

Bugs in the free USB class drivers go to usb-wdm-free's issues. The non-free drivers are from their manufacturers, as released, except where that pack's README says a file was changed. Everything else: open a bug report and attach:

  • The driver's report: make the problem happen, then in the xHCI98 USB Tree use File > Save Report (or XHCITR /report <file>) and attach the .TXT. It needs the logging level at 2 or more (the default; View > Logging level...).
  • The driver's snapshot: right after the report, use File > Save Snapshot... (or XHCITR /snapshot; XHCITR64 on 64-bit Windows) and attach every file it writes: four for each controller xHCI98 drives (.D, .T, .B and .P, each followed by the controller's number, named from the date and time), and two for each Thunderbolt or USB4 controller (.CT and .CB, each followed by its number).
  • The DOS report, if a maintainer asks for it: run QUALREP.BAT from real DOS in TOOLS\XHCIQUAL\ and attach the .LOG it names (read-only). If a maintainer asks for the full run, XHCIQUAL --no-page --log FULL.LOG resets the controller and its ports: use a PS/2 keyboard, and do not write the log to a drive on that controller.
  • An install problem: XHCIINST.LOG from the root of the system drive (or from the path Setup showed).

Known limitations/issues

The release notes' Known limitations, Thunderbolt and USB4 limitations have the full lists. The ones most likely to matter:

Windows and hardware limitations

These come from Windows or the hardware itself (most happen on Microsoft's own USB stack too), so the driver cannot fix them.

  • Windows 98 SE
    • The first USB audio device plugged in after a boot (a webcam with a microphone included) can freeze Windows. Plug it in before switching on and leave it plugged in. If you have a webcam but do not use the microphone, you can use usb-wdm-free's NOAUD98.INF.
    • Stop audio playback before unplugging a USB audio device. Unplugged while Windows' own USB audio driver plays it, the device can freeze Windows.
  • Windows ME
    • Do not unplug a device while Windows is installing it.
    • A UAS drive plugged in before any ordinary stick shows Code 2. Plug in an ordinary Bulk-Only stick once, then replug the UAS drive.
  • Windows 98 SE and ME
    • Installing the free audio or MIDI driver, Windows may ask for wdmaudio.cat, ks.cat and other files of its own from the Windows CD. Point it at the CD's WIN98 folder, or click Skip File for the .cat files: they only hold signatures, which 98 SE and ME do not check.
  • Windows XP
    • Installing XP from the F6 floppy needs a PS/2 or built-in keyboard to answer GUI-mode Setup's unsigned-driver question. Windows 2000 does not ask.
  • Vista x64 and 7 x64
    • Test-signing mode or F8 is needed at every start; otherwise the controller sits at Code 39 (Vista) or Code 52 (7).
  • Windows 8, 8.1 and 10
    • Secure Boot must be off, and the x64 editions need test-signing mode.
  • Thunderbolt and USB4
    • Windows 2000: the first time a Thunderbolt dock is plugged in, Windows asks to restart for each of its PCI bridges; until the restart some of the dock's devices do not start.
    • Windows 2000 with the "Standard PC" computer type: an NVMe drive plugged in behind the tunnel after the start works, but runs polled. Drives attached at power-on are not affected (issue 19).
    • A dual-mode NVMe enclosure (TB/USB4, and USB) may come up as a USB (UAS) disk instead. Unplug it and plug it in again to get the Thunderbolt or USB4 connection.
    • Windows 98 SE and ME: a device plugged in after the start needs an interrupt from the BIOS (the P14s Gen 1 gives one). An NVMe drive on the bundled Stor98 and a Thunderbolt dock's second and further USB controllers start without one, polled (XhciCmNoIrqStart, on by default).
    • Windows 98 SE and ME: if a device stays at Code 29, attach it at power-on with pre-boot support on. A drive attached at power-on cannot be stopped from the xHCI98 USB Tree: shut down Windows before you unplug it.
    • Windows 98 SE and ME: the Thunderbolt driver stays loaded until a restart, so a disable, update or removal takes effect after one.

Driver issues

These are xHCI98's own and may be fixed in a future release.

  • Thunderbolt and USB4
    • Standby and hibernation, Windows 2000 to 10: supported when the drive was connected before Windows started, or when the computer's firmware sets up its USB4 ports again at the wake. Otherwise stop the drive first.
    • Windows 7 to 10, a drive plugged in after Windows started: standby or hibernation disconnects it, as if it had been unplugged, and any file being written to it is lost. Stop the drive before sleeping; after the wake, unplug it and plug it in again.
    • Standby, Windows 98 SE and ME: stop and unplug the drive first; a drive connected when Windows started cannot be stopped, so shut down instead. On 98 SE a drive on a dock left in during standby disconnects at the wake and comes back a few seconds later: close its files first, and eject it if the data matters.
    • Windows ME (rarely 98 SE): with a dock or chain attached at power-on, the first start after the install can stop with a fatal exception 0E.
    • Docks (98 SE and ME; 2000 to 7 under a firmware connection manager): stop a dock before unplugging it when a keyboard, mouse, tablet or network adapter is on its USB controller; otherwise Windows may not shut down.

Toolchain and building

The drivers are C89 (no C++ or CRT), built on Windows 11 x64. The toolchain unpacks inside the repository (tools/, git-ignored), installs nothing to C:\, and every script finds it relative to itself.

  1. Download into tools\ under these exact names:

    File Source
    tools\MSVC600.zip MSVC 6.0 - itsmattkc/MSVC600
    tools\WIN2KDDK.EXE Windows 2000 DDK - KunYi/WDK_DDKArchive

    The 64-bit build (and the 32-bit xhcihlpr.sys) also needs WDK 7.1 (7600.16385.1) unpacked to tools\WinDDK71.

  2. Unpack them in place:

    powershell -ExecutionPolicy Bypass -File scripts\setup-msvc6.ps1        # -> tools\MSVC600
    powershell -ExecutionPolicy Bypass -File scripts\install-w2kddk-cabs.ps1 # -> tools\ntddk
  3. Build. release (default) is the one shipping flavour; all adds the qemu development flavour, which is never published. -amd64 builds the separate 64-bit binaries. Every build runs the gates' self-tests, the host unit tests and the INF, import and charset gates, and stops on any failure.

    scripts\build-driver.cmd release
    scripts\build-driver.cmd release -amd64
    

    The same runs build and gate Stor98, the bundled NVMe driver, from src\stor98 (it also needs the Windows 98 DDK's SCSI.H and SRB.H in tools\w98ddk\inc; src/stor98/docs/BUILD.md); scripts\build-all.cmd runs both architectures at once.

  4. The tools build with their own build.cmd in xhciqual\ (needs Open Watcom 2.0 at C:\WATCOM), xhciinst\ and xhcitr\.

  5. Install media: scripts\package\make-package.ps1 (to out\); a release cut: scripts\package\make-release.ps1. Never hand-copy a .sys without its INF.

  6. Test as build-and-test.md describes.

The version lives in src/xhci_version.h. build-and-test.md has the full procedure (test setups, gates, versioning, packaging), and source-files.md says what each source file is.

Repository Layout

src/            xhci98.sys (C), its two INFs and DDK build files
  uas/          xhciuas.sys, the UAS class driver
  cm/           xhcicm.sys, the Thunderbolt and USB4 driver
  net/          xhcinet.sys and xhcinet6.sys, Thunderbolt networking
  pfw/ vsd/     XHCIPFW and S98VSD.VXD
  stor98/       Stor98, the bundled NVMe driver (BSD-3-Clause)
test/           Host-side unit tests (test\run-host-tests.cmd)
scripts/        Build wrapper, setup helpers, gates, vm-matrix/
xhciqual/       DOS hardware-qualification tool (Open Watcom)
xhciinst/       Install/update/uninstall tool and INSTALL.BAT
xhcitr/         The xHCI98 USB Tree
xhcimark/       The Thunderbolt safe-removal mark service
docs/           Documentation, indexed by docs/README.md
releases/       Every release cut, one directory per version
images/         Pictures used by this README
.github/        Issue forms
AGENTS.md       Maintainer and AI agent guide
tools/ external/ vm/ out/   Toolchain, reference mirrors, test disks, staged media (git-ignored)

Documentation

Everything is under docs/, indexed by docs/README.md. Start with:

AI usage

This project was developed with substantial help from AI coding agents:

  • Claude Fable 5.1 for planning
  • Claude Opus 5.5 for coding
  • Codex GPT 6 Astra as an adversarial reviewer

The agents wrote and revised code, tests and documentation under the guidance in AGENTS.md.

Kheng Meng directed the work, ran the hardware validation on real machines and reviewed what went in.

References

None of these PDFs is tracked here; fetch your own into the git-ignored docs/references/ (docs/references/README.md has versions and SHA-256 sums). Source mirrors go in external/ (external/README.md).

Licensing and provenance

xHCI98 is licensed under GPL-2.0-or-later (LICENSE); Stor98 keeps its own BSD-3-Clause licence (src/stor98/LICENSE). The repository holds no Microsoft file, but some downloads carry third-party drivers unmodified, without an established licence to redistribute them. The details are in docs/contributing/legal-provenance.md.

The documentation (every Markdown file outside src/stor98/, this README included) is licensed under CC BY 4.0, not the GPL. LICENSE-docs.md gives the scope, what is excluded and how to credit. Third-party material quoted in the documentation keeps its own terms.

If you use anything from the xHCI98 project and its blog posts in your work, please credit this repository and/or blog post. I would be interested to know how it has helped.

Third-party work used

  • Stor98, the bundled NVMe driver, is a fork of SweetLow's nvme9x / nvment, SweetLow's port to Windows 9x and NT4 of nvme2k by Dominik Behr (techomancer). Its README and NOTICE give the lineage and the licence.
  • The Windows 98 SE USB storage files in the release download are taken unmodified from the NUSB (Native USB) project's 3.3 release by Maximus Decim; the files themselves are Microsoft's, apart from USBU2A.SYS (see "Licensing and provenance").

About

A generic USB 3.x, USB4, Thunderbolt host controller driver targeting Windows 98 SE, ME, 2000, XP, Vista, 7, 8 and 10.

Resources

Stars

157 stars

Watchers

5 watching

Forks

Releases

Packages

Contributors

Languages