NewFeatureTemplate

New Feature Template

Template to use for new features and changes that update user-visible interface options (command line options, QMP, etc.). Use the source of this page to populate a new one for the new feature, and then add the info.

Scope

[ ] Changes to Host kernel

[ ] Changes to Guest kernel

[ ] Changes to firmware, e.g. seabios, ovmf, vgabios, etc.

[ ] Affects all archs

[ ] Affects specific archs: x86, ppc, arm, s390, etc.

[ ] Affects all guests

[ ] Affects specific guests: Linux, Windows, etc.

If the changes affect only specific architectures or guests, describe how in the detailed description section.

Benefits to KVM and upper layers

• e.g. QEMU, libvirt, OpenStack, oVirt, etc.
• also include benefits to users

Added / removed / deprecated / changed settings exposed to higher layers or users

e.g.

• kernel config options
• kernel command line options
• module parameters
• /sys entries
• /proc entries

For new options / settings, what are the recommended values, and the ranges? If settings are workload-specific, describe in brief. This helps testers and higher layers to pick proper defaults.

Other debugging options / tunables

e.g.

• debugfs entries
• new tracepoints

When filing a bug for this feature / area, what kind of debug data will be most helpful? Anything that will make the bug reports more meaningful. Also, any tips on helping to narrow down the problems to this subsystem? e.g. A minimal command line that reproduces is always helpful.

Conflicts / enhances / deprecates any existing features

e.g.

• effectively disables feature X since both are exclusive
• boosts performance of feature Y transparently

Update plans

Is the feature complete? Are new things going to come in future releases? What are these pending changes?

How to test the feature

If possible, include instructions to also test with other projects - e.g. libvirt interfaces with qemu

Include as much information as possible. e.g.:

• How to test while disabling and enabling this feature / change
• Expected results when disabled
• Expected results when enabled
• Setup required - e.g. RDMA network connection between hosts
• Cases where feature shines
• Cases where feature doesn't shine
• Other features / subsystems that influence this one which should be tested together
• If there is performance-sensitive stuff here, how to setup such tests and test for regressions
• Are automated tests for Avocado added?
• Any cases that can test for scalability?
• In case of a qemu feature that's exposed to guests: how to check host's setting and guest values match? (e.g. # of MSI vectors exposed from qemu for a PCI device; and checking the #vectors in the guest via lspci)
• Description of all options for a new device -- ie options that can be set via the cmdline, and how they influence the performance / functionality
• If a feature uses a different feature with various options, what options make sense for this feature? e.g. virtio-scsi-pci added that uses -drive; or vhost-user added that uses other facilities: what options make sense together?

List of commits

(e.g. output from git log --pretty=oneline)

Dependencies

e.g.

• depends on a new systemd feature / release
• upstream releases where these changes are included

Supporting documentation

e.g.

• blog posts
• mailing list conversations
• slides / videos from conferences
• feature pages or commits from other projects (QEMU, libvirt, etc.)