From f3f7bf228aad61b14bfe3b58e3bc47b9dec0764e Mon Sep 17 00:00:00 2001 From: Giova Date: Tue, 10 Nov 2026 23:39:57 -0800 Subject: [PATCH] usb(macOS): unmount a drive's volumes before connecting it to a VM Connecting a USB drive to a QEMU virtual machine takes the device away from macOS at once. A volume that was still mounted went away with it, as if the drive had been unplugged: macOS never got to unmount it, and for a volume that can be written to it warns that the disk was not ejected properly. Ask macOS to unmount the volumes of the device first, and connect it only when that worked. If a volume is in use, the device is left with macOS and the user is told which volume it is. UTM is not allowed to mount a volume again, so whether the device can be connected at all is checked before anything is unmounted. The idea and a first version are from giovariot in #7928. This version finds the device by vendor, product, bus, port and serial number, names the volume and not its device node in the message, and has no timeout of its own, since DiskArbitration always answers. Resolves #5650 Assisted-by: OpenCode:deepseek-v4.1-flash Assisted-by: Claude:claude-fable-5-2 --- .../VMDisplayQemuDisplayController.swift | 6 +- Scripting/UTMScriptingUSBDeviceImpl.swift | 2 +- Services/UTMUSBDeviceUnmount.swift | 206 ++++++++++++++++++ UTM.xcodeproj/project.pbxproj | 4 + 4 files changed, 214 insertions(+), 4 deletions(-) create mode 100644 Services/UTMUSBDeviceUnmount.swift diff --git a/Platform/macOS/Display/VMDisplayQemuDisplayController.swift b/Platform/macOS/Display/VMDisplayQemuDisplayController.swift index 8bfc42b063..1cf2b412ea 100644 --- a/Platform/macOS/Display/VMDisplayQemuDisplayController.swift +++ b/Platform/macOS/Display/VMDisplayQemuDisplayController.swift @@ -366,7 +366,7 @@ extension VMDisplayQemuWindowController: CSUSBManagerDelegate { } Task.detached { do { - try await usbManager.connectUsbDevice(usbDevice) + try await usbManager.connectUsbDeviceAfterUnmounting(usbDevice) await MainActor.run { self.connectedUsbDevices.append(usbDevice) } @@ -464,7 +464,7 @@ extension VMDisplayQemuWindowController { let device = allUsbDevices[menu.tag] Task.detached { self.withErrorAlert { - try await usbManager.connectUsbDevice(device) + try await usbManager.connectUsbDeviceAfterUnmounting(device) await MainActor.run { self.primaryDisplayController.connectedUsbDevices.append(device) } @@ -517,7 +517,7 @@ extension VMDisplayQemuWindowController { let filtered = devices.filter({ self.isAutoConnect($0) }) for device in filtered { self.withErrorAlert { - try await usbManager.connectUsbDevice(device) + try await usbManager.connectUsbDeviceAfterUnmounting(device) await MainActor.run { self.connectedUsbDevices.append(device) } diff --git a/Scripting/UTMScriptingUSBDeviceImpl.swift b/Scripting/UTMScriptingUSBDeviceImpl.swift index bf06a04b6c..57357d2015 100644 --- a/Scripting/UTMScriptingUSBDeviceImpl.swift +++ b/Scripting/UTMScriptingUSBDeviceImpl.swift @@ -136,7 +136,7 @@ class UTMScriptingUSBDeviceImpl: NSObject, UTMScriptable { guard let usbDevice = same(usbDevice: box, for: usbManager) else { throw ScriptingError.deviceNotFound } - try await usbManager.connectUsbDevice(usbDevice) + try await usbManager.connectUsbDeviceAfterUnmounting(usbDevice) } else if #available(macOS 27, *), let vm = scriptingVM?.vm as? UTMAppleVirtualMachine { guard vm.hasUsbRedirection else { throw UTMScriptingVirtualMachineImpl.ScriptingError.operationNotAvailable diff --git a/Services/UTMUSBDeviceUnmount.swift b/Services/UTMUSBDeviceUnmount.swift new file mode 100644 index 0000000000..20aef9dce5 --- /dev/null +++ b/Services/UTMUSBDeviceUnmount.swift @@ -0,0 +1,206 @@ +// +// Copyright © 2026 Turing Software, LLC. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import CocoaSpice +import DiskArbitration +import Foundation +import IOKit + +extension CSUSBManager { + /// Connect a host USB device to the guest after macOS has let go of its volumes + /// + /// Capturing a drive takes it away from macOS at once. A volume that is still mounted is + /// lost as if the drive was unplugged, so the volumes are unmounted first and the device + /// is left alone when macOS refuses because one is in use. + /// - Parameter device: USB device to connect + func connectUsbDeviceAfterUnmounting(_ device: CSUSBDevice) async throws { + // UTM is not allowed to mount a volume again, so find out first if the connect can work + var reason: NSString? + guard canRedirectUsbDevice(device, errorMessage: &reason) else { + throw UTMUSBDeviceUnmountError.cannotConnect(reason as String?) + } + try await device.unmountVolumes() + try await connectUsbDevice(device) + } +} + +private extension CSUSBDevice { + /// Unmount every volume macOS has mounted from this device + /// + /// Does nothing for a device that has no mounted volume. + func unmountVolumes() async throws { + guard let session = DASessionCreate(kCFAllocatorDefault) else { + return + } + DASessionSetDispatchQueue(session, DispatchQueue.global(qos: .userInitiated)) + defer { + DASessionSetDispatchQueue(session, nil) + } + for bsdName in mediaNames { + guard let disk = DADiskCreateFromBSDName(kCFAllocatorDefault, session, bsdName), + let description = DADiskCopyDescription(disk) as NSDictionary?, + description[kDADiskDescriptionVolumePathKey] != nil else { + continue + } + let volumeName = description[kDADiskDescriptionVolumeNameKey] as? String ?? bsdName + try await unmount(disk, named: volumeName) + } + } + + private func unmount(_ disk: DADisk, named volumeName: String) async throws { + try await withCheckedThrowingContinuation { (continuation: CheckedContinuation) in + let request = UnmountRequest(continuation: continuation, volumeName: volumeName) + DADiskUnmount(disk, DADiskUnmountOptions(kDADiskUnmountOptionDefault), { _, dissenter, context in + let request = Unmanaged.fromOpaque(context!).takeRetainedValue() + guard let dissenter = dissenter, DADissenterGetStatus(dissenter) != kDAReturnNotMounted else { + request.continuation.resume() + return + } + let status = DADissenterGetStatus(dissenter) + let reason = DADissenterGetStatusString(dissenter) as String? + logger.debug("cannot unmount '\(request.volumeName)': \(String(status, radix: 16)) \(reason ?? "")") + if status == kDAReturnBusy || status == kDAReturnExclusiveAccess { + request.continuation.resume(throwing: UTMUSBDeviceUnmountError.volumeInUse(request.volumeName)) + } else { + request.continuation.resume(throwing: UTMUSBDeviceUnmountError.unmountFailed(request.volumeName)) + } + }, Unmanaged.passRetained(request).toOpaque()) + } + } + + /// BSD names of the disks and partitions macOS has created for this device + private var mediaNames: [String] { + guard let service = service else { + return [] + } + defer { + IOObjectRelease(service) + } + var iterator: io_iterator_t = 0 + guard IORegistryEntryCreateIterator(service, kIOServicePlane, IOOptionBits(kIORegistryIterateRecursively), &iterator) == KERN_SUCCESS else { + return [] + } + defer { + IOObjectRelease(iterator) + } + var names: [String] = [] + while case let entry = IOIteratorNext(iterator), entry != IO_OBJECT_NULL { + if IOObjectConformsTo(entry, "IOMedia") != 0, let name = Self.property(kIOBSDNameKey, of: entry) as? String { + names.append(name) + } + IOObjectRelease(entry) + } + return names + } + + /// IORegistry entry of this device, which the caller releases + /// + /// Devices of the same model are told apart by the bus and port they are on and then by + /// their serial number. If that still leaves more than one, none is returned. + private var service: io_service_t? { + let matching = IOServiceMatching("IOUSBHostDevice") as NSMutableDictionary + matching["idVendor"] = usbVendorId + matching["idProduct"] = usbProductId + var iterator: io_iterator_t = 0 + guard IOServiceGetMatchingServices(kIOMainPortDefault, matching, &iterator) == KERN_SUCCESS else { + return nil + } + defer { + IOObjectRelease(iterator) + } + var found: [io_service_t] = [] + while case let entry = IOIteratorNext(iterator), entry != IO_OBJECT_NULL { + found.append(entry) + } + func keep(_ isThisDevice: (io_service_t) -> Bool) { + guard found.count > 1 else { + return + } + var kept: [io_service_t] = [] + for entry in found { + if isThisDevice(entry) { + kept.append(entry) + } else { + IOObjectRelease(entry) + } + } + found = kept + } + keep { entry in + Self.location(of: entry) >> 24 == UInt32(truncatingIfNeeded: usbBusNumber) + } + keep { entry in + Self.portNumber(fromLocation: Self.location(of: entry)) == usbPortNumber + } + if let serial = usbSerial, !serial.isEmpty { + keep { entry in + (Self.property("USB Serial Number", of: entry) as? String)?.hasPrefix(serial) ?? false + } + } + guard found.count == 1 else { + found.forEach { IOObjectRelease($0) } + return nil + } + return found[0] + } + + private static func location(of entry: io_registry_entry_t) -> UInt32 { + (property("locationID", of: entry) as? NSNumber)?.uint32Value ?? 0 + } + + /// The location ID has the bus in its top byte and then one port per hub level, 4 bits each + private static func portNumber(fromLocation location: UInt32) -> Int { + var ports = location & 0x00ffffff + while ports != 0 && ports & 0xf == 0 { + ports >>= 4 + } + return Int(ports & 0xf) + } + + private static func property(_ name: String, of entry: io_registry_entry_t) -> Any? { + IORegistryEntryCreateCFProperty(entry, name as CFString, kCFAllocatorDefault, 0)?.takeRetainedValue() + } +} + +/// What the DiskArbitration callback, which cannot capture anything, needs to answer +private final class UnmountRequest { + let continuation: CheckedContinuation + let volumeName: String + + init(continuation: CheckedContinuation, volumeName: String) { + self.continuation = continuation + self.volumeName = volumeName + } +} + +enum UTMUSBDeviceUnmountError: LocalizedError { + case cannotConnect(String?) + case volumeInUse(String) + case unmountFailed(String) + + var errorDescription: String? { + switch self { + case .cannotConnect(let reason): + return reason ?? NSLocalizedString("This USB device cannot be connected to the virtual machine.", comment: "UTMUSBDeviceUnmount") + case .volumeInUse(let volumeName): + let format = NSLocalizedString("'%@' could not be ejected because it is in use. Close anything that is using it and try again.", comment: "UTMUSBDeviceUnmount") + return String.localizedStringWithFormat(format, volumeName) + case .unmountFailed(let volumeName): + let format = NSLocalizedString("'%@' could not be ejected. Eject it in the Finder and try again.", comment: "UTMUSBDeviceUnmount") + return String.localizedStringWithFormat(format, volumeName) + } + } +} diff --git a/UTM.xcodeproj/project.pbxproj b/UTM.xcodeproj/project.pbxproj index d3ee63d980..c6abd931dd 100644 --- a/UTM.xcodeproj/project.pbxproj +++ b/UTM.xcodeproj/project.pbxproj @@ -701,6 +701,7 @@ CE65BABF26A4D8DD0001BD6B /* VMConfigDisplayConsoleView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8401FDA5269D44E400265F0D /* VMConfigDisplayConsoleView.swift */; }; CE65BAC026A4D8DE0001BD6B /* VMConfigDisplayConsoleView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8401FDA5269D44E400265F0D /* VMConfigDisplayConsoleView.swift */; }; CE6804802E493D71001671E9 /* UTMUSBManager.swift in Sources */ = {isa = PBXBuildFile; fileRef = CE68047D2E493D71001671E9 /* UTMUSBManager.swift */; }; + 83EEE570616BAC210F7FDFA5 /* UTMUSBDeviceUnmount.swift in Sources */ = {isa = PBXBuildFile; fileRef = 468649F8E4C55D7A49FB9139 /* UTMUSBDeviceUnmount.swift */; }; CE6804852E4E5D84001671E9 /* UTMScriptingInputImpl.swift in Sources */ = {isa = PBXBuildFile; fileRef = CE6804842E4E5D84001671E9 /* UTMScriptingInputImpl.swift */; }; CE68E5442E3912E0006B3645 /* VMKeyboardShortcutsView.swift in Sources */ = {isa = PBXBuildFile; fileRef = CE68E5422E3912E0006B3645 /* VMKeyboardShortcutsView.swift */; }; CE68E5452E3912E0006B3645 /* VMKeyboardShortcutsView.swift in Sources */ = {isa = PBXBuildFile; fileRef = CE68E5422E3912E0006B3645 /* VMKeyboardShortcutsView.swift */; }; @@ -2254,6 +2255,7 @@ CE63B0F02F0ED67700C59D13 /* vulkan */ = {isa = PBXFileReference; lastKnownFileType = text.json; name = vulkan; path = "$(SYSROOT_DIR)/share/vulkan"; sourceTree = ""; }; CE66450C2269313200B0849A /* MetalKit.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = MetalKit.framework; path = System/Library/Frameworks/MetalKit.framework; sourceTree = SDKROOT; }; CE68047D2E493D71001671E9 /* UTMUSBManager.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = UTMUSBManager.swift; sourceTree = ""; }; + 468649F8E4C55D7A49FB9139 /* UTMUSBDeviceUnmount.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = UTMUSBDeviceUnmount.swift; sourceTree = ""; }; CE6804842E4E5D84001671E9 /* UTMScriptingInputImpl.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = UTMScriptingInputImpl.swift; sourceTree = ""; }; CE68E5422E3912E0006B3645 /* VMKeyboardShortcutsView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VMKeyboardShortcutsView.swift; sourceTree = ""; }; CE68E5472E3C3E0A006B3645 /* VMWizardOSClassicMacView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VMWizardOSClassicMacView.swift; sourceTree = ""; }; @@ -3391,6 +3393,7 @@ E2D64BE0241EAEBE0034E0C6 /* UTMSpiceIODelegate.h */, 845F95E22A57628400A016D7 /* UTMSWTPM.swift */, CE68047D2E493D71001671E9 /* UTMUSBManager.swift */, + 468649F8E4C55D7A49FB9139 /* UTMUSBDeviceUnmount.swift */, CE7A1C012EFA0A01001671E9 /* UTMAppleUSBDevice.swift */, CE7A1C032EFA0A01001671E9 /* UTMAppleUSBManager.swift */, CE1D15AA2F6B100100D15C01 /* UTMAppleDiskImage.swift */, @@ -4983,6 +4986,7 @@ 848A98B4286A1215006F0550 /* UTMAppleConfigurationVirtualization.swift in Sources */, 843BF842284555E70029D60D /* UTMQemuConfigurationPortForward.swift in Sources */, CE6804802E493D71001671E9 /* UTMUSBManager.swift in Sources */, + 83EEE570616BAC210F7FDFA5 /* UTMUSBDeviceUnmount.swift in Sources */, CE7A1C022EFA0A01001671E9 /* UTMAppleUSBDevice.swift in Sources */, CE7A1C042EFA0A01001671E9 /* UTMAppleUSBManager.swift in Sources */, CE1D15AB2F6B100100D15C01 /* UTMAppleDiskImage.swift in Sources */,