KVM Virtualization

Relevant source files

The following files were used as context for generating this wiki page:

• Documentation/process/maintainer-kvm-x86.rst
• Documentation/virt/kvm/review-checklist.rst
• Documentation/kernel-hacking/hacking.rst
• Documentation/process/4.Coding.rst
• Documentation/virt/index.rst
• Documentation/process/howto.rst

Kernel-based Virtual Machine (KVM) provides virtualization infrastructure for the Linux kernel. It turns the Linux kernel into a hypervisor that allows a host machine to run multiple, isolated virtual machines (VMs). KVM supports hardware-assisted virtualization on various architectures, most notably x86 through Intel VMX and AMD SVM extensions.

Sources: Documentation/virt/index.rst:1-15, Documentation/process/maintainer-kvm-x86.rst:114-118

System Architecture and Components

KVM operates as a kernel module that interacts with hardware virtualization features. The architecture divides responsibilities between the Linux kernel (acting as the hypervisor) and userspace Virtual Machine Monitors (VMMs) like QEMU or kvmtool.

CPU Virtualization Modes

KVM x86 implementations are deeply tied to architectural behaviors defined by hardware vendors. The system uses specific hardware extensions to manage guest execution.

Feature	Description
VMX	Intel Virtual Machine Extensions for hardware-assisted virtualization.
SVM	AMD Secure Virtual Machine architecture.
nVMX / nSVM	Nested virtualization support allowing a guest to act as a hypervisor.
TDP	Two-Level Address Translation (EPT for Intel, NPT for AMD).

Sources: Documentation/process/maintainer-kvm-x86.rst:114-123, Documentation/process/maintainer-kvm-x86.rst:196-200

Execution Contexts

The hypervisor manages transitions between host and guest contexts. Within the Linux kernel environment, execution falls into three primary categories.

The diagram shows the transition flow between userspace requests, kernel-level management, guest execution, and interrupt handling.
Sources: Documentation/kernel-hacking/hacking.rst:24-45, Documentation/virt/kvm/review-checklist.rst:38-42

Programming and Development Standards

API and Interfaces

KVM exposes functionality to userspace via the /dev/kvm device. Developers must follow specific rules when modifying or adding to the KVM API.

• Discovery: Userspace must discover new APIs using the KVM_CHECK_EXTENSION ioctl.
• Documentation: All new userspace APIs must be documented in Documentation/virt/kvm/api.rst.
• Alignment: Interfaces must be 64-bit clean with all variables naturally aligned to 64-bit boundaries.
• Save/Restore: New state introduced by a feature must include support for save and restore operations to facilitate VM migration.

Sources: Documentation/virt/kvm/review-checklist.rst:13-25

Coding Constraints

KVM development adheres to strict kernel programming rules to ensure stability and performance.

1. Locking: All shared resources (data structures, hardware registers) must be protected by locks. Developers use lockdep to find potential deadlocks.
2. Memory: Use GFP_KERNEL for allocations in user context and GFP_ATOMIC in interrupt context.
3. Floating Point: Do not use floating point or MMX instructions in the kernel as the FPU context is not saved.
4. Style: KVM x86 prefers the "reverse fir tree" (reverse Christmas tree) variable declaration style where possible.

Sources: Documentation/process/4.Coding.rst:104-118, Documentation/kernel-hacking/hacking.rst:100-110, Documentation/process/maintainer-kvm-x86.rst:95-99

Testing Requirements

Testing is mandatory for all KVM contributions. The project utilizes several test suites to validate changes across different hardware and configurations.

Mandatory Test Suites

• KVM Selftests: Located at tools/testing/selftests/kvm, these provide granular testing of kernel APIs and failure scenarios.
• kvm-unit-tests: A separate repository of small guests that test CPU and emulated device features from the guest's perspective.
• Functional Tests: Suite including QEMU functional tests and full OS boots.

Sources: Documentation/virt/kvm/review-checklist.rst:32-55

Validation Matrix

Requirement	Description
Build Cleanliness	Must build for KVM_INTEL=m, KVM_AMD=m, and KVM_WERROR=y.
TDP Validation	Changes to shadow paging or common MMU code require testing with TDP (EPT/NPT) disabled.
Vendor Neutrality	Changes should be vendor-neutral; common code modifications are preferred over duplicating logic in VMX/SVM files.
Hardware Access	If a developer lacks specific hardware (e.g., AMD vs Intel), they must state the testing limitations in their submission.

Sources: Documentation/process/maintainer-kvm-x86.rst:185-205, Documentation/virt/kvm/review-checklist.rst:26-30

Development Workflow

KVM x86 is transitioning to an architecture-specific tree model. Development flows through multiple branches before reaching the mainline Linux kernel.

The diagram illustrates the path of patches from submission through topic branches and integration trees to the mainline kernel.
Sources: Documentation/process/maintainer-kvm-x86.rst:23-55

Patch Guidelines

• Prefixes: Use specific prefixes like KVM: x86:, KVM: VMX:, or KVM: SVM:.
• Imperative Mood: Write changelogs and comments using the imperative mood (e.g., "Fix bug" instead of "Fixed bug").
• Citations: Reference Intel SDM or AMD APM by name, but avoid referencing specific section numbers as they change frequently.

Sources: Documentation/process/maintainer-kvm-x86.rst:126-150, Documentation/process/maintainer-kvm-x86.rst:101-105

Summary

KVM Virtualization integrates hardware-assisted virtualization directly into the Linux kernel. It relies on strict adherence to hardware architectural manuals (SDM/APM) and requires comprehensive testing through both selftests and unit tests. The development process emphasizes consistency, vendor neutrality, and robust userspace API management to maintain a stable hypervisor environment.

Sources: Documentation/process/maintainer-kvm-x86.rst:16-20, Documentation/virt/kvm/review-checklist.rst:104-108