Documentation/process/maintainer-kvm-x86.rst

3 KVM x86
8 KVM strives to be a welcoming community; contributions from newcomers are
12 an honest effort to follow KVM x86's guidelines, are receptive to feedback,
22 KVM x86 is currently in a transition period from being part of the main KVM
23 tree, to being "just another KVM arch".  As such, KVM x86 is split across the
24 main KVM tree, ``git.kernel.org/pub/scm/virt/kvm/kvm.git``, and a KVM x86
28 main KVM tree, while all development for the next cycle is routed through the
29 KVM x86 tree.  In the unlikely event that a fix for the current cycle is routed
30 through the KVM x86 tree, it will be applied to the ``fixes`` branch before
31 making its way to the main KVM tree.
38 The KVM x86 tree is organized into multiple topic branches.  The purpose of
52 directly to the main KVM tree, i.e. do not route through the KVM x86 tree.
54 Changes that target the next release are routed through the KVM x86 tree.  Pull
55 requests (from KVM x86 to main KVM) are sent for each KVM x86 topic branch,
58 rolled into the main KVM pull request sent during Linus' merge window.
60 The KVM x86 tree doesn't have its own official merge window, but there's a soft
69 Patches that will be taken through a non-KVM tree (most often through the tip
99 is a multi-arch series, i.e. has non-trivial modifications to common KVM code
101 arch patch/series should instead be based on a common, stable point in KVM's
109 priority in KVM x86.  If all else fails, match what already exists.
112 :ref:`maintainer-tip-coding-style`, as patches/series often touch both KVM and
113 non-KVM x86 files, i.e. draw the attention of KVM *and* tip tree maintainers.
119 functions.  The vast majority of "public" KVM functions aren't truly public as
120 they are intended only for KVM-internal consumption (there are plans to
121 privatize KVM's headers and exports to enforce this).
132 Much of KVM's code base is directly tied to architectural behavior defined in
143 APM in comments.  With few exceptions, KVM *must* honor architectural behavior,
144 therefore it's implied that KVM behavior is emulating SDM and/or APM behavior.
150 The preferred prefix format is ``KVM: <topic>:``, where ``<topic>`` is one of::
162 **DO NOT use x86/kvm!**  ``x86/kvm`` is used exclusively for Linux-as-a-KVM-guest
169 All names are case sensitive!  ``KVM: x86:`` is good, ``kvm: vmx:`` is not.
174     KVM: x86: Fix a null pointer dereference in function_xyz()
201 that primarily target arch/x86 code that is _NOT_ KVM code.
203 Stating what a patch does before diving into details is preferred by KVM x86
228 If a change fixes a KVM/kernel bug, add a Fixes: tag even if the change doesn't
234 KVM x86 opts out of backporting Fixes: by default.  Some auto-selected patches
250 Running KVM selftests and KVM-unit-tests is also mandatory (and stating the
256 For changes that touch KVM's shadow paging code, running with TDP (EPT/NPT)
257 disabled is mandatory.  For changes that affect common KVM MMU code, running
262 Note, KVM selftests and KVM-unit-tests do have known failures.  If you suspect
274 With one exception, new features *must* come with test coverage.  KVM specific
277 but dedicated KVM tests are preferred in all cases.  Negative testcases in
281 The only exception to this rule is if KVM is simply advertising support for a
282 feature via KVM_GET_SUPPORTED_CPUID, i.e. for instructions/features that KVM
286 that can't be well validated using existing KVM selftests and/or KVM-unit-tests
308 Note, KVM bugs are rarely urgent *and* non-trivial to reproduce.  Ask yourself
341 KVM x86 topic, and feed that into ``--base``.  E.g. ``x86/pmu/my_branch_name``,
344 track the KVM x86 remote.
348 KVM selftests that are associated with KVM changes, e.g. regression tests for
349 bug fixes, should be posted along with the KVM changes as a single series.  The
350 standard kernel rules for bisection apply, i.e. KVM changes that result in test
352 tests that fail due to KVM bugs should be ordered after the KVM fixes.
354 KVM-unit-tests should *always* be posted separately.  Tools, e.g. b4 am, don't
355 know that KVM-unit-tests is a separate repository and get confused when patches
356 in a series apply on different trees.  To tie KVM-unit-tests patches back to
357 KVM patches, first post the KVM changes and then provide a lore Link: to the
358 KVM patch/series in the KVM-unit-tests patch(es).
381 patch's SHA1 changes.  However, in some scenarios, e.g. if all KVM x86 branches
388 L1), are of particular interest to KVM.  Please follow the protocol for