1.. SPDX-License-Identifier: GPL-2.0 2 3================================ 4Review checklist for kvm patches 5================================ 6 71. The patch must follow Documentation/process/coding-style.rst and 8 Documentation/process/submitting-patches.rst. 9 102. Patches should be against kvm.git master or next branches. 11 123. 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 164. New state must include support for save/restore. 17 185. New features must default to off (userspace should explicitly request them). 19 Performance improvements can and should default to on. 20 216. New cpu features should be exposed via KVM_GET_SUPPORTED_CPUID2, 22 or its equivalent for non-x86 architectures 23 247. The feature should be testable (see below). 25 268. Changes should be vendor neutral when possible. Changes to common code 27 are better than duplicating changes to vendor code. 28 299. Similarly, prefer changes to arch independent code than to arch dependent 30 code. 31 3210. 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 3611. New guest visible features must either be documented in a hardware manual 37 or be accompanied by documentation. 38 39Testing of KVM code 40------------------- 41 42All features contributed to KVM, and in many cases bugfixes too, should be 43accompanied by some kind of tests and/or enablement in open source guests 44and 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 60Functional 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 66The best testing approach depends on the feature's complexity and 67operation. Here are some examples and guidelines: 68 69New 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 76New 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 82Bug 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 90Large 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 97New 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 105Bigger 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 116Following the above suggestions for testing in selftests and 117``kvm-unit-tests`` will make it easier for the maintainers to review 118and accept your code. In fact, even before you contribute your changes 119upstream it will make it easier for you to develop for KVM. 120 121Of course, the KVM maintainers reserve the right to require more tests, 122though they may also waive the requirement from time to time. 123