Skip to content

Fix Windows driver setup, dongle access, and the restore-mode stall - #58

Merged
fcjr merged 10 commits into
mainfrom
windows-driver-fixes
Nov 17, 2026
Merged

fcjr merged 10 commits into
mainfrom
windows-driver-fixes

Conversation

@fcjr

@fcjr fcjr commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Fixes for problems I hit driving a restore entirely from Windows. I tested in a Windows 11 25H2 VM with the Dongle-Lite and an M4 Mac mini passed through, and with Apple's appleusb.inf installed the way iTunes or Apple Devices would leave it. A non-erasing revive ran to Restore Finished on this branch, with DFU triggered from Windows over the dongle.

#56: stuck at "Waiting for device to enter restore mode"

The reporter's log shows libusb failing to open RESTORE_MODE&MI_00 with error 50 through {664BE590-…}, which is the interface GUID from Apple's AppleUsbMux_Install. So Apple's driver still owned restore mode. The force-bind watcher can end up doing nothing in two ways:

  • No RestoreKit package staged. With Apple's driver installed, DFU and recovery work without setup-driver, so a restore can reach restore mode before our INF was ever staged. The watcher then exits 1 without saying anything. I confirmed this by removing the package and running the watcher worker on 0.6.2. There's no package to stage any more (see "No driver package" below): the watcher binds Windows' own WinUSB itself, and it logs what it did to %TEMP%\restorekit-restore-watch.log.
  • UAC declined. Before, the restore carried on and hung minutes later. Now it stops up front and says so.

I couldn't reproduce the reporter's exact machine, so this is the likely cause, not a confirmed one. The log file is what to ask for if it still happens.

No driver package

setup-driver used to generate a WinUSB INF, sign its catalog with a self-signed certificate it added to the machine's trusted roots, and stage it with pnputil. Windows on ARM refuses such packages outright ("Driver package signer is not trusted by system, and Code Integrity is enforced"), and the certificate step failed on a clean 25H2 machine.

Now nothing is packaged or signed. restorekit binds Windows' own Microsoft-signed winusb.inf:

  1. It builds a driver list from just that INF with DI_FLAGSEX_ALLOWEXCLUDEDDRVS. Its "WinUsb Device" entry matches USB\MS_COMP_WINUSB, not the Mac, which is the same thing Device Manager's "Have Disk" route allows.
  2. It installs that entry on the one device instance with DiInstallDevice.
  3. It writes the mode's DeviceInterfaceGUIDs to the device's registry key, the way the INF's AddReg did.

A device already on WinUSB without a GUID, such as a dongle on old firmware, just gets the GUID and a restart.

  • setup-driver binds present devices this way. Devices on Apple's own drivers are left alone, because libirecovery talks to those directly.
  • The restore-mode watcher is now a Rust loop instead of PowerShell. It binds the restore-mode interface when it appears, plus any DFU, recovery or KIS device left with no driver for a few seconds.
  • No certificate, catalog, pnputil or PowerShell, and it works the same on x64 and ARM64.

Device waits on Windows

  • libimobiledevice-glue's Windows cond_t was a semaphore. A signal with no waiter was counted rather than dropped, so after one stray device event the next "wait for the device to disconnect" returned at once and idevicerestore failed with "Device did not disconnect". A wait also never re-took the mutex. It's now a CONDITION_VARIABLE with the CRITICAL_SECTION mutex, which behaves like the pthreads version these callers are written for.
  • dfu_enter_recovery gave iBEC 10 seconds to boot. It now waits 60, like the same step in idevicerestore.c.

Dongle on Windows

No dongle command worked on Windows: "Could not find DeviceInterfaceGUIDs in registry". The firmware asks for WinUSB through its MS OS 2.0 descriptors but never gives an interface GUID. Without one, Windows doesn't expose the vendor interface of a composite device, and nusb can't open it.

  • The firmware now advertises a GUID. It's shared through restorekit-dongle-proto, which also pins the vendor interface number. It isn't flashed or released yet.
  • setup-driver binds the dongle interface with that GUID for dongles already out there, and now runs with only a dongle connected. Without that, Windows users couldn't use the dongle to get the Mac into DFU in the first place.

Driverless with Apple's stack

Windows Update installs Apple's drivers for DFU (WUDFRd), recovery and KIS (AppleKIS) on first plug-in, and libirecovery's Windows backend already talks to them. Only two things still needed our WinUSB:

  • Restore mode. When Apple Mobile Device Service (from iTunes or Apple Devices) is running, it listens on 127.0.0.1:27015 and muxes the restore-mode interface through Apple's driver. restorekit now uses it as-is and skips both the embedded usbmuxd and the WinUSB watcher. It checks that the listener really is Apple's service, by matching the port's owning pid (GetExtendedTcpTable) against the service's pid from the service manager. Any other listener, such as another restorekit restore, stops the restore up front with that program's name. Before this, the embedded usbmuxd tried to bind that same port, so a restore on a machine with Apple's service installed most likely failed at startup.
  • KIS identify. restorekit read a KIS Mac's identity over WinUSB. With AppleKIS bound it now sends the GET_INFO ioctl to AppleKIS's KIS\VID_05AC&PID_0001 child device, the same request libirecovery sends.

Related changes:

  • driver_ready counts Apple's DFU and KIS drivers, so the desktop app doesn't ask for "Set up USB access" when they're bound.
  • setup-driver no longer moves devices off Apple's drivers. They work as they are, and moving a KIS Mac off AppleKIS strands it until it re-enters DFU.
  • AppleKIS sometimes misses the Mac. Entering KIS DFU from a fully booted Mac, AppleKIS leaves its interface disabled about half the time, and the Mac stays unreadable until it re-enters DFU. With a dongle, restorekit now reboots it out of DFU and triggers again, up to twice. This also fixes the KIS identity cache, which kept its first sighting across re-enumeration because Windows reuses the device id.

Tested on Windows 11 ARM64 with Apple Mobile Device Support installed and every RestoreKit driver package removed:

  • A full revive of the M4 mini (KIS DFU via the dongle) ran to Restore Finished, with no UAC prompt and no test signing.
  • In 10 trials of DFU from a fully booted Mac, 5 were readable on the first entry, 4 after one automatic re-entry, and 1 after two.
  • A dummy listener on 27015 stopped the restore up front, naming powershell.exe.
  • setup-driver left the Mac on AppleKIS (still readable) and bound only the dongle.

Classic 05ac:1227 DFU through Apple's driver isn't tested here, because the M4 only enters KIS DFU over the dongle.

CI

MSYS2 has dropped mingw-w64-x86_64-libusb from the MINGW64 repo; only the ucrt64 and clang64 builds remain. The Windows jobs only kept working off the setup action's cached package database. libusb 1.0.30 is now a vendored submodule that build.rs builds on Windows with the rest of the C stack, and the workflows no longer install it. Linux still links the system libusb.

Not fixed here

  • Dongle firmware with the interface GUID isn't released yet. Older dongles work after setup-driver writes the GUID.

Testing

  • Unit tests: cargo test -p restorekit --lib -- kis:: usbmuxd:: driver:: passes on Windows (11 tests).
  • Firmware: builds for Lite and --features pro. Not flashed yet. The host-side setup-driver path is what was verified for the dongle.
  • On the VM:
    • 0.6.2's reboot --dongle fails, and this branch's setup-driver with only the dongle connected binds it with the GUID. After that, reboot and dfu work from Windows.
    • revive --verbose from a non-elevated session ran to Restore Finished on Windows 11 ARM64, with test signing off, no Apple Mobile Device Service, and no RestoreKit package or certificate on the machine. The watcher bound the restore-mode interface to Windows' WinUSB.

fcjr added 10 commits November 16, 2026 23:41
The firmware asked Windows for WinUSB through its MS OS 2.0 descriptors
but never supplied DeviceInterfaceGUIDs, so Windows didn't expose the
vendor interface of the composite device to apps and every dongle command
failed with "Could not find DeviceInterfaceGUIDs in registry". Advertise a
fixed GUID (shared through restorekit-dongle-proto) and pin the vendor
interface number the host relies on.
- Force our WinUSB onto present targets like the restore-mode watcher does.
  Windows Update installs Apple's WHQL applekis.inf for a KIS Mac, which
  outranks our package, so pnputil /install left it bound and restorekit
  couldn't read the Mac.
- Bind the dongle's vendor interface with its interface GUID, for firmware
  that doesn't supply it, and run with only a dongle connected.
- Trust the signing cert through X509Store: Import-Certificate into
  LocalMachine\TrustedPublisher is refused on current Windows 11.
- Fail when pnputil can't stage the package and include its output.
- Point dongle open failures and unreadable KIS Macs at setup-driver.
With Apple's driver installed, DFU and recovery work without setup-driver,
so a restore could reach restore mode with no RestoreKit package staged.
The watcher then had nothing to bind, Apple's driver kept the interface,
and the restore hung at "Waiting for device to enter restore mode" with
libusb failing to open it (error 50). The elevated watcher now stages the
package first and logs what it did, and the restore stops up front when
the watcher can't start (UAC declined) instead of hanging later.

Refs #56
Windows Update installs Apple's drivers for DFU, recovery and KIS, and
libirecovery's Windows backend already talks to them. The two gaps were
restore mode and our own KIS identify.

- Restore mode: when Apple Mobile Device Service (iTunes, Apple Devices)
  is listening on 127.0.0.1:27015 it muxes the restore-mode interface
  through Apple's driver. Use it instead of starting the embedded
  usbmuxd (which would fail to bind that port) and the WinUSB watcher.
- KIS identify: with AppleKIS bound, read the identity through the GET_INFO
  ioctl on its KIS child device, as libirecovery does, instead of WinUSB.
- driver_ready counts Apple's DFU and KIS drivers as ready.

With Apple's service installed, a full restore needs no RestoreKit driver
package, UAC prompt or test signing, which also covers Windows on ARM.
- Only use the usbmuxd port when Apple Mobile Device Service owns it,
  matching the listener's pid against the service's. Any other listener
  (another restorekit restore, say) fails the restore up front by name.
- With a dongle, put a Mac back into DFU (up to twice) when it lands in
  KIS DFU unreadable. AppleKIS leaves the interface disabled about half
  the time when entering DFU from a booted Mac, until it re-enters DFU.
- Forget cached KIS sightings for devices that left the bus. Windows
  reuses the device id, so a re-entry got no arrival grace period.
- setup-driver leaves devices on Apple's drivers alone and counts them as
  set up; moving a KIS Mac off AppleKIS strands it.
- Windows on ARM: stop a restore that has neither Apple's service nor a
  staged package before it starts, and point setup-driver failures there
  at Apple Devices or iTunes.
- Unit tests for the AppleKIS reply and TCP table parsing.
MSYS2 dropped mingw-w64-x86_64-libusb from the MINGW64 repo (only the
ucrt64/clang64 builds remain), so the Windows jobs only kept working off
the setup action's cached package database. Vendor libusb 1.0.30 as a
submodule and build it with the rest of the C stack on Windows, where only
the embedded usbmuxd uses it. Linux still links the system libusb.
libimobiledevice-glue implemented cond_t on Windows as a semaphore. A
signal with no waiter was counted rather than dropped, so after one stray
device event the next "wait for the device to disconnect" returned at once
and idevicerestore failed the restore ("Device did not disconnect"). A wait
also never re-took the mutex, so callers released it twice. Use a
CONDITION_VARIABLE with the CRITICAL_SECTION mutex, which behaves like the
pthreads version these callers are written for.

Also give iBEC 60 seconds to boot in dfu_enter_recovery instead of 10, as
the same step in idevicerestore.c already does.

build.rs now applies patches/<lib>/ to any autotools library that has a
patch directory, not just libirecovery.
setup-driver generated a WinUSB INF, signed its catalog with a
self-signed certificate it added to the machine's trusted roots, and
staged it with pnputil. Windows on ARM refuses such packages outright,
since Code Integrity only loads Microsoft-signed drivers.

Bind the inbox winusb.inf instead: build a driver list from just that INF
with DI_FLAGSEX_ALLOWEXCLUDEDDRVS (its "WinUsb Device" entry matches
USB\MS_COMP_WINUSB, not the Mac, as Device Manager's "Have Disk" route
allows), install it on the one device instance with DiInstallDevice, and
write the mode's DeviceInterfaceGUIDs to the device's registry key the
way the INF's AddReg did. A device already on WinUSB without a GUID (a
dongle on old firmware) just gets the GUID and a restart.

The restore-mode watcher is now a Rust loop doing the same for the
restore-mode interface, and for any DFU, recovery or KIS device left
without a driver. No certificate, catalog, pnputil or PowerShell, and it
works the same on x64 and ARM64, so the ARM-only restore check is gone.
@fcjr
fcjr merged commit 1610608 into main Nov 17, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant