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.
- 1 Feature name
- 2 Short description
- 3 Feature authors / maintainers
- 4 Scope
- 5 Detailed description
- 6 Benefits to KVM and upper layers
- 7 Added / removed / deprecated / changed settings exposed to higher layers or users
- 8 Other debugging options / tunables
- 9 Will this feature result in a noticeable change for users?
- 10 Conflicts / enhances / deprecates any existing features
- 11 Update plans
- 12 How to test the feature
- 13 List of commits
- 14 Dependencies
- 15 Supporting documentation
- 16 Revisions
[ ] 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
- 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
- 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.
Will this feature result in a noticeable change for users?
If so, how?
Conflicts / enhances / deprecates any existing features
- effectively disables feature X since both are exclusive
- boosts performance of feature Y transparently
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)
- depends on a new systemd feature / release
- upstream releases where these changes are included
- blog posts
- mailing list conversations
- slides / videos from conferences
- feature pages or commits from other projects (QEMU, libvirt, etc.)