Repository navigation
Detect and restore Macs in DFU over Debug USB (KIS, 05ac:1881) - #53
Conversation
Newer Macs (M5 and up) can come up in DFU over Apple's Debug USB
interface ("KIS") instead of the classic 05ac:1227. restorekit didn't
know that PID, so after a successful trigger it never saw the target
and re-sent the VDM, which then failed with "no target detected".
- Recognize 05ac:1881 as UsbMode::Kis, which counts as DFU.
- Read the CPID/ECID identity over KIS (port of libirecovery's
GET_INFO request) since the device has no USB serial.
- Treat a KIS arrival as "entered" in the DFU watch and trigger wait.
- When the identity can't be read (always on macOS, which gates the
interface behind a private entitlement), stop with a clear error
instead of re-triggering.
- Show the mode in the CLI and desktop app; add 1881 to the udev rule.
Refs #51
Diagnostic for poking at what a USB-C partner supports, e.g. the Apple action list (0x05ac8010) and action info (0x05ac8011) queries. Prints the reply register.
macOS only lets processes with com.apple.private.debug-usb.access open a 05ac:1881 Debug USB device, and only Apple's deviceinterfaced has it. The daemon does hand out a raw KIS transport to any client through the private DeviceInterfaceClient.framework, so go through that: - Patch libirecovery so that on macOS a KIS device is opened via deviceinterfaced and its KIS requests (GET_INFO, image upload, boot) go through transfer_data. Device-add events for KIS devices no longer get dropped when the IOKit plug-in can't be created. The framework is loaded at runtime; without it everything falls back to plain IOKit. Set IRECV_KIS_NO_DIC to force the old path. - build.rs now applies patches/libirecovery/ to a copy of the vendored sources, like idevicerestore, and rebuilds only when they change. - Read the identity through the same transport in restorekit, so a KIS Mac shows up as restorable on macOS. - Add a hidden `restorekit kis-probe` that dumps what deviceinterfaced reports, the raw GET_INFO reply and what it parses to. Checked against an iPhone with Debug USB turned on (listing, portal mapping, a GET_INFO round trip). Not yet tried on a Mac in DFU.
- libirecovery's check_context treats a client without a USB handle as gone, so set_configuration failed before reaching the KIS shortcut. Let deviceinterfaced clients through, and guard the IOKit helpers that use the handle instead of their public wrappers. - deviceinterfaced's ids are the registry entry ids of the device's IOUSBHostInterface, not the device. Match on the interface's parent in restorekit too (libirecovery already checked children), and show the mapping in kis-probe.
A device can answer GET_INFO with no info block: the port is in Debug USB but the chip behind it isn't in DFU (a booted device with Debug USB switched on over USB-PD). That isn't a restore mode, so list it as an other-mode device with its own hint instead of "couldn't read its identity". Only a good identity is cached now. Anything else is asked again, and a failed read is retried for a few seconds after the device first shows up, since on macOS deviceinterfaced attaches on that same arrival and the first request can beat it.
libirecovery's Windows KIS code only knows Apple's AppleKIS driver, which frames KIS itself behind its own ioctls and enumerates as kis#vid_05ac&pid_0001. restorekit binds plain WinUSB to 05ac:1881, so a KIS Mac was never found. Patch libirecovery so a WinUSB-bound KIS interface is opened with WinUsb_Initialize and spoken to with raw KIS requests on its bulk pipes, the same ones the libusb and IOKit backends send: enable, GET_INFO, chunked upload and boot. Covers both the open path and device-add events. Link winusb on Windows. Also skip symlinks when copying libirecovery for patching: autogen on macOS links its aux files into Homebrew, which breaks the copy on any other machine.
|
Tried this on Windows 11 with my M4 Max MacBook Pro (Mac16,5, j616cap) and Detection is fine. The restore isn't. If I start from Port DFU, the Ace3 upload goes through and the device disconnects, and then: If I run If I start with the Mac already in KIS, it sits at "detecting device" and then gives up: The desktop app does the same thing. I dug into it and both come from the same place. On Windows libirecovery uses its SetupAPI backend, and there are three spots that check whether a device on the KIS interface GUID is one it wants: idevicerestore only finds out what mode the device is in from those events. So starting in KIS it waits 10 seconds for a mode and times out, and after Port DFU it waits 20 seconds for a DFU arrival that never comes. I first thought it was an ECID mismatch, since the Port DFU "ECID" is the port controller's and not the SoC's. It isn't: idevicerestore already clears its ECID when a Port DFU device disconnects and takes whatever shows up next. It's also not libusb, libirecovery doesn't use it on Windows. The "libusb does not support hotplug events" line is from the embedded usbmuxd. Once I got the poller to accept pid_1881 locally, a non-erasing revive ran all the way through (Restore Finished, about 4m20s). The Port DFU to KIS reconnect is picked up as DFU mode, iBSS and everything after it uploads over the WinUSB KIS path, and the Mac gets into restore mode and runs the firmware updaters. So the rest of the WinUSB KIS code works on real hardware. Two things I noticed in that run. One checkpoint failed but didn't stop the restore: The Mac asked for the AppleTCON updater data twice, a Baobab ticket was fetched and sent both times, and it still reported that. I'm getting more logging on it. The other is |
The SetupAPI poller in _irecv_event_handler still only accepted pid 1 on the KIS interface GUID, so a WinUSB-bound 05ac:1881 never produced a device-add event. idevicerestore reads the device mode from those events, so a restore started in KIS timed out discovering the mode, and one started in Port DFU never saw the Mac come back after the Ace3 upload.
|
@freddy-fazbear-real thanks really appreciate the writeup! you're totally right, I've missed the polling on windows. I added it in if you happen to have a chance to retest i'd really appreciate it! |
|
@fcjr I haven't been able to test starting directly from KIS, unfortunately, but it does appear to work after being put in KIS during the process. One other thing I ran into, separate from this PR. The AppleTCON updater fails on this Mac: Checkpoint FAILURE id: 0x1332 result=-1: _update_generic_firmware: failed to copy response for AppleTCON The restore still finishes, so it’s easy to miss. From logging the exchange: the Mac’s FirmwareUpdaterData request for AppleTCON has no DeviceGeneratedTags/ResponseTags at all. It only has MessageArgInfo, MessageArgUpdaterLoopCount, MessageForceRepersonalization and DataChunkSize. Since idevicerestore commit 3faf292 (“Only send FirmwareData when it has been requested”), restore_get_tcon_firmware_data only attaches the firmware when ResponseTags lists FirmwareData, so here it replies with just the Baobab ticket and the updater gives up. I tried treating a request with no ResponseTags as wanting the firmware, like it did before that commit. With that it extracts Firmware/DP855/X3091/X3091.bin, sends 1417226 bytes, and the step passes (await_update_appletcon result=0). Tested on 27.2.1 (26B131), two revives. Unfortunately, this didn't fix the whole issue I was trying to fix by reviving anyways, but figured I would share haha. |
Both or either would be extremely appreciated. Thank you so much for all your help. I'm sorry for restore didn't help fix your issues! |
|
Here’s the patch and logs for the AppleTCON thing. @fcjr 0008 only adds logging, it dumps the AppleTCON request from the Mac and what we send back. These are excerpts, not full logs, and I redacted the ECID and the ticket. The full logs have the serial and other device stuff in them, but I can send a cleaned up one if you need more context. 0008-log-appletcon-updater-exchange.patch |
On macOS the identity read fails when another app (seen with Chrome) has the 05ac:1881 device open, since deviceinterfaced only attaches on arrival. Say that instead of sending people to Apple Configurator, and give the desktop app the same hint instead of the manual DFU steps.
M3 and newer Macs put into DFU with the USB-PD trigger come up as Debug USB (
05ac:1881, "KIS") instead of classic DFU. The main chip is in DFU but the USB-C port isn't, so the port controller serves the Debug USB interface (Siguza and others confirmed this in libirecovery#123: the key combo gives Port DFU, the VDM gives KIS). restorekit didn't know that PID, so after a successful trigger it never saw the target, re-sent the VDM, and failed with "no target detected on the DFU port". That's #51.This makes a KIS Mac detectable and restorable on all three platforms. Restores are tested on real M4 Macs from macOS and Windows; Linux hasn't been tried on hardware yet.
Detection (all platforms)
05ac:1881is now a DFU mode (UsbMode::Kis, shown askis).deviceinterfaced(below).deviceinterfacedattaches on that same arrival.Restore
The vendored libirecovery gets two patches (
crates/restorekit-sys/patches/libirecovery/).build.rsnow applies them to a copy of the tree, the same way idevicerestore is patched, and only rebuilds when they change.05ac:1881is gated behindcom.apple.private.debug-usb.access(DeviceInterface-IOUSBHostFamily.kext), and only Apple'sdeviceinterfacedhas it. The daemon does hand out a raw KIS transport to any client through the privateDeviceInterfaceClient.framework, with no peer checks. Patch 0001 opens KIS devices through it and sends every KIS request (GET_INFO, image upload, boot) with itstransfer_data. It also stops libirecovery dropping the device-add event for a device it can't open. Loaded at runtime, falls back to plain IOKit,IRECV_KIS_NO_DIC=1forces that.WinUsb_Initializeand sends the same raw KIS requests on its bulk pipes. The AppleKIS path is untouched.Tested so far
restorekit vdm 0x05ac8012 0x00824606), on macOS:deviceinterfacedlists the 1881 device to an unentitled, non-root client, its ids are the registry ids of the device'sIOUSBHostInterface, and a GET_INFO round-trips through both restorekit and the patched libirecovery. The reply is empty because the phone isn't in DFU (it has no DFU action at all, its action list is in the commit history), so this checks the transport, not what a DFU Mac sends back.dfureports DFU over Debug USB with the ECID,kis-probereturns the full GET_INFO, a non-erasingreviveran to Restore Finished in about 5 minutes, and an erasingrestorestarted from a booted Mac (dongle trigger, KIS, iBSS, recovery, iBEC, restore mode) ran to Restore Finished in 13.5 minutes with no checkpoint failures. The one snag was the identity read failing while Chrome had the 1881 device open. It only worked after quitting Chrome and re-entering DFU, becausedeviceinterfacedonly attaches when the device shows up. The macOS error now says that instead of pointing at Apple Configurator.Diagnostics
restorekit kis-probe(hidden) dumps whatdeviceinterfacedsees, the raw GET_INFO reply and what it parses to.restorekit vdm <words...>(hidden) sends one raw VDM and prints the reply.To test on an M3+ Mac
restorekit dfushould report DFU and an ECID.restorekit kis-probeshould show aCPID:… ECID:…serial andNONC:… SNON:…nonces.restorekit restoreshould upload iBSS/iBEC over KIS and come back in recovery (0x1281), then carry on as usual.On Windows, run
restorekit setup-driverfirst so WinUSB is bound to 1881.Refs #51