Skip to content

Detect and restore Macs in DFU over Debug USB (KIS, 05ac:1881) - #53

Merged
fcjr merged 11 commits into
mainfrom
kis-dfu-detect
Nov 17, 2026
Merged

fcjr merged 11 commits into
mainfrom
kis-dfu-detect

Conversation

@fcjr

@fcjr fcjr commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

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:1881 is now a DFU mode (UsbMode::Kis, shown as kis).
  • The CPID/ECID identity comes from a KIS GET_INFO request since the device has no USB serial. Linux and Windows send it over nusb; macOS goes through deviceinterfaced (below).
  • The DFU watch and trigger wait treat a 1881 arrival as "entered", so we stop re-firing the trigger at a Mac that's already in DFU.
  • A Debug USB device that answers with no info block isn't in DFU (e.g. a booted device with Debug USB switched on), so it's listed as other mode with its own hint.
  • If the identity really can't be read, the CLI and desktop app stop with a per-OS message instead of looping. A failed read is retried for a few seconds after the device shows up, since on macOS deviceinterfaced attaches on that same arrival.

Restore

The vendored libirecovery gets two patches (crates/restorekit-sys/patches/libirecovery/). build.rs now applies them to a copy of the tree, the same way idevicerestore is patched, and only rebuilds when they change.

  • Linux: upstream libirecovery already speaks KIS over libusb. Nothing extra needed beyond the udev rule for 1881.
  • macOS: 05ac:1881 is gated behind com.apple.private.debug-usb.access (DeviceInterface-IOUSBHostFamily.kext), and only Apple's deviceinterfaced has it. The daemon does hand out a raw KIS transport to any client through the private DeviceInterfaceClient.framework, with no peer checks. Patch 0001 opens KIS devices through it and sends every KIS request (GET_INFO, image upload, boot) with its transfer_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=1 forces that.
  • Windows: upstream's Windows KIS code only knows Apple's AppleKIS driver, which does the framing itself behind its own ioctls. We bind plain WinUSB to 1881, so the device was never found. Patch 0002 opens a WinUSB-bound KIS interface with WinUsb_Initialize and sends the same raw KIS requests on its bulk pipes. The AppleKIS path is untouched.

Tested so far

  • Against an iPhone 17 Pro with Debug USB switched on over USB-PD (restorekit vdm 0x05ac8012 0x00824606), on macOS: deviceinterfaced lists the 1881 device to an unentitled, non-root client, its ids are the registry ids of the device's IOUSBHostInterface, 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.
  • Unit tests for the KIS header, descriptor parsing and reply classification. clippy clean.
  • On macOS against an M4 Mac mini (Mac16,10) through a Dongle-Lite: dfu reports DFU over Debug USB with the ECID, kis-probe returns the full GET_INFO, a non-erasing revive ran to Restore Finished in about 5 minutes, and an erasing restore started 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, because deviceinterfaced only attaches when the device shows up. The macOS error now says that instead of pointing at Apple Configurator.
  • On Windows 11 against an M4 Max MacBook Pro (Mac16,5), tested by a contributor: a non-erasing revive ran to Restore Finished, through Port DFU, the reconnect as KIS, iBSS/iBEC over the WinUSB KIS path and the firmware updaters. It needed the hotplug poller to accept pid 1881 too, which is now in patch 0002.

Diagnostics

  • restorekit kis-probe (hidden) dumps what deviceinterfaced sees, 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

  1. restorekit dfu should report DFU and an ECID.
  2. restorekit kis-probe should show a CPID:… ECID:… serial and NONC:… SNON:… nonces.
  3. restorekit restore should upload iBSS/iBEC over KIS and come back in recovery (0x1281), then carry on as usual.

On Windows, run restorekit setup-driver first so WinUSB is bound to 1881.

Refs #51

fcjr added 7 commits November 14, 2026 08:46
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.
@fcjr fcjr changed the title Detect Macs in DFU over Debug USB (05ac:1881) Detect and restore Macs in DFU over Debug USB (KIS, 05ac:1881) Nov 14, 2026
@freddy-fazbear-real

Copy link
Copy Markdown

Tried this on Windows 11 with my M4 Max MacBook Pro (Mac16,5, j616cap) and revive doesn't get anywhere once the Mac is in KIS. Built from this branch under MSYS2 MINGW64 (gnu toolchain), WinUSB bound with setup-driver, IPSW is UniversalMac_27.2.1_26B131.

Detection is fine. restorekit list shows the Mac in port-dfu (05ac:f014) and in kis (05ac:1881) with CPID, BDID, ECID and the iBoot version.

The restore isn't. If I start from Port DFU, the Ace3 upload goes through and the device disconnects, and then:

Waiting for device to reconnect in DFU mode...
Device did not reconnect in DFU mode. Port DFU failed.
error: restore failed (exit -2)

If I run restorekit list in another terminal while it's waiting, the Mac is already back as 05ac:1881 in kis mode, so it did reconnect, the restore just never notices.

If I start with the Mac already in KIS, it sits at "detecting device" and then gives up:

Unable to discover device mode. Please make sure a device is attached.
error: restore failed (exit -1)

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: win32_open_with_ecid, _irecv_handle_device_add, and the polling loop in _irecv_event_handler. The 0002 patch teaches the first two about pid_1881 (WinUSB bound straight to the device, as opposed to AppleKIS's pid_0001), but the polling loop still has the upstream check that only lets pid 1 through. So the 1881 device gets skipped on every poll and no device-add event ever fires for it.

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:

Checkpoint FAILURE id: 0x1332 result=-1: _update_generic_firmware: failed to copy response for AppleTCON

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 handleConnectResult new session to port 5097 failed: 61 repeating once a second through the whole restore-mode phase. Didn't seem to break anything.

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.
@fcjr

fcjr commented Nov 15, 2026

Copy link
Copy Markdown
Owner Author

@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!

@freddy-fazbear-real

freddy-fazbear-real commented Nov 15, 2026 •

Copy link
Copy Markdown

@fcjr
Retested, thanks. Your commit is the same change I’d made locally, and I’ve done four revives on a Mac16,5 (M4 Max 16") with it on Windows 11. Starting from Port DFU it reconnects as 1881 every time and the restore runs to “Restore Finished”.

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.
No idea if other Macs send the request the same way, I only have this one. Happy to share the patch or logs.

@fcjr

fcjr commented Nov 15, 2026

Copy link
Copy Markdown
Owner Author

Happy to share the patch or logs.

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!

@freddy-fazbear-real

freddy-fazbear-real commented Nov 16, 2026 •

Copy link
Copy Markdown

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.
0009 is the actual change. If the request has no ResponseTags at all, it sends the firmware anyway instead of only the ticket. If ResponseTags is there it behaves like before.
appletcon-before-ticket-only.log is that step with just the logging patch. The Mac asks twice, gets the ticket with no firmware both times, then fails checkpoint 0x1332.
appletcon-after-firmware-sent.log is the same step with 0009. It sends X3091.bin and the checkpoint passes.

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
0009-send-appletcon-firmware-without-response-tags.patch
appletcon-after-firmware-sent.log
appletcon-before-ticket-only.log

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.
@fcjr
fcjr merged commit 405d436 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.

2 participants