I’m using Virtualization.framework on Apple silicon with a Linux guest (VZGenericPlatformConfiguration + VZLinuxBootLoader).
The VM is intentionally minimal:
2 vCPUs, 2 GiB RAM
1 virtio entropy device
2 virtio block devices (base read-only, scratch read-write)
1 virtio console with 2 ports, both isConsole = false
no serial, network, sharing, socket, USB, audio, graphics, keyboard, pointing, balloon, or custom virtio devices
no EFI variable store
nested virtualization disabled
On the normal success path the host does not call requestStop(). A destructive host stop is tracked separately and treated as failure.
I need a supported way for the host to distinguish:
a clean Linux guest shutdown intentionally issued by the guest after its application protocol and cleanup have completed, from
an abnormal or independent shutdown path such as kernel panic, watchdog, thermal / hardware-protection shutdown, emergency shutdown, or another kernel/platform-triggered stop.
guestDidStopVirtualMachine tells me that the guest stopped, but I cannot find a public contract that says which Linux/kernel/platform histories can produce that callback, nor a public shutdown reason/initiator value.
My specific questions are:
For VZGenericPlatformConfiguration + VZLinuxBootLoader, what is the documented complete guest-visible shutdown/reset event surface, including implicit platform events not represented by explicitly configured device arrays?
What Linux-facing mechanism does VZVirtualMachine.requestStop() use in this configuration?
Can guestDidStopVirtualMachine also be emitted after panic, watchdog, thermal/hardware-protection shutdown, emergency shutdown, or another guest-kernel/platform shutdown source?
Are those abnormal cases guaranteed to arrive through virtualMachine(_:didStopWithError:) instead?
If guestDidStopVirtualMachine can represent multiple terminal histories, is there any supported public API or documented guarantee that lets the host distinguish a clean guest system-off from the abnormal/platform-triggered cases?
If not, is it correct to treat this distinction as unspecified by the public Virtualization.framework contract?
I do not need private implementation details. A public/supported contract describing which terminal histories can produce each delegate callback would be enough.
This matters because the host is fail-closed: it must accept PASS only after an application-level success condition and a clean guest shutdown. A successful runtime observation alone is not enough for the qualification.
Environment:
Apple silicon / arm64
macOS 26.6.2 (25G83)
public Virtualization.framework APIs