How to Configure Machine Type and CPU Features for VM Tests Using vt.common.machine_type

Set machine_type under the [vt.common] section in your Avocado-VT configuration to specify the QEMU machine model (e.g., q35, pc, pseries), while CPU features are automatically detected from /proc/cpuinfo via virttest.vt_utils.cpu.get_cpu_features() and passed to QEMU through the -cpu argument.

The avocado-framework/avocado-vt repository provides a flexible testing framework for virtual machines driven by QEMU. Central to VM configuration is the vt.common.machine_type parameter, which determines the hardware machine model emulated by QEMU. Understanding how to set this option—and how it interacts with automatic CPU feature detection—allows you to precisely control the virtual hardware environment for your tests.

Understanding the vt.common.machine_type Configuration Parameter

What is machine_type?

The machine_type parameter specifies the QEMU machine model that defines the virtual hardware layout, including chipset, PCI topology, and default devices. Common values include pc (i440FX), q35 (Q35 chipset), pseries (IBM Power), and s390-ccw-virtio (IBM Z).

Where vt.common.machine_type is Defined

Default values reside in avocado_vt/conf.d/vt.conf under the [vt.common] section. The framework reads this during initialization to establish the baseline machine model for all VM tests.

How the Framework Processes vt.common.machine_type

Configuration Parsing in avocado_vt/options.py

The _process_machine_type method in avocado_vt/options.py (lines 245–262) handles the vt.common.machine_type parameter. It retrieves the value from the configuration dictionary and adds it to the Cartesian product, ensuring the machine type becomes a variable in the test matrix.

Cartesian Product Integration

The Cartesian parser treats machine_type as a first-class parameter. When avocado_vt/loader.py builds test variants (lines 57–80), it calls get_opt(config, "vt.common.machine_type") to inject the machine type into the test name and parameter set, making it available to the VM creation logic.

QEMU Command Line Injection

During VM instantiation, virttest/qemu_vm.py reads the machine_type parameter from the test configuration. It appends the -machine <type> flag to the QEMU command line, directing QEMU to emulate the specified hardware model.

Configuring CPU Features Alongside Machine Type

Automatic CPU Feature Detection

The framework automatically detects host CPU capabilities through virttest/vt_utils/cpu.py. The get_cpu_features() function (lines 79–94) parses /proc/cpuinfo, extracts the features line using a regular expression, and returns a Python list of available CPU flags.

Passing Features to QEMU

While vt.common.machine_type controls the machine model, CPU features are passed to QEMU via the -cpu argument. The test parameters can specify cpu_model (e.g., host) and append specific features from get_cpu_features() using the + prefix syntax (e.g., -cpu host,+vmx,+ssbd).

Practical Configuration Examples

Configure the machine type in the default configuration file:

[vt.common]

# QEMU machine model: pc, q35, pseries, s390-ccw-virtio, etc.

machine_type = q35

Override the value from the command line:

avocado run my_vm_test.py --vt-machine-type q35

# Alternative long-form option:

avocado run my_vm_test.py --vt-common.machine_type q35

Access the configured value programmatically in a test:

from avocado.core.settings import Settings

machine = Settings().as_dict().get("vt.common.machine_type")
print(f"Executing VM test with machine type: {machine}")

Retrieve host CPU features for custom logic:

from virttest.vt_utils import cpu

host_features = cpu.get_cpu_features()
print("Detected host CPU features:", host_features)

Combine machine type and CPU features in test parameters:

# vm_params dict passed to QemuVM

vm_params = {
    "machine_type": "q35",
    "cpu_model": "host",
    "cpu_features": "+".join(cpu.get_cpu_features()[:3]),  # Use first 3 features

}

# Results in QEMU arguments: -machine q35 -cpu host,+feature1,+feature2,+feature3

Summary

• vt.common.machine_type specifies the QEMU machine model (e.g., q35, pc, pseries) in the [vt.common] configuration section.
• The framework parses this value in avocado_vt/options.py via _process_machine_type and injects it into the Cartesian product for test matrix generation.
• virttest/qemu_vm.py translates the parameter into the -machine QEMU command-line flag.
• CPU features are automatically detected by virttest/vt_utils/cpu.py (get_cpu_features()) reading /proc/cpuinfo, and can be appended to the -cpu argument.
• You can configure the machine type via vt.conf, CLI options (--vt-machine-type), or programmatically through Avocado's Settings API.

Frequently Asked Questions

How do I override vt.common.machine_type from the command line?

Use the --vt-machine-type shortcut or the full --vt-common.machine_type option when invoking Avocado. For example: avocado run test.py --vt-machine-type q35. This value is processed by _process_machine_type in avocado_vt/options.py and takes precedence over the configuration file.

What file handles the parsing of vt.common.machine_type?

The parsing logic resides in avocado_vt/options.py within the _process_machine_type method (lines 245–262). This method retrieves the value from the configuration object and adds it to the Cartesian product, making it available to the test loader and VM creation logic in virttest/qemu_vm.py.

How does avocado-vt detect host CPU features?

The framework detects CPU capabilities through the get_cpu_features() function in virttest/vt_utils/cpu.py (lines 79–94). This function reads /proc/cpuinfo, parses the features line using a regular expression, and returns a Python list of feature flags available on the host hardware.

Can I use custom CPU features with any machine type?

Yes, CPU features operate independently of the machine type configuration. While vt.common.machine_type controls the hardware model (chipset, PCI topology), you can specify any compatible CPU model and feature set via the cpu_model and cpu_features parameters. The framework combines these into the -cpu QEMU argument, allowing you to enable specific flags like +vmx or +ssbd regardless of whether you use pc, q35, or pseries machine types.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}