| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
================================ |
| 4 |
Review checklist for kvm patches |
| 5 |
================================ |
| 6 |
|
| 7 |
1. The patch must follow Documentation/process/coding-style.rst and |
| 8 |
Documentation/process/submitting-patches.rst. |
| 9 |
|
| 10 |
2. Patches should be against kvm.git master or next branches. |
| 11 |
|
| 12 |
3. If the patch introduces or modifies a new userspace API: |
| 13 |
- the API must be documented in Documentation/virt/kvm/api.rst |
| 14 |
- the API must be discoverable using KVM_CHECK_EXTENSION |
| 15 |
|
| 16 |
4. New state must include support for save/restore. |
| 17 |
|
| 18 |
5. New features must default to off (userspace should explicitly request them). |
| 19 |
Performance improvements can and should default to on. |
| 20 |
|
| 21 |
6. New cpu features should be exposed via KVM_GET_SUPPORTED_CPUID2, |
| 22 |
or its equivalent for non-x86 architectures |
| 23 |
|
| 24 |
7. The feature should be testable (see below). |
| 25 |
|
| 26 |
8. Changes should be vendor neutral when possible. Changes to common code |
| 27 |
are better than duplicating changes to vendor code. |
| 28 |
|
| 29 |
9. Similarly, prefer changes to arch independent code than to arch dependent |
| 30 |
code. |
| 31 |
|
| 32 |
10. User/kernel interfaces and guest/host interfaces must be 64-bit clean |
| 33 |
(all variables and sizes naturally aligned on 64-bit; use specific types |
| 34 |
only - u64 rather than ulong). |
| 35 |
|
| 36 |
11. New guest visible features must either be documented in a hardware manual |
| 37 |
or be accompanied by documentation. |
| 38 |
|
| 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 preferable 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. |