diff --git a/09-macOS-Host-Support.md b/09-macOS-Host-Support.md new file mode 100644 index 0000000..692c34b --- /dev/null +++ b/09-macOS-Host-Support.md @@ -0,0 +1,193 @@ +# macOS QEMU 3D Acceleration + +This guide covers 3D graphics acceleration for VMs running on macOS hosts. Stock QEMU packages lack OpenGL support on macOS, but acceleration is possible with patched builds. + +## Current State + +**Stock Homebrew and Nixpkgs QEMU on macOS lack OpenGL support.** This is by design - the OpenGL dependencies (libepoxy, virglrenderer) target Linux in these packages. + +The result: software rendering only, which is slower but stable. + +## How 3D Acceleration Works on macOS + +macOS deprecated OpenGL in favour of Metal. To enable GPU acceleration in QEMU: + +1. **ANGLE** translates OpenGL ES calls to Metal +2. **virglrenderer** provides VirGL 3D support to guests +3. **`gl=es`** display option enables this pathway (not `gl=on` or `gl=core`) + +This requires patched QEMU and virglrenderer builds with ANGLE integration. + +## GL Mode Comparison + +| Mode | Backend | Stability | Performance | Notes | +|------|---------|-----------|-------------|-------| +| `gl=off` | Software | Stable | Slow | Default for stock QEMU | +| `gl=core` | Native OpenGL.framework | Unstable | Variable | macOS OpenGL is deprecated | +| `gl=es` | ANGLE/Metal | Stable | Fast | Recommended when available | + +## How to Get GL-Enabled QEMU + +### Option A: Homebrew Tap (Recommended) + +The simplest method using Konstantin Nazarov's maintained tap: + +```bash +brew install knazarov/qemu-virgl/qemu-virgl +``` + +Repository: https://github.com/knazarov/homebrew-qemu-virgl + +### Option B: Build from Source + +Building requires Akihiko Odaki's patched forks. + +**Dependencies:** + +```bash +brew install glib meson pipenv pixman pkg-config spice-protocol +``` + +**Required repositories:** + +- QEMU: https://github.com/akihikodaki/qemu +- virglrenderer: https://github.com/akihikodaki/virglrenderer +- libepoxy (with macOS support) +- ANGLE libraries + +**Configure flags:** + +```bash +./configure \ + --enable-cocoa \ + --enable-opengl \ + --enable-virglrenderer \ + --enable-hvf \ + --target-list=aarch64-softmmu,x86_64-softmmu +``` + +For detailed build instructions, see Odaki's guide: https://gist.github.com/akihikodaki/87df4149e7ca87f18dc56807ec5a1bc5 + +### Option C: UTM + +UTM bundles all patches and ANGLE libraries in a GUI application: + +https://github.com/utmapp/UTM + +Pre-packaged with everything needed for GL acceleration, but provides a GUI rather than CLI. + +## Building a Nix Package with VirGL Support + +Creating a custom Nix overlay for GL-enabled QEMU on macOS requires: + +1. Override `openGLSupport = true` in the QEMU derivation +2. Add macOS-compatible dependencies: + - libepoxy (with macOS/ANGLE support) + - virglrenderer (from Odaki's fork or with his patches) + - ANGLE libraries (libEGL.dylib, libGLESv2.dylib) +3. Apply patches from Odaki's QEMU fork + +**Note:** Upstream QEMU and Nixpkgs do not fully support this configuration. You will need to: + +- Patch virglrenderer for OpenGL ES compatibility +- Ensure ANGLE libraries are available at runtime via `DYLD_LIBRARY_PATH` or installed in the package prefix + +Reference the build scripts in Odaki's repository for patch requirements. + +## Quickemu Support + +[PR #1812](https://github.com/quickemu-project/quickemu/pull/1812) adds automatic GL detection and enablement for macOS hosts. + +**How it works:** + +1. `check_cocoa_gl_es_support()` tests whether QEMU accepts `gl=es`: + ```bash + qemu-system-* -display cocoa,gl=es -M none + ``` +2. Also checks for ANGLE libraries (`libEGL.dylib`) in: + - QEMU's prefix (`/lib/`) + - Homebrew locations (`/opt/homebrew/lib/`, `/usr/local/lib/`) + - `DYLD_LIBRARY_PATH` entries +3. Automatically uses `gl=es` when available +4. Falls back to `gl=off` for stock QEMU builds + +**Display devices used:** + +| Guest Architecture | GL Device | +|--------------------|-----------| +| x86_64 | `virtio-vga-gl` | +| aarch64 | `virtio-gpu-gl-pci` | + +**Diagnostic output:** + +When GL is enabled, quickemu displays: +``` + - Display: COCOA, virtio-vga-gl, GL (es), VirGL (on) @ (1280 x 800) +``` + +When falling back to software rendering: +``` + - Display: COCOA, virtio-vga, GL (off), VirGL (off) @ (1280 x 800) +``` + +## Version Requirements + +| Component | Minimum | Recommended | +|-----------|---------|-------------| +| QEMU | 6.0+ | 8.0+ with Odaki patches | +| macOS | 11.0 (Big Sur) | 13.0+ (Ventura) | +| virglrenderer | 0.9.0+ | Latest from Odaki fork | + +## Troubleshooting + +### "OpenGL support was not enabled in this build of QEMU" + +You are using stock QEMU without GL support. Install a GL-enabled build (see options above). + +### Verifying GL is working + +**From quickemu output:** + +Look for `GL (es)` and `VirGL (on)` in the display status line. + +**Inside the guest:** + +```bash +glxinfo | grep "OpenGL renderer" +``` + +Should show something like: +``` +OpenGL renderer string: virgl (ANGLE (Apple, Apple M2, OpenGL 4.1 Metal - 89.4)) +``` + +### Guest shows software rendering despite GL-enabled QEMU + +1. Verify ANGLE libraries are accessible: + ```bash + ls -la /opt/homebrew/lib/libEGL.dylib # Homebrew location + ``` + +2. Check QEMU accepts `gl=es`: + ```bash + qemu-system-aarch64 -display cocoa,gl=es -M none + ``` + No error output means GL is supported. + +3. Ensure the guest has Mesa with virgl support installed. + +### Performance is poor with GL enabled + +- Verify you are using `gl=es`, not `gl=core` +- Check Activity Monitor for GPU usage - Metal should show activity +- Some guests may need updated Mesa drivers for optimal virgl performance + +## References + +- Akihiko Odaki's Guide: https://gist.github.com/akihikodaki/87df4149e7ca87f18dc56807ec5a1bc5 +- Odaki's QEMU Fork: https://github.com/akihikodaki/qemu +- Odaki's virglrenderer Fork: https://github.com/akihikodaki/virglrenderer +- Homebrew Tap: https://github.com/knazarov/homebrew-qemu-virgl +- UTM Project: https://github.com/utmapp/UTM +- ANGLE Project: https://chromium.googlesource.com/angle/angle +- Quickemu PR #1812: https://github.com/quickemu-project/quickemu/pull/1812 diff --git a/Home.md b/Home.md index 6e0e00d..843622e 100644 --- a/Home.md +++ b/Home.md @@ -10,4 +10,5 @@ This wiki describes how to get up and running with Quickemu and also covers more - [**Advanced quickget features**](https://github.com/quickemu-project/quickemu/wiki/06-Advanced-quickget-features) 🤓 - [**Alternative frontends**](https://github.com/quickemu-project/quickemu/wiki/07-Alternative-frontends) 🧑‍💻 - [**References**](https://github.com/quickemu-project/quickemu/wiki/08-References) 📚️ +- [**macOS Host Support**](https://github.com/quickemu-project/quickemu/wiki/09-macOS-Host-Support) 🍎