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