What is macvdmtool?

It is a tool from the AsahiLinux project that lets you put an Apple Silicon Mac in DFU mode with a simple set of terminal commands.

Note: macvdmtool requires that you have two Apple silicon machines on hand. One acts as the “host” machine which initiates the “target” machine to perform a restore.

Setting up and using macvdmtool

  1. Install Xcode and the Xcode commandline tools.

  2. Install Apple Configurator 2 from the Mac App Store.

  3. Clone macvdmtool

    git clone https://github.com/AsahiLinux/macvdmtool.git
    
  4. Change into the macvdmtool directory and compile the tool

    ~ % cd macvdmtool && make
    cc -o macvdmtool main.o -framework CoreFoundation -framework IOKit -lc++
    macvdmtool % 
    
  5. (Optional) Copy macvdmtool to somewhere that is in the default path.

    macvdmtool % sudo cp macvdmtool /usr/local/bin
    Password:
    macvdmtool % 
    
  6. Launch Apple Configuration 2 and install the “Automation Tools”.

    Install Automation Tools

    Install Automation Tools dialogue

    Install Automation Tools password prompt

  7. Connect the host and target Macs together via an official Apple USB-C charging cable. The cable must be plugged into the DFU port on both ends.

    • On the M1 Macbook Air, the DFU port is the usb-c port closest to the screen.
    • On the M1 Pro, the DFU port is the usb-c port closest to the Magsafe connector.

    See Mr. Macintosh’s excellent blog post on DFU restores for more information.

  8. Use macvdmtool to put the target mac in serial mode. In my experience, you do not have to wait for the boot process to finish to perform the next step: you can perform it immediately after sudo macvdmtool reboot serial finishes.

    ~ % sudo macvdmtool reboot serial
    Password:
    Mac type: J313AP
    Looking for HPM devices...
    Found: IOService:/AppleARMPE/arm-io@10F00000/AppleT810xIO/i2c0@35010000/AppleS5L8940XI2CController/hpmBusManager@6B/AppleHPMBusController/hpm0/AppleHPMARM
    Connection: Sink
    Status: APP
    Unlocking... OK
    Entering DBMa mode... Status: DBMa
    Rebooting target into normal mode... OK
    Waiting for connection.... Connected
    Putting target into serial mode... OK
    Putting local end into serial mode... OK
    Exiting DBMa mode... OK
    ~ %
    
  9. Put the target mac in DFU mode.

    ~ % sudo macvdmtool dfu
    Mac type: J313AP
    Looking for HPM devices...
    Found: IOService:/AppleARMPE/arm-io@10F00000/AppleT810xIO/i2c0@35010000/AppleS5L8940XI2CController/hpmBusManager@6B/AppleHPMBusController/hpm0/AppleHPMARM
    Connection: Source
    Status: APP
    Unlocking... OK
    Entering DBMa mode... Status: DBMa
    Rebooting target into DFU mode... OK
    Exiting DBMa mode... OK
    ~ %
    
  10. Confirm the device is in DFU mode by launching Apple Configurator 2. It should look like this.

    Apple Configurator 2 is now showing target device in DFU

  11. Grab the IPSW you want to restore from Mr. Macintosh’s database.

  12. Use cfgutil to restore that IPSW.

    ~ % cfgutil restore -I ~/Downloads/UniversalMac_12.1_21C5021h_Restore.ipsw
    objc[53015]: Class AMSupportURLConnectionDelegate is implemented in both /usr/lib/libauthinstall.dylib (0x1da64c9e8) and /Library/Apple/System/Library/PrivateFrameworks/MobileDevice.framework/Versions/A/MobileDevice (0x104d782c8). One of the two will be used. Which one is undefined.
    objc[53015]: Class AMSupportURLSession is implemented in both /usr/lib/libauthinstall.dylib (0x1da64ca38) and /Library/Apple/System/Library/PrivateFrameworks/MobileDevice.framework/Versions/A/MobileDevice (0x104d78318). One of the two will be used. Which one is undefined.
    cfgutil: restore: target OS is 12.1
    
    Waiting for the device [1/2] [*******************************************]  100%
    Step 2 of 2: Installing System [2/2] [**********************************>]  99%
    

At this point you’ll see an Apple logo and a loading bar on the target mac.

After a few minutes, the Mac will reboot and launch the standard Setup Assistant experience.

That’s it! Enjoy.

Future automation enhancements

  • Once Apple adds 12.X IPSWs to the com_apple_macOSIPSW.xml feed, I could write a script to download the latest IPSW and then execute macvdmtool and cfgutil.
  • Autopkg recipe to download latest IPSW and package it with Munki. This could be useful to distribute IPSWs to technicians.

Have a question, clarification, or comment?

File an issue or PR (pull request) against my blog at https://github.com/discentem/blog-content or reach out via MacAdmins Slack.