Repository navigation
Fix Windows driver setup, dongle access, and the restore-mode stall - #58
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.infinstalled 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_00with error 50 through{664BE590-…}, which is the interface GUID from Apple'sAppleUsbMux_Install. So Apple's driver still owned restore mode. The force-bind watcher can end up doing nothing in two ways: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.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-driverused to generate a WinUSB INF, sign its catalog with a self-signed certificate it added to the machine's trusted roots, and stage it withpnputil. 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:DI_FLAGSEX_ALLOWEXCLUDEDDRVS. Its "WinUsb Device" entry matchesUSB\MS_COMP_WINUSB, not the Mac, which is the same thing Device Manager's "Have Disk" route allows.DiInstallDevice.DeviceInterfaceGUIDsto the device's registry key, the way the INF'sAddRegdid.A device already on WinUSB without a GUID, such as a dongle on old firmware, just gets the GUID and a restart.
setup-driverbinds present devices this way. Devices on Apple's own drivers are left alone, because libirecovery talks to those directly.pnputilor PowerShell, and it works the same on x64 and ARM64.Device waits on Windows
cond_twas 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 aCONDITION_VARIABLEwith theCRITICAL_SECTIONmutex, which behaves like the pthreads version these callers are written for.dfu_enter_recoverygave iBEC 10 seconds to boot. It now waits 60, like the same step inidevicerestore.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.
restorekit-dongle-proto, which also pins the vendor interface number. It isn't flashed or released yet.setup-driverbinds 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:127.0.0.1:27015and 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\VID_05AC&PID_0001child device, the same request libirecovery sends.Related changes:
driver_readycounts Apple's DFU and KIS drivers, so the desktop app doesn't ask for "Set up USB access" when they're bound.setup-driverno 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.Tested on Windows 11 ARM64 with Apple Mobile Device Support installed and every RestoreKit driver package removed:
powershell.exe.setup-driverleft the Mac on AppleKIS (still readable) and bound only the dongle.Classic
05ac:1227DFU 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-libusbfrom 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 thatbuild.rsbuilds 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
setup-driverwrites the GUID.Testing
cargo test -p restorekit --lib -- kis:: usbmuxd:: driver::passes on Windows (11 tests).--features pro. Not flashed yet. The host-sidesetup-driverpath is what was verified for the dongle.reboot --donglefails, and this branch'ssetup-driverwith only the dongle connected binds it with the GUID. After that,rebootanddfuwork from Windows.revive --verbosefrom 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.