1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3VMApple machine emulation 4======================================================================================== 5 6VMApple is the device model that the macOS built-in hypervisor called "Virtualization.framework" 7exposes to Apple Silicon macOS guests. The "vmapple" machine model in QEMU implements the same 8device model, but does not use any code from Virtualization.Framework. 9 10Prerequisites 11------------- 12 13To run the vmapple machine model, you need to 14 15 * Run on Apple Silicon 16 * Run on macOS 12.0 or above 17 * Have an already installed copy of a Virtualization.Framework macOS 12 virtual 18 machine. Note that newer versions than 12.x are currently NOT supported on 19 the guest side. I will assume that you installed it using the 20 `macosvm <https://github.com/s-u/macosvm>`__ CLI. 21 22First, we need to extract the UUID from the virtual machine that you installed. You can do this 23by running the shell script in contrib/vmapple/uuid.sh on the macosvm.json file. 24 25.. code-block:: bash 26 :caption: uuid.sh script to extract the UUID from a macosvm.json file 27 28 $ contrib/vmapple/uuid.sh "path/to/macosvm.json" 29 30Now we also need to trim the aux partition. It contains metadata that we can just discard: 31 32.. code-block:: bash 33 :caption: Command to trim the aux file 34 35 $ dd if="aux.img" of="aux.img.trimmed" bs=$(( 0x4000 )) skip=1 36 37How to run 38---------- 39 40Then, we can launch QEMU with the Virtualization.Framework pre-boot environment and the readily 41installed target disk images. I recommend to port forward the VM's ssh and vnc ports to the host 42to get better interactive access into the target system: 43 44.. code-block:: bash 45 :caption: Example execution command line 46 47 $ UUID="$(contrib/vmapple/uuid.sh 'macosvm.json')" 48 $ AVPBOOTER="/System/Library/Frameworks/Virtualization.framework/Resources/AVPBooter.vmapple2.bin" 49 $ AUX="aux.img.trimmed" 50 $ DISK="disk.img" 51 $ qemu-system-aarch64 \ 52 -serial mon:stdio \ 53 -m 4G \ 54 -accel hvf \ 55 -M vmapple,uuid="$UUID" \ 56 -bios "$AVPBOOTER" \ 57 -drive file="$AUX",if=pflash,format=raw \ 58 -drive file="$DISK",if=pflash,format=raw \ 59 -drive file="$AUX",if=none,id=aux,format=raw \ 60 -drive file="$DISK",if=none,id=root,format=raw \ 61 -device vmapple-virtio-blk-pci,variant=aux,drive=aux \ 62 -device vmapple-virtio-blk-pci,variant=root,drive=root \ 63 -netdev user,id=net0,ipv6=off,hostfwd=tcp::2222-:22,hostfwd=tcp::5901-:5900 \ 64 -device virtio-net-pci,netdev=net0 65 66