English | 中文
Project author: YWYCASM
HItex (Hypervisor Interruptible Mutex) is an interruptible mutex mechanism for real-time QEMU-KVM virtualization, designed to improve the timeliness and predictability of guest interrupt handling under heavy I/O workloads. It addresses the vIRQ deferral problem: after a VM exit to QEMU for I/O handling, a vCPU may be unable to resume guest execution and handle pending interrupts because it is waiting for the Big QEMU Lock (BQL).
HItex combines vIRQ-aware asynchronous trylock with restartable I/O emulation. When guest interrupts are enabled and a vIRQ is pending, the vCPU can withdraw from lock acquisition, return to the guest to handle the interrupt, and then retry the incomplete I/O operation. This preserves mutual exclusion and requires changes only to QEMU and the host KVM, with no guest OS modifications.
This repository provides the ARM64 kernel and QEMU implementation, guest images for testing, and support for real-time vCPU priorities, CPU affinity, and comparisons with HItex enabled or disabled. Tests on ARMv8 platforms under heavy I/O workloads showed a 96% reduction in maximum guest periodic-task latency and an 87% reduction in UDP packet loss rate. Results depend on the hardware, workload, and configuration.
| File / directory | Description |
|---|---|
linux-rpi-6.1.y/ |
Modified Raspberry Pi host kernel source with a supplied .config enabling PREEMPT_RT, KVM, and HItex |
qemu-8.1.0/ |
Modified QEMU source supporting -rtvcpu and -hitex |
Image |
ARM64 kernel image for the virtual machine |
rootfs_arm.img |
Guest root filesystem image |
On an ARM64 Raspberry Pi host with KVM support, enter the linux-rpi-6.1.y source directory in this project and use the supplied .config to build and install the kernel and modules following the kernel installation procedure for your Raspberry Pi model. Reboot into the new kernel. Ensure /dev/kvm is available before launching the VM; enabling HItex requires the modified host kernel provided by this project.
Run from the project root. C/C++ build tools, Python 3, Ninja, and QEMU build dependencies are required.
cd qemu-8.1.0
mkdir -p build
cd build
../configure --target-list=aarch64-softmmu --enable-kvm --enable-rtvcpu --enable-hitex
ninja -j"$(nproc)"
cd ../..If configuration reports missing Python packages or system dependencies, install them as indicated and retry. The resulting executable is qemu-8.1.0/build/qemu-system-aarch64.
Run from the project root:
sudo ./qemu-8.1.0/build/qemu-system-aarch64 \
-M virt -cpu host -smp 2 -m 4G \
-kernel ./Image -enable-kvm -nographic \
-drive file=./rootfs_arm.img,format=raw \
-append "root=/dev/vda rw console=ttyAMA0" \
-rtvcpu prio=90,cpupinset=2:3 \
-hitex-rtvcpu prio=90,cpupinset=2:3: use FIFO real-time scheduling at priority 90 for vCPU threads and pin them to host CPUs 2 and 3. Ensure these CPUs are online, or adjust the IDs for your host.-hitex: enable interruptible mutexes. Remove this option for a baseline run with HItex disabled.- This example allocates 2 vCPUs and 4 GiB of memory; the host must have sufficient resources.
Log in through the VM console in the current terminal with username root and password 111111. Run inside the VM:
# Start a background I/O workload
stress-ng --hdd 4 --hdd-bytes 1G &
# Measure real-time wake-up latency to evaluate interrupt responsiveness
cyclictest -t 1 -p 99 -i 1000 -d 0 -m -aIf the commands are unavailable, install stress-ng and rt-tests (which provides cyclictest) inside the VM. Ensure the test directory has enough writable disk space. Keep the workload, CPU affinity, and test duration identical across runs with and without -hitex, then compare the average and maximum latency reported by cyclictest. Press Ctrl+C to stop cyclictest, then run kill %1 to stop the background workload in the same shell.
Original HItex code and modifications are licensed under the GNU General Public License, version 2 only (GPL-2.0-only). See LICENSE for the full text. Bundled Linux, QEMU, and other third-party components retain their respective copyright notices, licenses, and applicable exceptions, as specified in their directories and source files. Software within the VM images remains subject to its respective licenses.