@@ -7,7 +7,7 @@ Review checklist for kvm patches
771. The patch must follow Documentation/process/coding-style.rst and
88 Documentation/process/submitting-patches.rst.
99
10- 2. Patches should be against kvm.git master branch .
10+ 2. Patches should be against kvm.git master or next branches .
1111
12123. If the patch introduces or modifies a new userspace API:
1313 - the API must be documented in Documentation/virt/kvm/api.rst
@@ -18,10 +18,10 @@ Review checklist for kvm patches
18185. New features must default to off (userspace should explicitly request them).
1919 Performance improvements can and should default to on.
2020
21- 6. New cpu features should be exposed via KVM_GET_SUPPORTED_CPUID2
21+ 6. New cpu features should be exposed via KVM_GET_SUPPORTED_CPUID2,
22+ or its equivalent for non-x86 architectures
2223
23- 7. Emulator changes should be accompanied by unit tests for qemu-kvm.git
24- kvm/test directory.
24+ 7. The feature should be testable (see below).
2525
26268. Changes should be vendor neutral when possible. Changes to common code
2727 are better than duplicating changes to vendor code.
@@ -36,6 +36,87 @@ Review checklist for kvm patches
363611. New guest visible features must either be documented in a hardware manual
3737 or be accompanied by documentation.
3838
39- 12. Features must be robust against reset and kexec - for example, shared
40- host/guest memory must be unshared to prevent the host from writing to
41- guest memory that the guest has not reserved for this purpose.
39+ Testing of KVM code
40+ -------------------
41+
42+ All features contributed to KVM, and in many cases bugfixes too, should be
43+ accompanied by some kind of tests and/or enablement in open source guests
44+ and VMMs. KVM is covered by multiple test suites:
45+
46+ *Selftests *
47+ These are low level tests that allow granular testing of kernel APIs.
48+ This includes API failure scenarios, invoking APIs after specific
49+ guest instructions, and testing multiple calls to ``KVM_CREATE_VM ``
50+ within a single test. They are included in the kernel tree at
51+ ``tools/testing/selftests/kvm ``.
52+
53+ ``kvm-unit-tests ``
54+ A collection of small guests that test CPU and emulated device features
55+ from a guest's perspective. They run under QEMU or ``kvmtool ``, and
56+ are generally not KVM-specific: they can be run with any accelerator
57+ that QEMU support or even on bare metal, making it possible to compare
58+ behavior across hypervisors and processor families.
59+
60+ Functional test suites
61+ Various sets of functional tests exist, such as QEMU's ``tests/functional ``
62+ suite and `avocado-vt <https://avocado-vt.readthedocs.io/en/latest/ >`__.
63+ These typically involve running a full operating system in a virtual
64+ machine.
65+
66+ The best testing approach depends on the feature's complexity and
67+ operation. Here are some examples and guidelines:
68+
69+ New instructions (no new registers or APIs)
70+ The corresponding CPU features (if applicable) should be made available
71+ in QEMU. If the instructions require emulation support or other code in
72+ KVM, it is worth adding coverage to ``kvm-unit-tests `` or selftests;
73+ the latter can be a better choice if the instructions relate to an API
74+ that already has good selftest coverage.
75+
76+ New hardware features (new registers, no new APIs)
77+ These should be tested via ``kvm-unit-tests ``; this more or less implies
78+ supporting them in QEMU and/or ``kvmtool ``. In some cases selftests
79+ can be used instead, similar to the previous case, or specifically to
80+ test corner cases in guest state save/restore.
81+
82+ Bug fixes and performance improvements
83+ These usually do not introduce new APIs, but it's worth sharing
84+ any benchmarks and tests that will validate your contribution,
85+ ideally in the form of regression tests. Tests and benchmarks
86+ can be included in either ``kvm-unit-tests `` or selftests, depending
87+ on the specifics of your change. Selftests are especially useful for
88+ regression tests because they are included directly in Linux's tree.
89+
90+ Large scale internal changes
91+ While it's difficult to provide a single policy, you should ensure that
92+ the changed code is covered by either ``kvm-unit-tests `` or selftests.
93+ In some cases the affected code is run for any guests and functional
94+ tests suffice. Explain your testing process in the cover letter,
95+ as that can help identify gaps in existing test suites.
96+
97+ New APIs
98+ It is important to demonstrate your use case. This can be as simple as
99+ explaining that the feature is already in use on bare metal, or it can be
100+ a proof-of-concept implementation in userspace. The latter need not be
101+ open source, though that is of course preferrable for easier testing.
102+ Selftests should test corner cases of the APIs, and should also cover
103+ basic host and guest operation if no open source VMM uses the feature.
104+
105+ Bigger features, usually spanning host and guest
106+ These should be supported by Linux guests, with limited exceptions for
107+ Hyper-V features that are testable on Windows guests. It is strongly
108+ suggested that the feature be usable with an open source host VMM, such
109+ as at least one of QEMU or crosvm, and guest firmware. Selftests should
110+ test at least API error cases. Guest operation can be covered by
111+ either selftests of ``kvm-unit-tests `` (this is especially important for
112+ paravirtualized and Windows-only features). Strong selftest coverage
113+ can also be a replacement for implementation in an open source VMM,
114+ but this is generally not recommended.
115+
116+ Following the above suggestions for testing in selftests and
117+ ``kvm-unit-tests `` will make it easier for the maintainers to review
118+ and accept your code. In fact, even before you contribute your changes
119+ upstream it will make it easier for you to develop for KVM.
120+
121+ Of course, the KVM maintainers reserve the right to require more tests,
122+ though they may also waive the requirement from time to time.
0 commit comments