Skip to content

Quickly sandbox your AI agent.

Python

Scope WHPX kernel-irqchip=off to x86_64

Matt Van Horn3e5e68383b10
diff --git a/docs/under-the-hood/02-sandbox-lifecycle.md b/docs/under-the-hood/02-sandbox-lifecycle.md
index 82be862..4777067 100644
--- a/docs/under-the-hood/02-sandbox-lifecycle.md
+++ b/docs/under-the-hood/02-sandbox-lifecycle.md
@@ -60,7 +60,7 @@ Auto-detection selects the best available accelerator:
With hardware acceleration (`-cpu host`), the guest runs on the real CPU. With TCG (`-cpu max`), QEMU translates every instruction in software.
-On Windows, WHPX gets an extra flag: `-accel whpx,kernel-irqchip=off`. Routing interrupts through userspace keeps device interrupts reliable alongside the guest's `noapic` boot parameter.
+On Windows x86_64 only, WHPX gets an extra flag: `-accel whpx,kernel-irqchip=off`. Routing interrupts through userspace keeps device interrupts reliable alongside the guest's `noapic` boot parameter.
## Device naming by machine type
diff --git a/packages/quicksand-core/quicksand_core/qemu/platform.py b/packages/quicksand-core/quicksand_core/qemu/platform.py
index dab7bac..f3ca824 100644
--- a/packages/quicksand-core/quicksand_core/qemu/platform.py
+++ b/packages/quicksand-core/quicksand_core/qemu/platform.py
@@ -24,6 +24,7 @@ from ..host.os_ import (
)
from ..host.smb import SMBServer
from .arch import (
+ Architecture,
ArchitectureConfig,
BaseArchitectureConfig,
MachineType,
@@ -223,14 +224,13 @@ class PlatformConfig:
if accelerator:
accel_arg = accelerator.value
- if accelerator == Accelerator.WHPX:
- # kernel-irqchip=off routes interrupts through userspace. WHPX's
- # in-kernel irqchip combined with the guest's noapic boot param
- # (our IO-APIC workaround) delivers device interrupts unreliably:
- # later `mount -t cifs` operations hang in the guest kernel until
- # they time out. This was previously only applied when nested
- # (baseboard == "Microsoft Corporation"), but bare-metal Windows
- # hosts need it too, so apply it for WHPX unconditionally.
+ if accelerator == Accelerator.WHPX and self.arch.arch_type == Architecture.X86_64:
+ # kernel-irqchip=off is the x86 noapic workaround. WHPX's
+ # in-kernel irqchip plus the guest's noapic boot param drops
+ # device interrupts, so later `mount -t cifs` calls hang.
+ # Bare-metal x86_64 still needs the userspace irqchip. Arm
+ # WHPX accepts only kernel-irqchip=on, so every other
+ # architecture keeps a bare whpx accel arg.
accel_arg = "whpx,kernel-irqchip=off"
cmd.extend(["-accel", accel_arg])
diff --git a/tests/unit/test_core_sandbox.py b/tests/unit/test_core_sandbox.py
index 127024e..473ce85 100644
--- a/tests/unit/test_core_sandbox.py
+++ b/tests/unit/test_core_sandbox.py
@@ -200,23 +200,34 @@ class TestSandboxMountConfig:
class TestWhpxAccelerator:
- """Regression: WHPX must always get kernel-irqchip=off.
+ """Regression: x86_64 WHPX must always get kernel-irqchip=off.
WHPX's in-kernel irqchip + the guest's noapic boot param delivers device
- interrupts unreliably (CIFS mounts hang). kernel-irqchip=off fixes it. This
- was previously gated on nested_virt (baseboard == Microsoft), but bare-metal
- Windows hosts need it too, so it must be applied for WHPX regardless.
+ interrupts unreliably (CIFS mounts hang). kernel-irqchip=off fixes it on
+ x86_64. This was previously gated on nested_virt (baseboard == Microsoft),
+ but bare-metal Windows x86_64 hosts need it too. Arm WHPX accepts only
+ kernel-irqchip=on, so other architectures keep a bare accel argument.
"""
- def _build(self, fake_qcow2, *, nested_virt: bool):
+ def _build(
+ self,
+ fake_qcow2,
+ *,
+ nested_virt: bool,
+ arch=None,
+ accelerator: Accelerator | None = Accelerator.WHPX,
+ qemu_binary: str = "/usr/bin/qemu-system-x86_64",
+ ):
from quicksand_core.host import WindowsConfig
from quicksand_core.qemu.arch import X86_64Config
- platform_config = PlatformConfig(arch=X86_64Config(), os=WindowsConfig())
+ if arch is None:
+ arch = X86_64Config()
+ platform_config = PlatformConfig(arch=arch, os=WindowsConfig())
return platform_config.build_qemu_command(
config=SandboxConfig(image="ubuntu"),
runtime_info=RuntimeInfo(
- qemu_binary=Path("/usr/bin/qemu-system-x86_64"),
+ qemu_binary=Path(qemu_binary),
qemu_img=Path("/usr/bin/qemu-img"),
runtime_dir=Path("/usr"),
),
@@ -225,7 +236,7 @@ class TestWhpxAccelerator:
overlay_path=Path(str(fake_qcow2)),
agent_port=12345,
agent_token="test_token",
- accelerator=Accelerator.WHPX,
+ accelerator=accelerator,
nested_virt=nested_virt,
)
@@ -240,6 +251,52 @@ class TestWhpxAccelerator:
accel_val = cmd[cmd.index("-accel") + 1]
assert accel_val == "whpx,kernel-irqchip=off"
+ def test_arm64_whpx_omits_kernel_irqchip(self, fake_qcow2):
+ """ARM64 WHPX (qemu-system-aarch64) rejects kernel-irqchip=off."""
+ from quicksand_core.qemu.arch import ARM64Config
+
+ for nested_virt in (False, True):
+ cmd = self._build(
+ fake_qcow2,
+ nested_virt=nested_virt,
+ arch=ARM64Config(),
+ accelerator=Accelerator.WHPX,
+ qemu_binary="/usr/bin/qemu-system-aarch64",
+ )
+ accel_val = cmd[cmd.index("-accel") + 1]
+ assert accel_val == "whpx"
+ assert "kernel-irqchip" not in " ".join(cmd)
+
+ def test_other_accelerators_stay_bare(self, fake_qcow2):
+ """KVM, HVF, and TCG stay bare; accelerator=None omits -accel."""
+ from quicksand_core.qemu.arch import ARM64Config, X86_64Config
+
+ cases = (
+ (X86_64Config(), "/usr/bin/qemu-system-x86_64"),
+ (ARM64Config(), "/usr/bin/qemu-system-aarch64"),
+ )
+ for arch, qemu_binary in cases:
+ for accel in (Accelerator.KVM, Accelerator.HVF, Accelerator.TCG):
+ cmd = self._build(
+ fake_qcow2,
+ nested_virt=False,
+ arch=arch,
+ accelerator=accel,
+ qemu_binary=qemu_binary,
+ )
+ accel_val = cmd[cmd.index("-accel") + 1]
+ assert accel_val == accel.value
+ assert "irqchip" not in " ".join(cmd)
+
+ cmd = self._build(
+ fake_qcow2,
+ nested_virt=False,
+ arch=arch,
+ accelerator=None,
+ qemu_binary=qemu_binary,
+ )
+ assert "-accel" not in cmd
+
class TestSandboxContextManager:
"""Tests for async context manager interface."""