docs(quickemu): clarify CPU, display and VM comments
- Clarify highmem behaviour for aarch64 virt machine and why it is needed for >3GB RAM - Add detailed explanation of TCG (software emulation), how to force it, and common use cases - Replace TODOs about VM detection with manufacturer-based detection guidance - Improve ARM detection rationale (no standard vendor strings) - Explain that TCG enables running x86_64 macOS on ARM via software emulation - Prefer OpenGL ES via ANGLE on macOS for stability/performance on Metal-backed systems - Document virtio-gpu naming and regex rationale for matching device names - Note virtio devices manage VRAM dynamically via QEMU default max_hostmem - Add SMM/vmport note clarifying x86-specific semantics and Secure Boot differences No functional changes; comments only. Signed-off-by: Martin Wimpress <martin@wimpress.org>
This commit is contained in:
Martin Wimpress
Martin Wimpress
parent
2324d96303
commit
e7b49430cf
48
quickemu
48
quickemu
|
|
@ -504,7 +504,9 @@ function configure_cpu() {
|
|||
if [ "${ARCH_VM}" == "aarch64" ]; then
|
||||
# ARM64 guest support
|
||||
# https://qemu-project.gitlab.io/qemu/system/arm/virt.html
|
||||
# highmem=on allows RAM above 4GB (required for VMs with >3GB RAM)
|
||||
# highmem=on allows aarch64 guests on the "virt" machine type to access guest RAM
|
||||
# above the 4GB boundary. This is required for VMs configured with >3GB RAM and is
|
||||
# generally more compatible on modern aarch64 systems.
|
||||
# pflash0/pflash1 reference the blockdev nodes for AAVMF firmware
|
||||
MACHINE_TYPE="virt,highmem=on,pflash0=rom,pflash1=efivars"
|
||||
case ${ARCH_HOST} in
|
||||
|
|
@ -518,15 +520,28 @@ function configure_cpu() {
|
|||
esac
|
||||
elif [ "${ARCH_VM}" != "${ARCH_HOST}" ]; then
|
||||
# If the architecture of the VM is different from the host, disable acceleration
|
||||
# and use TCG (Tiny Code Generator) software emulation. TCG emulates the target
|
||||
# architecture in software, allowing cross-architecture virtualisation (e.g.,
|
||||
# running x86_64 VMs on ARM hosts).
|
||||
#
|
||||
# Users can manually force TCG mode by adding this to their VM .conf file:
|
||||
# cpu_model="qemu64"
|
||||
# extra_args="-accel tcg"
|
||||
# or by exporting QEMU_ACCEL in the shell environment:
|
||||
# export QEMU_ACCEL="tcg"
|
||||
#
|
||||
# TCG is useful for:
|
||||
# - Cross-architecture virtualisation (x86 on ARM, ARM on x86)
|
||||
# - Testing VMs on hosts without hardware virtualisation support
|
||||
# - Emulating CPU features in software (e.g., running macOS x86_64 VMs on ARM Macs)
|
||||
CPU_MODEL="qemu64"
|
||||
CPU_KVM_UNHALT=""
|
||||
QEMU_ACCEL="tcg"
|
||||
fi
|
||||
|
||||
# TODO: More robust detection of running in a VM
|
||||
# - macOS check for CPU flag: vmx
|
||||
# - Linux AMD check for CPU flag: svm
|
||||
# - Linux Intel check for CPU flag: vmx
|
||||
# Detect if running inside a VM based on manufacturer detection
|
||||
# Note: Checking CPU flags (vmx/svm) indicates hardware virtualisation SUPPORT,
|
||||
# not whether we're inside a VM. Nested virtualisation may expose these flags.
|
||||
case ${MANUFACTURER,,} in
|
||||
qemu|virtualbox) CPU_MODEL="qemu64"
|
||||
QEMU_ACCEL="tcg"
|
||||
|
|
@ -549,8 +564,10 @@ function configure_cpu() {
|
|||
fi
|
||||
elif [ "${ARCH_HOST}" == "aarch64" ] || [ "${ARCH_HOST}" == "arm64" ]; then
|
||||
# ARM hosts running native ARM guests with hardware acceleration (HVF on macOS, KVM on Linux)
|
||||
# ARM processors don't have x86-specific virtualisation flags (VT-x/SVM) to check
|
||||
# Cross-architecture guests (x86 on ARM) use TCG and skip this validation block entirely
|
||||
# ARM processors don't have x86-specific virtualisation flags (VT-x/SVM) to check.
|
||||
# We use architecture detection here instead of vendor detection (used for x86)
|
||||
# because ARM CPUs don't have standardised vendor strings like x86 (GenuineIntel/AuthenticAMD).
|
||||
# Cross-architecture guests (x86 on ARM) use TCG and skip this validation block entirely.
|
||||
# No validation needed here - ARM virtualisation support is handled by the hypervisor
|
||||
true
|
||||
else
|
||||
|
|
@ -603,7 +620,8 @@ function configure_cpu() {
|
|||
# A CPU with fma is required for Metal support
|
||||
# A CPU with invtsc is required for macOS to boot
|
||||
# Skip CPU feature checks when using TCG emulation (cross-architecture)
|
||||
# as QEMU will emulate the required x86 features in software
|
||||
# as TCG will emulate the required x86 features in software. This enables
|
||||
# running macOS x86_64 VMs on ARM Macs through software emulation.
|
||||
if [ "${QEMU_ACCEL}" != "tcg" ]; then
|
||||
case ${macos_release} in
|
||||
ventura|sonoma|sequoia|tahoe)
|
||||
|
|
@ -1294,6 +1312,10 @@ function configure_display() {
|
|||
# Map Quickemu $display to QEMU -display
|
||||
case ${display} in
|
||||
cocoa)
|
||||
# macOS: prefer OpenGL ES (via ANGLE) for stability and performance
|
||||
# ANGLE provides OpenGL ES on macOS through Metal, which is more stable
|
||||
# than the deprecated native OpenGL implementation
|
||||
# Reference: https://gist.github.com/akihikodaki/87df4149e7ca87f18dc56807ec5a1bc5
|
||||
if [ "${gl}" == "on" ] && check_cocoa_gl_es_support; then
|
||||
DISPLAY_RENDER="${display},gl=es"
|
||||
gl="es"
|
||||
|
|
@ -1309,6 +1331,8 @@ function configure_display() {
|
|||
esac
|
||||
|
||||
# https://www.kraxel.org/blog/2021/05/virtio-gpu-qemu-graphics-update/
|
||||
# For GL-enabled displays, check if dedicated GL device variants are available.
|
||||
# Note: virtio-gpu-pci becomes virtio-gpu-gl-pci (not virtio-gpu-pci-gl)
|
||||
if [ "${gl}" != "off" ] && [[ "${DISPLAY_DEVICE}" =~ ^virtio-(vga|gpu|gpu-pci)$ ]]; then
|
||||
local GL_DEVICE=""
|
||||
case "${DISPLAY_DEVICE}" in
|
||||
|
|
@ -1334,6 +1358,8 @@ function configure_display() {
|
|||
fi
|
||||
|
||||
# Set display resolution for devices that support xres/yres parameters
|
||||
# Use (,|$) anchor to match device names with or without comma-separated parameters
|
||||
# Pattern ordered most-specific to least-specific for clarity (vga-gl before vga, etc.)
|
||||
if [[ "${DISPLAY_DEVICE}" =~ ^(virtio-(vga|vga-gl|gpu|gpu-gl|gpu-pci|gpu-gl-pci)|qxl|qxl-vga|bochs-display)(,|$) ]]; then
|
||||
VIDEO="${VIDEO},xres=${X_RES},yres=${Y_RES}"
|
||||
echo " @ (${X_RES} x ${Y_RES})"
|
||||
|
|
@ -1342,6 +1368,9 @@ function configure_display() {
|
|||
fi
|
||||
|
||||
# Allocate VRAM to VGA devices
|
||||
# Note: virtio devices (virtio-vga, virtio-gpu-pci, and their -gl variants) use
|
||||
# dynamic memory management and don't require explicit VRAM allocation via parameters.
|
||||
# They use QEMU's default max_hostmem setting (256 MiB) which is sufficient for most use cases.
|
||||
case ${DISPLAY_DEVICE} in
|
||||
bochs-display) VIDEO="${VIDEO},vgamem=67108864";;
|
||||
qxl|qxl-vga) VIDEO="${VIDEO},ram_size=65536,vram_size=65536,vgamem_mb=64";;
|
||||
|
|
@ -1618,6 +1647,9 @@ function vm_boot() {
|
|||
fi
|
||||
|
||||
# Build machine arguments - SMM and vmport are x86-only options
|
||||
# SMM (System Management Mode) is an x86-specific CPU mode used for firmware operations
|
||||
# and is required for Secure Boot. ARM64 uses different mechanisms for firmware security.
|
||||
# vmport emulates VMware's I/O port for guest tools, which is also x86-specific.
|
||||
if [ "${ARCH_VM}" == "aarch64" ]; then
|
||||
# ARM64 uses 'virt' machine type without x86-specific options
|
||||
# shellcheck disable=SC2054,SC2206,SC2140
|
||||
|
|
|
|||
Loading…
Reference in New Issue