| 1 | .. SPDX-License-Identifier: GPL-2.0-or-later |
| 2 | |
| 3 | VMApple machine emulation |
| 4 | ======================================================================================== |
| 5 | |
| 6 | VMApple is the device model that the macOS built-in hypervisor called "Virtualization.framework" |
| 7 | exposes to Apple Silicon macOS guests. The "vmapple" machine model in QEMU implements the same |
| 8 | device model, but does not use any code from Virtualization.Framework. |
| 9 | |
| 10 | Prerequisites |
| 11 | ------------- |
| 12 | |
| 13 | To 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 | |
| 22 | First, we need to extract the UUID from the virtual machine that you installed. You can do this |
| 23 | by 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 | |
| 30 | Now 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 | |
| 37 | How to run |
| 38 | ---------- |
| 39 | |
| 40 | Then, we can launch QEMU with the Virtualization.Framework pre-boot environment and the readily |
| 41 | installed target disk images. I recommend to port forward the VM's ssh and vnc ports to the host |
| 42 | to 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 |