On 12/1/25 22:00, Phil Dennis-Jordan wrote:
From: Alexander Graf <g...@amazon.com>
Apple defines a new "vmapple" machine type as part of its proprietary
macOS Virtualization.Framework vmm. This machine type is similar to the
virt one, but with subtle differences in base devices, a few special
vmapple device additions and a vastly different boot chain.
This patch reimplements this machine type in QEMU. To use it, you
have to have a readily installed version of macOS for VMApple,
run on macOS with -accel hvf, pass the Virtualization.Framework
boot rom (AVPBooter) in via -bios, pass the aux and root volume as pflash
and pass aux and root volume as virtio drives. In addition, you also
need to find the machine UUID and pass that as -M vmapple,uuid= parameter:
$ qemu-system-aarch64 -accel hvf -M vmapple,uuid=0x1234 -m 4G \
-bios
/System/Library/Frameworks/Virtualization.framework/Versions/A/Resources/AVPBooter.vmapple2.bin
-drive file=aux,if=pflash,format=raw \
-drive file=root,if=pflash,format=raw \
-drive file=aux,if=none,id=aux,format=raw \
-device vmapple-virtio-blk-pci,variant=aux,drive=aux \
-drive file=root,if=none,id=root,format=raw \
-device vmapple-virtio-blk-pci,variant=root,drive=root
With all these in place, you should be able to see macOS booting
successfully.
Known issues:
- Currently only macOS 12 guests are supported. The boot process for
13+ will need further investigation and adjustment.
Signed-off-by: Alexander Graf <g...@amazon.com>
Co-authored-by: Phil Dennis-Jordan <p...@philjordan.eu>
Signed-off-by: Phil Dennis-Jordan <p...@philjordan.eu>
Reviewed-by: Akihiko Odaki <akihiko.od...@daynix.com>
---
MAINTAINERS | 1 +
contrib/vmapple/uuid.sh | 9 +
docs/system/arm/vmapple.rst | 63 ++++
docs/system/target-arm.rst | 1 +
hw/vmapple/Kconfig | 20 ++
hw/vmapple/meson.build | 1 +
hw/vmapple/vmapple.c | 618 ++++++++++++++++++++++++++++++++++++
7 files changed, 713 insertions(+)
create mode 100755 contrib/vmapple/uuid.sh
create mode 100644 docs/system/arm/vmapple.rst
create mode 100644 hw/vmapple/vmapple.c
diff --git a/MAINTAINERS b/MAINTAINERS
index e220744abf..3a3d9e19f4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2791,6 +2791,7 @@ M: Phil Dennis-Jordan <p...@philjordan.eu>
S: Maintained
F: hw/vmapple/*
F: include/hw/vmapple/*
+F: docs/system/arm/vmapple.rst
Subsystems
----------
diff --git a/contrib/vmapple/uuid.sh b/contrib/vmapple/uuid.sh
new file mode 100755
index 0000000000..956e8c3afe
--- /dev/null
+++ b/contrib/vmapple/uuid.sh
@@ -0,0 +1,9 @@
+#!/bin/sh
+# Used for converting a guest provisioned using Virtualization.framework
+# for use with the QEMU 'vmapple' aarch64 machine type.
+#
+# Extracts the Machine UUID from Virtualization.framework VM JSON file.
+# (as produced by 'macosvm', passed as command line argument)
+
+plutil -extract machineId raw "$1" | base64 -d | plutil -extract ECID raw -
+
diff --git a/docs/system/arm/vmapple.rst b/docs/system/arm/vmapple.rst
new file mode 100644
index 0000000000..5090a8997c
--- /dev/null
+++ b/docs/system/arm/vmapple.rst
@@ -0,0 +1,63 @@
Alex, Phil, we now mandate a SPDX tag. Due to the license used in
vmapple.c in this patch, are you OK with me squashing here:
-- >8 --
diff --git a/docs/system/arm/vmapple.rst b/docs/system/arm/vmapple.rst
index 5090a8997c3..c5b1bcf45ea 100644
--- a/docs/system/arm/vmapple.rst
+++ b/docs/system/arm/vmapple.rst
@@ -0,0 +1,2 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
diff --git a/contrib/vmapple/uuid.sh b/contrib/vmapple/uuid.sh
index 956e8c3afed..f5637221d23 100755
--- a/contrib/vmapple/uuid.sh
+++ b/contrib/vmapple/uuid.sh
@@ -1,0 +2 @@
+#
@@ -6,0 +8,2 @@
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
---
?
+VMApple machine emulation
+========================================================================================
+
+VMApple is the device model that the macOS built-in hypervisor called
"Virtualization.framework"
+exposes to Apple Silicon macOS guests. The "vmapple" machine model in QEMU
implements the same
+device model, but does not use any code from Virtualization.Framework.
+
+Prerequisites
+-------------
+
+To run the vmapple machine model, you need to
+
+ * Run on Apple Silicon
+ * Run on macOS 12.0 or above
+ * Have an already installed copy of a Virtualization.Framework macOS 12
virtual
+ machine. Note that newer versions than 12.x are currently NOT supported on
+ the guest side. I will assume that you installed it using the
+ `macosvm <https://github.com/s-u/macosvm>` CLI.
+
+First, we need to extract the UUID from the virtual machine that you
installed. You can do this
+by running the shell script in contrib/vmapple/uuid.sh on the macosvm.json
file.
+
+.. code-block:: bash
+ :caption: uuid.sh script to extract the UUID from a macosvm.json file
+
+ $ contrib/vmapple/uuid.sh "path/to/macosvm.json"
+
+Now we also need to trim the aux partition. It contains metadata that we can
just discard:
+
+.. code-block:: bash
+ :caption: Command to trim the aux file
+
+ $ dd if="aux.img" of="aux.img.trimmed" bs=$(( 0x4000 )) skip=1
+
+How to run
+----------
+
+Then, we can launch QEMU with the Virtualization.Framework pre-boot
environment and the readily
+installed target disk images. I recommend to port forward the VM's ssh and vnc
ports to the host
+to get better interactive access into the target system:
+
+.. code-block:: bash
+ :caption: Example execution command line
+
+ $ UUID="$(contrib/vmapple/uuid.sh 'macosvm.json')"
+ $
AVPBOOTER="/System/Library/Frameworks/Virtualization.framework/Resources/AVPBooter.vmapple2.bin"
+ $ AUX="aux.img.trimmed"
+ $ DISK="disk.img"
+ $ qemu-system-aarch64 \
+ -serial mon:stdio \
+ -m 4G \
+ -accel hvf \
+ -M vmapple,uuid="$UUID" \
+ -bios "$AVPBOOTER" \
+ -drive file="$AUX",if=pflash,format=raw \
+ -drive file="$DISK",if=pflash,format=raw \
+ -drive file="$AUX",if=none,id=aux,format=raw \
+ -drive file="$DISK",if=none,id=root,format=raw \
+ -device vmapple-virtio-blk-pci,variant=aux,drive=aux \
+ -device vmapple-virtio-blk-pci,variant=root,drive=root \
+ -netdev
user,id=net0,ipv6=off,hostfwd=tcp::2222-:22,hostfwd=tcp::5901-:5900 \
+ -device virtio-net-pci,netdev=net0
+
