sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget./translations/zh_CN/process/maintainer-kvm-x86modnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/zh_TW/process/maintainer-kvm-x86modnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/it_IT/process/maintainer-kvm-x86modnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/ja_JP/process/maintainer-kvm-x86modnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/ko_KR/process/maintainer-kvm-x86modnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/pt_BR/process/maintainer-kvm-x86modnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/sp_SP/process/maintainer-kvm-x86modnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhH/var/lib/git/docbuild/linux/Documentation/process/maintainer-kvm-x86.rsthKubhsection)}(hhh](htitle)}(hKVM x86h]hKVM x86}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hForewordh]hForeword}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXKVM strives to be a welcoming community; contributions from newcomers are valued and encouraged. Please do not be discouraged or intimidated by the length of this document and the many rules/guidelines it contains. Everyone makes mistakes, and everyone was a newbie at some point. So long as you make an honest effort to follow KVM x86's guidelines, are receptive to feedback, and learn from any mistakes you make, you will be welcomed with open arms, not torches and pitchforks.h]hXKVM strives to be a welcoming community; contributions from newcomers are valued and encouraged. Please do not be discouraged or intimidated by the length of this document and the many rules/guidelines it contains. Everyone makes mistakes, and everyone was a newbie at some point. So long as you make an honest effort to follow KVM x86’s guidelines, are receptive to feedback, and learn from any mistakes you make, you will be welcomed with open arms, not torches and pitchforks.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]forewordah ]h"]forewordah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hTL;DRh]hTL;DR}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hJTesting is mandatory. Be consistent with established styles and patterns.h]hJTesting is mandatory. Be consistent with established styles and patterns.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]tl-drah ]h"]tl;drah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hTreesh]hTrees}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj-hhhhhKubh)}(hXKVM x86 is currently in a transition period from being part of the main KVM tree, to being "just another KVM arch". As such, KVM x86 is split across the main KVM tree, ``git.kernel.org/pub/scm/virt/kvm/kvm.git``, and a KVM x86 specific tree, ``github.com/kvm-x86/linux.git``.h](hKVM x86 is currently in a transition period from being part of the main KVM tree, to being “just another KVM arch”. As such, KVM x86 is split across the main KVM tree, }(hj>hhhNhNubhliteral)}(h+``git.kernel.org/pub/scm/virt/kvm/kvm.git``h]h'git.kernel.org/pub/scm/virt/kvm/kvm.git}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhj>ubh, and a KVM x86 specific tree, }(hj>hhhNhNubjG)}(h ``github.com/kvm-x86/linux.git``h]hgithub.com/kvm-x86/linux.git}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhj>ubh.}(hj>hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj-hhubh)}(hXZGenerally speaking, fixes for the current cycle are applied directly to the main KVM tree, while all development for the next cycle is routed through the KVM x86 tree. In the unlikely event that a fix for the current cycle is routed through the KVM x86 tree, it will be applied to the ``fixes`` branch before making its way to the main KVM tree.h](hXGenerally speaking, fixes for the current cycle are applied directly to the main KVM tree, while all development for the next cycle is routed through the KVM x86 tree. In the unlikely event that a fix for the current cycle is routed through the KVM x86 tree, it will be applied to the }(hjrhhhNhNubjG)}(h ``fixes``h]hfixes}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjrubh3 branch before making its way to the main KVM tree.}(hjrhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj-hhubh)}(hyNote, this transition period is expected to last quite some time, i.e. will be the status quo for the foreseeable future.h]hyNote, this transition period is expected to last quite some time, i.e. will be the status quo for the foreseeable future.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK!hj-hhubh)}(hhh](h)}(hBranchesh]hBranches}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK%ubh)}(hXThe KVM x86 tree is organized into multiple topic branches. The purpose of using finer-grained topic branches is to make it easier to keep tabs on an area of development, and to limit the collateral damage of human errors and/or buggy commits, e.g. dropping the HEAD commit of a topic branch has no impact on other in-flight commits' SHA1 hashes, and having to reject a pull request due to bugs delays only that topic branch.h]hXThe KVM x86 tree is organized into multiple topic branches. The purpose of using finer-grained topic branches is to make it easier to keep tabs on an area of development, and to limit the collateral damage of human errors and/or buggy commits, e.g. dropping the HEAD commit of a topic branch has no impact on other in-flight commits’ SHA1 hashes, and having to reject a pull request due to bugs delays only that topic branch.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK&hjhhubh)}(hAll topic branches, except for ``next`` and ``fixes``, are rolled into ``next`` via a Cthulhu merge on an as-needed basis, i.e. when a topic branch is updated. As a result, force pushes to ``next`` are common.h](hAll topic branches, except for }(hjhhhNhNubjG)}(h``next``h]hnext}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh and }(hjhhhNhNubjG)}(h ``fixes``h]hfixes}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh, are rolled into }(hjhhhNhNubjG)}(h``next``h]hnext}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubhn via a Cthulhu merge on an as-needed basis, i.e. when a topic branch is updated. As a result, force pushes to }(hjhhhNhNubjG)}(h``next``h]hnext}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh are common.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK-hjhhubeh}(h]branchesah ]h"]branchesah$]h&]uh1hhj-hhhhhK%ubh)}(hhh](h)}(h Lifecycleh]h Lifecycle}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK2ubh)}(hFixes that target the current release, a.k.a. mainline, are typically applied directly to the main KVM tree, i.e. do not route through the KVM x86 tree.h]hFixes that target the current release, a.k.a. mainline, are typically applied directly to the main KVM tree, i.e. do not route through the KVM x86 tree.}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK3hjhhubh)}(hX}Changes that target the next release are routed through the KVM x86 tree. Pull requests (from KVM x86 to main KVM) are sent for each KVM x86 topic branch, typically the week before Linus' opening of the merge window, e.g. the week following rc7 for "normal" releases. If all goes well, the topic branches are rolled into the main KVM pull request sent during Linus' merge window.h]hXChanges that target the next release are routed through the KVM x86 tree. Pull requests (from KVM x86 to main KVM) are sent for each KVM x86 topic branch, typically the week before Linus’ opening of the merge window, e.g. the week following rc7 for “normal” releases. If all goes well, the topic branches are rolled into the main KVM pull request sent during Linus’ merge window.}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK6hjhhubh)}(hThe KVM x86 tree doesn't have its own official merge window, but there's a soft close around rc5 for new features, and a soft close around rc6 for fixes (for the next release; see above for fixes that target the current release).h]hThe KVM x86 tree doesn’t have its own official merge window, but there’s a soft close around rc5 for new features, and a soft close around rc6 for fixes (for the next release; see above for fixes that target the current release).}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK:``, where ```` is one of::h](hThe preferred prefix format is }(hjbhhhNhNubjG)}(h``KVM: :``h]h KVM: :}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjbubh, where }(hjbhhhNhNubjG)}(h ````h]h}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjbubh is one of:}(hjbhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubh literal_block)}(hI- x86 - x86/mmu - x86/pmu - x86/xen - selftests - SVM - nSVM - VMX - nVMXh]hI- x86 - x86/mmu - x86/pmu - x86/xen - selftests - SVM - nSVM - VMX - nVMX}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjQhhubh)}(h**DO NOT use x86/kvm!** ``x86/kvm`` is used exclusively for Linux-as-a-KVM-guest changes, i.e. for arch/x86/kernel/kvm.c. Do not use file names or complete file paths as the subject/shortlog prefix.h](hstrong)}(h**DO NOT use x86/kvm!**h]hDO NOT use x86/kvm!}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh }(hjhhhNhNubjG)}(h ``x86/kvm``h]hx86/kvm}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh is used exclusively for Linux-as-a-KVM-guest changes, i.e. for arch/x86/kernel/kvm.c. Do not use file names or complete file paths as the subject/shortlog prefix.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubh)}(hjNote, these don't align with the topics branches (the topic branches care much more about code conflicts).h]hlNote, these don’t align with the topics branches (the topic branches care much more about code conflicts).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubh)}(hKAll names are case sensitive! ``KVM: x86:`` is good, ``kvm: vmx:`` is not.h](hAll names are case sensitive! }(hjhhhNhNubjG)}(h ``KVM: x86:``h]h KVM: x86:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh is good, }(hjhhhNhNubjG)}(h ``kvm: vmx:``h]h kvm: vmx:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh is not.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubh)}(hdCapitalize the first word of the condensed patch description, but omit ending punctionation. E.g.::h]hcCapitalize the first word of the condensed patch description, but omit ending punctionation. E.g.:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubj)}(h:KVM: x86: Fix a null pointer dereference in function_xyz()h]h:KVM: x86: Fix a null pointer dereference in function_xyz()}hj"sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjQhhubh)}(hnot::h]hnot:}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubj)}(h9kvm: x86: fix a null pointer dereference in function_xyz.h]h9kvm: x86: fix a null pointer dereference in function_xyz.}hj>sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjQhhubh)}(hIf a patch touches multiple topics, traverse up the conceptual tree to find the first common parent (which is often simply ``x86``). When in doubt, ``git log path/to/file`` should provide a reasonable hint.h](h{If a patch touches multiple topics, traverse up the conceptual tree to find the first common parent (which is often simply }(hjLhhhNhNubjG)}(h``x86``h]hx86}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjLubh). When in doubt, }(hjLhhhNhNubjG)}(h``git log path/to/file``h]hgit log path/to/file}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjLubh" should provide a reasonable hint.}(hjLhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubh)}(hNew topics do occasionally pop up, but please start an on-list discussion if you want to propose introducing a new topic, i.e. don't go rogue.h]hNew topics do occasionally pop up, but please start an on-list discussion if you want to propose introducing a new topic, i.e. don’t go rogue.}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubh)}(hXYSee :ref:`the_canonical_patch_format` for more information, with one amendment: do not treat the 70-75 character limit as an absolute, hard limit. Instead, use 75 characters as a firm-but-not-hard limit, and use 80 characters as a hard limit. I.e. let the shortlog run a few characters over the standard limit if you have good reason to do so.h](hSee }(hjhhhNhNubh)}(h!:ref:`the_canonical_patch_format`h]js)}(hjh]hthe_canonical_patch_format}(hjhhhNhNubah}(h]h ](j~stdstd-refeh"]h$]h&]uh1jrhjubah}(h]h ]h"]h$]h&]refdocj refdomainjreftyperef refexplicitrefwarnjthe_canonical_patch_formatuh1hhhhKhjubhX4 for more information, with one amendment: do not treat the 70-75 character limit as an absolute, hard limit. Instead, use 75 characters as a firm-but-not-hard limit, and use 80 characters as a hard limit. I.e. let the shortlog run a few characters over the standard limit if you have good reason to do so.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubeh}(h]shortlogah ]h"]shortlogah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h Changelogh]h Changelog}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hLMost importantly, write changelogs using imperative mood and avoid pronouns.h]hLMost importantly, write changelogs using imperative mood and avoid pronouns.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXuSee :ref:`describe_changes` for more information, with one amendment: lead with a short blurb on the actual changes, and then follow up with the context and background. Note! This order directly conflicts with the tip tree's preferred approach! Please follow the tip tree's preferred style when sending patches that primarily target arch/x86 code that is _NOT_ KVM code.h](hSee }(hjhhhNhNubh)}(h:ref:`describe_changes`h]js)}(hjh]hdescribe_changes}(hjhhhNhNubah}(h]h ](j~stdstd-refeh"]h$]h&]uh1jrhjubah}(h]h ]h"]h$]h&]refdocj refdomainjreftyperef refexplicitrefwarnjdescribe_changesuh1hhhhKhjubhX^ for more information, with one amendment: lead with a short blurb on the actual changes, and then follow up with the context and background. Note! This order directly conflicts with the tip tree’s preferred approach! Please follow the tip tree’s preferred style when sending patches that primarily target arch/x86 code that is _NOT_ KVM code.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXStating what a patch does before diving into details is preferred by KVM x86 for several reasons. First and foremost, what code is actually being changed is arguably the most important information, and so that info should be easy to find. Changelogs that bury the "what's actually changing" in a one-liner after 3+ paragraphs of background make it very hard to find that information.h]hXStating what a patch does before diving into details is preferred by KVM x86 for several reasons. First and foremost, what code is actually being changed is arguably the most important information, and so that info should be easy to find. Changelogs that bury the “what’s actually changing” in a one-liner after 3+ paragraphs of background make it very hard to find that information.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXFor initial review, one could argue the "what's broken" is more important, but for skimming logs and git archaeology, the gory details matter less and less. E.g. when doing a series of "git blame", the details of each change along the way are useless, the details only matter for the culprit. Providing the "what changed" makes it easy to quickly determine whether or not a commit might be of interest.h]hXFor initial review, one could argue the “what’s broken” is more important, but for skimming logs and git archaeology, the gory details matter less and less. E.g. when doing a series of “git blame”, the details of each change along the way are useless, the details only matter for the culprit. Providing the “what changed” makes it easy to quickly determine whether or not a commit might be of interest.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXAnother benefit of stating "what's changing" first is that it's almost always possible to state "what's changing" in a single sentence. Conversely, all but the most simple bugs require multiple sentences or paragraphs to fully describe the problem. If both the "what's changing" and "what's the bug" are super short then the order doesn't matter. But if one is shorter (almost always the "what's changing), then covering the shorter one first is advantageous because it's less of an inconvenience for readers/reviewers that have a strict ordering preference. E.g. having to skip one sentence to get to the context is less painful than having to skip three paragraphs to get to "what's changing".h]hXAnother benefit of stating “what’s changing” first is that it’s almost always possible to state “what’s changing” in a single sentence. Conversely, all but the most simple bugs require multiple sentences or paragraphs to fully describe the problem. If both the “what’s changing” and “what’s the bug” are super short then the order doesn’t matter. But if one is shorter (almost always the “what’s changing), then covering the shorter one first is advantageous because it’s less of an inconvenience for readers/reviewers that have a strict ordering preference. E.g. having to skip one sentence to get to the context is less painful than having to skip three paragraphs to get to “what’s changing”.}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] changelogah ]h"] changelogah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hFixesh]hFixes}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjIhhhhhKubh)}(hIf a change fixes a KVM/kernel bug, add a Fixes: tag even if the change doesn't need to be backported to stable kernels, and even if the change fixes a bug in an older release.h]hIf a change fixes a KVM/kernel bug, add a Fixes: tag even if the change doesn’t need to be backported to stable kernels, and even if the change fixes a bug in an older release.}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjIhhubh)}(hX<Conversely, if a fix does need to be backported, explicitly tag the patch with "Cc: stable@vger.kernel" (though the email itself doesn't need to Cc: stable); KVM x86 opts out of backporting Fixes: by default. Some auto-selected patches do get backported, but require explicit maintainer approval (search MANUALSEL).h](hVConversely, if a fix does need to be backported, explicitly tag the patch with “Cc: }(hjhhhhNhNubh reference)}(hstable@vger.kernelh]hstable@vger.kernel}(hjrhhhNhNubah}(h]h ]h"]h$]h&]refurimailto:stable@vger.kerneluh1jphjhubh” (though the email itself doesn’t need to Cc: stable); KVM x86 opts out of backporting Fixes: by default. Some auto-selected patches do get backported, but require explicit maintainer approval (search MANUALSEL).}(hjhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjIhhubeh}(h]fixesah ]h"]fixesah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hFunction Referencesh]hFunction References}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hWhen a function is mentioned in a comment, changelog, or shortlog (or anywhere for that matter), use the format ``function_name()``. The parentheses provide context and disambiguate the reference.h](hpWhen a function is mentioned in a comment, changelog, or shortlog (or anywhere for that matter), use the format }(hjhhhNhNubjG)}(h``function_name()``h]hfunction_name()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubhB. The parentheses provide context and disambiguate the reference.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]function-referencesah ]h"]function referencesah$]h&]uh1hhjhhhhhKubeh}(h] developmentah ]h"] developmentah$]h&]uh1hhhhhhhhKSubh)}(hhh](h)}(hTestingh]hTesting}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hX At a bare minimum, *all* patches in a series must build cleanly for KVM_INTEL=m KVM_AMD=m, and KVM_WERROR=y. Building every possible combination of Kconfigs isn't feasible, but the more the merrier. KVM_SMM, KVM_XEN, PROVE_LOCKING, and X86_64 are particularly interesting knobs to turn.h](hAt a bare minimum, }(hjhhhNhNubj)}(h*all*h]hall}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX  patches in a series must build cleanly for KVM_INTEL=m KVM_AMD=m, and KVM_WERROR=y. Building every possible combination of Kconfigs isn’t feasible, but the more the merrier. KVM_SMM, KVM_XEN, PROVE_LOCKING, and X86_64 are particularly interesting knobs to turn.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXRunning KVM selftests and KVM-unit-tests is also mandatory (and stating the obvious, the tests need to pass). The only exception is for changes that have negligible probability of affecting runtime behavior, e.g. patches that only modify comments. When possible and relevant, testing on both Intel and AMD is strongly preferred. Booting an actual VM is encouraged, but not mandatory.h]hXRunning KVM selftests and KVM-unit-tests is also mandatory (and stating the obvious, the tests need to pass). The only exception is for changes that have negligible probability of affecting runtime behavior, e.g. patches that only modify comments. When possible and relevant, testing on both Intel and AMD is strongly preferred. Booting an actual VM is encouraged, but not mandatory.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXWFor changes that touch KVM's shadow paging code, running with TDP (EPT/NPT) disabled is mandatory. For changes that affect common KVM MMU code, running with TDP disabled is strongly encouraged. For all other changes, if the code being modified depends on and/or interacts with a module param, testing with the relevant settings is mandatory.h]hXYFor changes that touch KVM’s shadow paging code, running with TDP (EPT/NPT) disabled is mandatory. For changes that affect common KVM MMU code, running with TDP disabled is strongly encouraged. For all other changes, if the code being modified depends on and/or interacts with a module param, testing with the relevant settings is mandatory.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hNote, KVM selftests and KVM-unit-tests do have known failures. If you suspect a failure is not due to your changes, verify that the *exact same* failure occurs with and without your changes.h](hNote, KVM selftests and KVM-unit-tests do have known failures. If you suspect a failure is not due to your changes, verify that the }(hj"hhhNhNubj)}(h *exact same*h]h exact same}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj"ubh. failure occurs with and without your changes.}(hj"hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hChanges that touch reStructured Text documentation, i.e. .rst files, must build htmldocs cleanly, i.e. with no new warnings or errors.h]hChanges that touch reStructured Text documentation, i.e. .rst files, must build htmldocs cleanly, i.e. with no new warnings or errors.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hIf you can't fully test a change, e.g. due to lack of hardware, clearly state what level of testing you were able to do, e.g. in the cover letter.h]hIf you can’t fully test a change, e.g. due to lack of hardware, clearly state what level of testing you were able to do, e.g. in the cover letter.}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hhh](h)}(h New Featuresh]h New Features}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^hhhhhMubh)}(hXWith one exception, new features *must* come with test coverage. KVM specific tests aren't strictly required, e.g. if coverage is provided by running a sufficiently enabled guest VM, or by running a related kernel selftest in a VM, but dedicated KVM tests are preferred in all cases. Negative testcases in particular are mandatory for enabling of new hardware features as error and exception flows are rarely exercised simply by running a VM.h](h!With one exception, new features }(hjohhhNhNubj)}(h*must*h]hmust}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjoubhX come with test coverage. KVM specific tests aren’t strictly required, e.g. if coverage is provided by running a sufficiently enabled guest VM, or by running a related kernel selftest in a VM, but dedicated KVM tests are preferred in all cases. Negative testcases in particular are mandatory for enabling of new hardware features as error and exception flows are rarely exercised simply by running a VM.}(hjohhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj^hhubh)}(hThe only exception to this rule is if KVM is simply advertising support for a feature via KVM_GET_SUPPORTED_CPUID, i.e. for instructions/features that KVM can't prevent a guest from using and for which there is no true enabling.h]hThe only exception to this rule is if KVM is simply advertising support for a feature via KVM_GET_SUPPORTED_CPUID, i.e. for instructions/features that KVM can’t prevent a guest from using and for which there is no true enabling.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj^hhubh)}(hNote, "new features" does not just mean "new hardware features"! New features that can't be well validated using existing KVM selftests and/or KVM-unit-tests must come with tests.h]hNote, “new features” does not just mean “new hardware features”! New features that can’t be well validated using existing KVM selftests and/or KVM-unit-tests must come with tests.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj^hhubh)}(hX+Posting new feature development without tests to get early feedback is more than welcome, but such submissions should be tagged RFC, and the cover letter should clearly state what type of feedback is requested/expected. Do not abuse the RFC process; RFCs will typically not receive in-depth review.h]hX+Posting new feature development without tests to get early feedback is more than welcome, but such submissions should be tagged RFC, and the cover letter should clearly state what type of feedback is requested/expected. Do not abuse the RFC process; RFCs will typically not receive in-depth review.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM!hj^hhubeh}(h] new-featuresah ]h"] new featuresah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h Bug Fixesh]h Bug Fixes}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM'ubh)}(hXExcept for "obvious" found-by-inspection bugs, fixes must be accompanied by a reproducer for the bug being fixed. In many cases the reproducer is implicit, e.g. for build errors and test failures, but it should still be clear to readers what is broken and how to verify the fix. Some leeway is given for bugs that are found via non-public workloads/tests, but providing regression tests for such bugs is strongly preferred.h]hXExcept for “obvious” found-by-inspection bugs, fixes must be accompanied by a reproducer for the bug being fixed. In many cases the reproducer is implicit, e.g. for build errors and test failures, but it should still be clear to readers what is broken and how to verify the fix. Some leeway is given for bugs that are found via non-public workloads/tests, but providing regression tests for such bugs is strongly preferred.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM(hjhhubh)}(hX In general, regression tests are preferred for any bug that is not trivial to hit. E.g. even if the bug was originally found by a fuzzer such as syzkaller, a targeted regression test may be warranted if the bug requires hitting a one-in-a-million type race condition.h]hX In general, regression tests are preferred for any bug that is not trivial to hit. E.g. even if the bug was originally found by a fuzzer such as syzkaller, a targeted regression test may be warranted if the bug requires hitting a one-in-a-million type race condition.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM/hjhhubh)}(hNote, KVM bugs are rarely urgent *and* non-trivial to reproduce. Ask yourself if a bug is really truly the end of the world before posting a fix without a reproducer.h](h!Note, KVM bugs are rarely urgent }(hjhhhNhNubj)}(h*and*h]hand}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh non-trivial to reproduce. Ask yourself if a bug is really truly the end of the world before posting a fix without a reproducer.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM4hjhhubeh}(h] bug-fixesah ]h"] bug fixesah$]h&]uh1hhjhhhhhM'ubeh}(h]testingah ]h"]testingah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hPostingh]hPosting}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM9ubh)}(hhh](h)}(hLinksh]hLinks}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj/hhhhhM<ubh)}(hXDo not explicitly reference bug reports, prior versions of a patch/series, etc. via ``In-Reply-To:`` headers. Using ``In-Reply-To:`` becomes an unholy mess for large series and/or when the version count gets high, and ``In-Reply-To:`` is useless for anyone that doesn't have the original message, e.g. if someone wasn't Cc'd on the bug report or if the list of recipients changes between versions.h](hTDo not explicitly reference bug reports, prior versions of a patch/series, etc. via }(hj@hhhNhNubjG)}(h``In-Reply-To:``h]h In-Reply-To:}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhj@ubh headers. Using }(hj@hhhNhNubjG)}(h``In-Reply-To:``h]h In-Reply-To:}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhj@ubhV becomes an unholy mess for large series and/or when the version count gets high, and }(hj@hhhNhNubjG)}(h``In-Reply-To:``h]h In-Reply-To:}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhj@ubh is useless for anyone that doesn’t have the original message, e.g. if someone wasn’t Cc’d on the bug report or if the list of recipients changes between versions.}(hj@hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM=hj/hhubh)}(hXTo link to a bug report, previous version, or anything of interest, use lore links. For referencing previous version(s), generally speaking do not include a Link: in the changelog as there is no need to record the history in git, i.e. put the link in the cover letter or in the section git ignores. Do provide a formal Link: for bug reports and/or discussions that led to the patch. The context of why a change was made is highly valuable for future readers.h]hXTo link to a bug report, previous version, or anything of interest, use lore links. For referencing previous version(s), generally speaking do not include a Link: in the changelog as there is no need to record the history in git, i.e. put the link in the cover letter or in the section git ignores. Do provide a formal Link: for bug reports and/or discussions that led to the patch. The context of why a change was made is highly valuable for future readers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMDhj/hhubeh}(h]linksah ]h"]linksah$]h&]uh1hhjhhhhhM<ubh)}(hhh](h)}(hGit Baseh]hGit Base}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMLubh)}(hIf you are using git version 2.9.0 or later (Googlers, this is all of you!), use ``git format-patch`` with the ``--base`` flag to automatically include the base tree information in the generated patches.h](hQIf you are using git version 2.9.0 or later (Googlers, this is all of you!), use }(hjhhhNhNubjG)}(h``git format-patch``h]hgit format-patch}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh with the }(hjhhhNhNubjG)}(h ``--base``h]h--base}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubhR flag to automatically include the base tree information in the generated patches.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMMhjhhubh)}(hX@Note, ``--base=auto`` works as expected if and only if a branch's upstream is set to the base topic branch, e.g. it will do the wrong thing if your upstream is set to your personal repository for backup purposes. An alternative "auto" solution is to derive the names of your development branches based on their KVM x86 topic, and feed that into ``--base``. E.g. ``x86/pmu/my_branch_name``, and then write a small wrapper to extract ``pmu`` from the current branch name to yield ``--base=x/pmu``, where ``x`` is whatever name your repository uses to track the KVM x86 remote.h](hNote, }(hjhhhNhNubjG)}(h``--base=auto``h]h --base=auto}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubhXK works as expected if and only if a branch’s upstream is set to the base topic branch, e.g. it will do the wrong thing if your upstream is set to your personal repository for backup purposes. An alternative “auto” solution is to derive the names of your development branches based on their KVM x86 topic, and feed that into }(hjhhhNhNubjG)}(h ``--base``h]h--base}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh. E.g. }(hjhhhNhNubjG)}(h``x86/pmu/my_branch_name``h]hx86/pmu/my_branch_name}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh,, and then write a small wrapper to extract }(hjhhhNhNubjG)}(h``pmu``h]hpmu}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh' from the current branch name to yield }(hjhhhNhNubjG)}(h``--base=x/pmu``h]h --base=x/pmu}(hj- hhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubh, where }(hjhhhNhNubjG)}(h``x``h]hx}(hj? hhhNhNubah}(h]h ]h"]h$]h&]uh1jFhjubhC is whatever name your repository uses to track the KVM x86 remote.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMQhjhhubeh}(h]git-baseah ]h"]git baseah$]h&]uh1hhjhhhhhMLubh)}(hhh](h)}(hCo-Posting Testsh]hCo-Posting Tests}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj_ hhhhhM[ubh)}(hXKVM selftests that are associated with KVM changes, e.g. regression tests for bug fixes, should be posted along with the KVM changes as a single series. The standard kernel rules for bisection apply, i.e. KVM changes that result in test failures should be ordered after the selftests updates, and vice versa, new tests that fail due to KVM bugs should be ordered after the KVM fixes.h]hXKVM selftests that are associated with KVM changes, e.g. regression tests for bug fixes, should be posted along with the KVM changes as a single series. The standard kernel rules for bisection apply, i.e. KVM changes that result in test failures should be ordered after the selftests updates, and vice versa, new tests that fail due to KVM bugs should be ordered after the KVM fixes.}(hjp hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM\hj_ hhubh)}(hXjKVM-unit-tests should *always* be posted separately. Tools, e.g. b4 am, don't know that KVM-unit-tests is a separate repository and get confused when patches in a series apply on different trees. To tie KVM-unit-tests patches back to KVM patches, first post the KVM changes and then provide a lore Link: to the KVM patch/series in the KVM-unit-tests patch(es).h](hKVM-unit-tests should }(hj~ hhhNhNubj)}(h*always*h]halways}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj~ ubhXN be posted separately. Tools, e.g. b4 am, don’t know that KVM-unit-tests is a separate repository and get confused when patches in a series apply on different trees. To tie KVM-unit-tests patches back to KVM patches, first post the KVM changes and then provide a lore Link: to the KVM patch/series in the KVM-unit-tests patch(es).}(hj~ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMbhj_ hhubeh}(h]co-posting-testsah ]h"]co-posting testsah$]h&]uh1hhjhhhhhM[ubeh}(h]postingah ]h"]postingah$]h&]uh1hhhhhhhhM9ubh)}(hhh](h)}(h Notificationsh]h Notifications}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMiubh)}(hXWhen a patch/series is officially accepted, a notification email will be sent in reply to the original posting (cover letter for multi-patch series). The notification will include the tree and topic branch, along with the SHA1s of the commits of applied patches.h]hXWhen a patch/series is officially accepted, a notification email will be sent in reply to the original posting (cover letter for multi-patch series). The notification will include the tree and topic branch, along with the SHA1s of the commits of applied patches.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMjhj hhubh)}(hIf a subset of patches is applied, this will be clearly stated in the notification. Unless stated otherwise, it's implied that any patches in the series that were not accepted need more work and should be submitted in a new version.h]hIf a subset of patches is applied, this will be clearly stated in the notification. Unless stated otherwise, it’s implied that any patches in the series that were not accepted need more work and should be submitted in a new version.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMohj hhubh)}(hIf for some reason a patch is dropped after officially being accepted, a reply will be sent to the notification email explaining why the patch was dropped, as well as the next steps.h]hIf for some reason a patch is dropped after officially being accepted, a reply will be sent to the notification email explaining why the patch was dropped, as well as the next steps.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMthj hhubh)}(hhh](h)}(hSHA1 Stabilityh]hSHA1 Stability}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMyubh)}(hXySHA1s are not 100% guaranteed to be stable until they land in Linus' tree! A SHA1 is *usually* stable once a notification has been sent, but things happen. In most cases, an update to the notification email be provided if an applied patch's SHA1 changes. However, in some scenarios, e.g. if all KVM x86 branches need to be rebased, individual notifications will not be given.h](hXSHA1s are not 100% guaranteed to be stable until they land in Linus’ tree! A SHA1 is }(hj hhhNhNubj)}(h *usually*h]husually}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhX stable once a notification has been sent, but things happen. In most cases, an update to the notification email be provided if an applied patch’s SHA1 changes. However, in some scenarios, e.g. if all KVM x86 branches need to be rebased, individual notifications will not be given.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMzhj hhubeh}(h]sha1-stabilityah ]h"]sha1 stabilityah$]h&]uh1hhj hhhhhMyubeh}(h] notificationsah ]h"] notificationsah$]h&]uh1hhhhhhhhMiubh)}(hhh](h)}(hVulnerabilitiesh]hVulnerabilities}(hj- hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj* hhhhhMubh)}(hX-Bugs that can be exploited by the guest to attack the host (kernel or userspace), or that can be exploited by a nested VM to *its* host (L2 attacking L1), are of particular interest to KVM. Please follow the protocol for :ref:`securitybugs` if you suspect a bug can lead to an escape, data leak, etc.h](h}Bugs that can be exploited by the guest to attack the host (kernel or userspace), or that can be exploited by a nested VM to }(hj; hhhNhNubj)}(h*its*h]hits}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj; ubh\ host (L2 attacking L1), are of particular interest to KVM. Please follow the protocol for }(hj; hhhNhNubh)}(h:ref:`securitybugs`h]js)}(hjW h]h securitybugs}(hjY hhhNhNubah}(h]h ](j~stdstd-refeh"]h$]h&]uh1jrhjU ubah}(h]h ]h"]h$]h&]refdocj refdomainjc reftyperef refexplicitrefwarnj securitybugsuh1hhhhMhj; ubh< if you suspect a bug can lead to an escape, data leak, etc.}(hj; hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj* hhubeh}(h]vulnerabilitiesah ]h"]vulnerabilitiesah$]h&]uh1hhhhhhhhMubeh}(h]kvm-x86ah ]h"]kvm x86ah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j j jjj*j'jjjjj]jZjjjjjDjAjjjjjNjKjjjFjCjjjjjjjjjjj j jjj\ jY j j j' j$ j j j j u nametypes}(j jj*jjj]jjjDjjjNjjFjjjjjj jj\ j j' j j uh}(j hjhj'jjj-jjjZjjj`jjjAjjjGjjjKjjjQjCjjjIjjjjjj^jjj jjj/jY jj j_ j$ j j j j j* u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.