요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
Base, style와 architecture manual 인용
maintainer-kvm-x86.rst:82-147Patch는 maintainer가 지정한 KVM x86 base에 만들고 generic kernel coding style에 더해 주변 virtualization code convention을 따른다. Comment는 instruction behavior를 반복하지 말고 virtualization invariant와 guest·host interaction 이유를 설명한다.
Intel SDM과 AMD APM을 인용할 때 document volume, section과 가능하면 stable title을 적어 reviewer가 architectural rule을 확인할 수 있게 한다. Vendor 문구만으로 Linux behavior를 정당화하지 말고 KVM state model에 연결한다.
Shortlog, changelog와 Fixes
maintainer-kvm-x86.rst:148-242Subject는 KVM: x86 또는 더 구체적인 vendor·component prefix를 사용하고 무엇을 왜 바꾸는지 표시한다. Changelog는 guest-visible symptom, root cause, affected mode, concurrency와 migration·nested virtualization 영향을 설명한다.
Bug를 도입한 commit에는 정확한 Fixes tag를 붙이고 stable backport 가능성을 평가한다. Function을 언급할 때 parenthesis를 붙여 symbol임을 명확히 하고 code quote보다 invariant를 중심으로 쓴다.
KVM selftest와 feature 검증
maintainer-kvm-x86.rst:243-311관련 KVM selftest, kvm-unit-tests와 guest workload를 실행하고 Intel·AMD, hardware feature on·off, nested guest와 migration처럼 영향 matrix를 확인한다. New feature는 userspace API와 capability discovery, backward compatibility, documentation과 test를 같은 series에 포함한다.
Bug fix는 재현 test를 먼저 또는 함께 제공하고 test가 old code에서 실패하고 fix 뒤 성공하는지 보여 준다. Hardware가 없어 실행하지 못한 조합은 명시한다.
Posting, base와 notification
maintainer-kvm-x86.rst:312-390관련 lore discussion과 dependency를 Link로 연결하고 git format-patch base-commit 정보를 제공한다. Selftest와 code를 다른 tree가 받는 경우에도 같은 thread에 co-post해 review context를 유지한다.
Maintainer tree에서 commit SHA가 안정되기 전에는 외부 dependency가 hash에 기대지 않게 한다. Vulnerability는 public posting 전에 kernel security process를 따르고 disclosure 뒤 fix·stable 흐름을 연결한다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
KVM x86
=======
Foreword
--------
KVM 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.
TL;DR
-----
Testing is mandatory. Be consistent with established styles and patterns.
Trees
-----
KVM 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``.
Generally 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.
Note, this transition period is expected to last quite some time, i.e. will be
the status quo for the foreseeable future.
Branches
~~~~~~~~
The 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.
All 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.
Lifecycle
~~~~~~~~~
Fixes 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.
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.
The 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).
Timeline
~~~~~~~~
Submissions are typically reviewed and applied in FIFO order, with some wiggle
room for the size of a series, patches that are "cache hot", etc. Fixes,
especially for the current release and or stable trees, get to jump the queue.
Patches that will be taken through a non-KVM tree (most often through the tip
tree) and/or have other acks/reviews also jump the queue to some extent.
Note, the vast majority of review is done between rc1 and rc6, give or take.
The period between rc6 and the next rc1 is used to catch up on other tasks,
i.e. radio silence during this period isn't unusual.
Pings to get a status update are welcome, but keep in mind the timing of the
current release cycle and have realistic expectations. If you are pinging for
acceptance, i.e. not just for feedback or an update, please do everything you
can, within reason, to ensure that your patches are ready to be merged! Pings
on series that break the build or fail tests lead to unhappy maintainers!
Development
-----------
Base Tree/Branch
~~~~~~~~~~~~~~~~
Fixes that target the current release, a.k.a. mainline, should be based on
``git://git.kernel.org/pub/scm/virt/kvm/kvm.git master``. Note, fixes do not
automatically warrant inclusion in the current release. There is no singular
rule, but typically only fixes for bugs that are urgent, critical, and/or were
introduced in the current release should target the current release.
Everything else should be based on ``kvm-x86/next``, i.e. there is no need to
select a specific topic branch as the base. If there are conflicts and/or
dependencies across topic branches, it is the maintainer's job to sort them
out.
The only exception to using ``kvm-x86/next`` as the base is if a patch/series
is a multi-arch series, i.e. has non-trivial modifications to common KVM code
and/or has more than superficial changes to other architectures' code. Multi-
arch patch/series should instead be based on a common, stable point in KVM's
history, e.g. the release candidate upon which ``kvm-x86 next`` is based. If
you're unsure whether a patch/series is truly multi-arch, err on the side of
caution and treat it as multi-arch, i.e. use a common base.
Coding Style
~~~~~~~~~~~~
When it comes to style, naming, patterns, etc., consistency is the number one
priority in KVM x86. If all else fails, match what already exists.
With a few caveats listed below, follow the tip tree maintainers' preferred
:ref:`maintainer-tip-coding-style`, as patches/series often touch both KVM and
non-KVM x86 files, i.e. draw the attention of KVM *and* tip tree maintainers.
Using reverse fir tree, a.k.a. reverse Christmas tree or reverse XMAS tree, for
variable declarations isn't strictly required, though it is still preferred.
Except for a handful of special snowflakes, do not use kernel-doc comments for
functions. The vast majority of "public" KVM functions aren't truly public as
they are intended only for KVM-internal consumption (there are plans to
privatize KVM's headers and exports to enforce this).
Comments
~~~~~~~~
Write comments using imperative mood and avoid pronouns. Use comments to
provide a high level overview of the code, and/or to explain why the code does
what it does. Do not reiterate what the code literally does; let the code
speak for itself. If the code itself is inscrutable, comments will not help.
SDM and APM References
~~~~~~~~~~~~~~~~~~~~~~
Much of KVM's code base is directly tied to architectural behavior defined in
Intel's Software Development Manual (SDM) and AMD's Architecture Programmer’s
Manual (APM). Use of "Intel's SDM" and "AMD's APM", or even just "SDM" or
"APM", without additional context is a-ok.
Do not reference specific sections, tables, figures, etc. by number, especially
not in comments. Instead, if necessary (see below), copy-paste the relevant
snippet and reference sections/tables/figures by name. The layouts of the SDM
and APM are constantly changing, and so the numbers/labels aren't stable.
Generally speaking, do not explicitly reference or copy-paste from the SDM or
APM in comments. With few exceptions, KVM *must* honor architectural behavior,
therefore it's implied that KVM behavior is emulating SDM and/or APM behavior.
Note, referencing the SDM/APM in changelogs to justify the change and provide
context is perfectly ok and encouraged.
Shortlog
~~~~~~~~
The preferred prefix format is ``KVM: <topic>:``, where ``<topic>`` is one of::
- x86
- x86/mmu
- x86/pmu
- x86/xen
- selftests
- SVM
- nSVM
- VMX
- nVMX
**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.
Note, these don't align with the topics branches (the topic branches care much
more about code conflicts).
All names are case sensitive! ``KVM: x86:`` is good, ``kvm: vmx:`` is not.
Capitalize the first word of the condensed patch description, but omit ending
punctionation. E.g.::
KVM: x86: Fix a null pointer dereference in function_xyz()
not::
kvm: x86: fix a null pointer dereference in function_xyz.
If 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.
New 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.
See :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.
Changelog
~~~~~~~~~
Most importantly, write changelogs using imperative mood and avoid pronouns.
See :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.
Stating 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.
For 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.
Another 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".
Fixes
~~~~~
If 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.
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).
Function References
~~~~~~~~~~~~~~~~~~~
When 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.
Testing
-------
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.
Running 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.
For 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.
Note, 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.
Changes that touch reStructured Text documentation, i.e. .rst files, must build
htmldocs cleanly, i.e. with no new warnings or errors.
If 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.
New Features
~~~~~~~~~~~~
With 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.
The 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.
Note, "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.
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.
Bug Fixes
~~~~~~~~~
Except 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.
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.
Note, 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.
Posting
-------
Links
~~~~~
Do 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.
To 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.
Git Base
~~~~~~~~
If 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.
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.
Co-Posting Tests
~~~~~~~~~~~~~~~~
KVM 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.
KVM-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).
Notifications
-------------
When 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.
If 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.
If 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.
SHA1 Stability
~~~~~~~~~~~~~~
SHA1s 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.
Vulnerabilities
---------------
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.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
KVM x86 contribution의 기본 태도
1-19KVM은 newcomer의 기여를 소중히 여기고 장려하는 열린 community를 지향한다. 이 문서의 길이와 많은 규칙에 위축될 필요는 없다. 누구나 실수하며 모두 한때 beginner였다. KVM x86 guideline을 따르려고 성실히 노력하고 feedback을 받아들이며 실수에서 배운다면 환영받는다.
요약하면 testing은 필수이며 기존 style과 pattern에 일관되게 맞춰야 한다.
KVM tree와 KVM x86 tree
20-47KVM x86은 main KVM tree의 일부에서 “또 하나의 KVM architecture”로 전환하는 중이다. 따라서 main KVM tree와 KVM x86 전용 tree에 나뉜다.
git.kernel.org/pub/scm/virt/kvm/kvm.git
github.com/kvm-x86/linux.git일반적으로 현재 cycle의 fix는 main KVM tree에 직접 적용하고 다음 cycle 개발은 모두 KVM x86 tree를 거친다. 드물게 현재 cycle fix가 KVM x86 tree를 거치면 fixes branch에 적용한 뒤 main KVM tree로 보낸다. 이 전환 상태는 예측 가능한 미래 동안 계속될 것으로 본다.
KVM x86 tree는 여러 topic branch로 구성한다. 세분화된 branch는 개발 영역을 추적하기 쉽고 사람의 실수나 buggy commit의 부수 피해를 제한한다. Topic branch HEAD를 drop해도 다른 in-flight commit SHA1은 바뀌지 않으며 bug 때문에 pull request를 거절해도 해당 topic branch만 지연된다.
next와 fixes를 제외한 topic branch는 갱신될 때 필요에 따라 Cthulhu merge로 next에 합친다. 따라서 next에 대한 force push는 흔하다.
Release cycle과 review timeline
49-80현재 mainline release용 fix는 보통 KVM x86 tree를 거치지 않고 main KVM tree에 직접 적용한다. 다음 release용 change는 KVM x86 tree를 거친다. KVM x86의 각 topic branch는 보통 Linus가 merge window를 열기 전 주, 일반 release라면 rc7 다음 주에 main KVM으로 pull request를 보낸다. 문제가 없으면 Linus의 merge window 동안 main KVM pull request에 topic branch가 합쳐진다.
KVM x86 tree에 공식 merge window는 없지만 새 feature는 rc5 무렵, 다음 release용 fix는 rc6 무렵 soft close된다.
Submission은 대체로 FIFO로 review하고 적용하지만 series 크기, reviewer cache에 아직 내용이 남은 patch 등은 조정할 수 있다. 현재 release 또는 stable tree용 fix는 우선 처리한다. Non-KVM tree, 흔히 tip tree를 통해 들어가거나 다른 ack/review가 있는 patch도 어느 정도 우선한다.
Review 대부분은 대략 rc1부터 rc6 사이에 수행한다. rc6부터 다음 rc1까지는 다른 작업을 따라잡는 기간이어서 응답이 없는 일이 드물지 않다. Status ping은 가능하지만 현재 release cycle을 고려해 현실적인 기대를 가져야 한다. 단순 feedback이 아니라 acceptance를 요청한다면 merge 준비를 최대한 마쳐야 한다. Build나 test를 깨뜨리는 series에 대한 ping은 maintainer를 불쾌하게 한다.
Patch base tree와 multi-arch 예외
82-104현재 mainline release를 대상으로 하는 fix는 다음 master를 기준으로 한다.
git://git.kernel.org/pub/scm/virt/kvm/kvm.git masterFix라고 해서 현재 release에 자동으로 포함되는 것은 아니다. 단일 규칙은 없지만 대개 urgent, critical하거나 현재 release에서 도입된 bug의 fix만 현재 release를 대상으로 한다.
그 밖의 모든 change는 kvm-x86/next를 기준으로 한다. 특정 topic branch를 base로 고를 필요가 없으며 topic branch 사이 conflict와 dependency는 maintainer가 해결한다.
예외는 common KVM code를 사소하지 않게 수정하거나 다른 architecture code에 표면적 수준을 넘는 change가 있는 multi-arch series다. 이런 series는 kvm-x86/next가 기반으로 삼은 release candidate처럼 KVM history의 공통 stable point를 base로 한다. Multi-arch인지 확신이 없다면 보수적으로 common base를 사용한다.
Coding style, comment, SDM/APM reference
106-146KVM x86에서 style, naming, pattern의 최우선 기준은 일관성이다. 다른 판단 기준이 없으면 이미 존재하는 code에 맞춘다. 몇 가지 예외를 제외하면 patch가 KVM과 non-KVM x86 file을 함께 수정하는 경우가 많으므로 tip tree maintainer의 coding style을 따른다.
Variable declaration의 reverse fir tree, reverse Christmas tree 또는 reverse XMAS tree style은 엄격한 필수는 아니지만 선호한다. 일부 특별한 경우를 제외하고 function에 kernel-doc comment를 쓰지 않는다. Public처럼 보이는 KVM function 대부분은 KVM 내부에서만 사용하며 header와 export를 private로 바꿀 계획이 있기 때문이다.
Comment는 imperative mood로 쓰고 pronoun을 피한다. Code의 high-level overview 또는 왜 그렇게 동작하는지를 설명한다. Code가 문자 그대로 무엇을 하는지는 반복하지 않는다. Code 자체가 이해 불가능하다면 comment로 해결할 수 없다.
KVM code 상당 부분은 Intel Software Development Manual(SDM)과 AMD Architecture Programmer's Manual(APM)의 architecture behavior에 직접 연결된다. 추가 맥락 없이 Intel's SDM, AMD's APM 또는 SDM/APM이라고 써도 된다.
특정 section, table, figure 번호를 reference하지 않는다. SDM과 APM layout이 계속 바뀌어 번호와 label이 안정적이지 않다. 꼭 필요하면 관련 snippet을 인용하고 이름으로 reference한다. 일반적으로 comment에서 SDM/APM을 명시하거나 copy-paste하지 않는다. KVM은 당연히 architecture behavior를 따라야 하기 때문이다. 다만 changelog에서 change 근거와 context로 SDM/APM을 reference하는 것은 권장한다.
Shortlog prefix와 길이
148-191권장 prefix는 KVM: <topic>: 형식이다.
- x86
- x86/mmu
- x86/pmu
- x86/xen
- selftests
- SVM
- nSVM
- VMX
- nVMX
x86/kvm은 사용하면 안 된다. 이 prefix는 arch/x86/kernel/kvm.c처럼 Linux가 KVM guest로 동작하는 change에만 사용한다. File name이나 전체 path도 subject/shortlog prefix로 쓰지 않는다. Shortlog topic은 code conflict 중심의 topic branch 이름과 일치하지 않을 수 있다.
모든 이름은 case-sensitive다. KVM: x86:은 맞고 kvm: vmx:은 틀리다. 압축된 patch description의 첫 단어는 대문자로 시작하고 끝 punctuation은 생략한다.
KVM: x86: Fix a null pointer dereference in function_xyz()
# 잘못된 예
kvm: x86: fix a null pointer dereference in function_xyz.여러 topic을 수정하면 conceptual tree에서 첫 common parent까지 올라가며 흔히 x86이 된다. 확신이 없으면 git log path/to/file이 단서를 준다. 새 topic을 제안하려면 독단적으로 사용하지 말고 list에서 먼저 논의한다.
Canonical patch format을 따르되 70~75 character를 절대 제한으로 보지 않는다. 75는 강하지만 넘을 수 있는 제한, 80은 hard limit다. 좋은 이유가 있으면 standard보다 몇 character 길어도 된다.
Changelog, Fixes, function reference
193-241Changelog도 imperative mood로 쓰고 pronoun을 피한다. 먼저 실제 change를 짧게 설명한 뒤 context와 background를 적는다. 이 순서는 tip tree의 선호와 반대다. 주 대상이 KVM이 아닌 arch/x86 code라면 tip tree style을 따른다.
무엇을 바꾸는지가 가장 중요한 정보이므로 쉽게 찾을 수 있어야 한다. Background 세 문단 뒤 한 줄에 change를 숨기면 찾기 어렵다. Initial review에서는 무엇이 깨졌는지가 더 중요할 수 있지만 log 훑기와 git archaeology에서는 자세한 background의 중요성이 줄어든다. 연속 git blame에서는 culprit commit을 제외한 각 change의 상세한 문제 설명보다 실제 change를 빨리 판별하는 정보가 유용하다.
무엇을 바꾸는지는 거의 항상 한 문장으로 쓸 수 있지만 단순하지 않은 bug는 여러 문장이나 문단이 필요하다. 짧은 내용을 먼저 쓰면 특정 순서를 선호하는 reader도 한 문장만 건너뛰면 되어 부담이 적다.
KVM/kernel bug를 고치면 stable backport가 필요 없거나 오래된 release의 bug라도 Fixes tag를 추가한다. 반대로 backport가 필요하면 patch에 Cc: stable@vger.kernel을 명시한다. Email 자체에 stable을 Cc할 필요는 없다. KVM x86은 Fixes tag만으로 자동 backport하는 동작을 기본 거부한다. 일부 auto-selected patch도 maintainer의 명시적 승인, 즉 MANUALSEL이 필요하다.
Comment, changelog, shortlog 등 어디서든 function을 언급할 때 function_name() 형식을 사용한다. Parenthesis가 context를 제공하고 다른 reference와 구분한다.
필수 build와 runtime test
243-270최소한 series의 모든 patch는 다음 설정에서 warning/error 없이 build되어야 한다.
KVM_INTEL=m
KVM_AMD=m
KVM_WERROR=y모든 Kconfig 조합 build는 불가능하지만 많을수록 좋다. KVM_SMM, KVM_XEN, PROVE_LOCKING, X86_64는 특히 유용한 option이다.
KVM selftests와 KVM-unit-tests 실행 및 통과도 필수다. Runtime behavior에 영향을 줄 가능성이 무시할 만큼 작은 comment-only patch 정도만 예외다. 가능하고 관련이 있다면 Intel과 AMD 양쪽에서 test하는 것을 강하게 선호한다. 실제 VM boot는 권장하지만 필수는 아니다.
KVM shadow paging code를 수정하면 TDP(EPT/NPT)를 끈 상태의 test가 필수다. Common KVM MMU code를 수정하면 TDP disabled test를 강하게 권장한다. 다른 change도 수정 code가 module parameter에 의존하거나 상호 작용하면 관련 설정의 test가 필수다.
KVM selftests와 KVM-unit-tests에는 알려진 failure가 있다. 자신의 change 때문이 아니라고 생각한다면 change 전후에 정확히 같은 failure가 발생하는지 확인한다. reStructuredText .rst를 수정하면 새 warning이나 error 없이 htmldocs가 build되어야 한다. Hardware 부족 등으로 완전히 test할 수 없다면 cover letter에 수행한 test 수준을 명확히 적는다.
새 feature의 test coverage
272-292한 가지 예외를 제외하면 새 feature에는 반드시 test coverage가 있어야 한다. 충분히 enable된 guest VM 실행이나 VM 안의 관련 kernel selftest로 coverage를 제공할 수 있어 KVM 전용 test가 절대 필수는 아니지만 언제나 dedicated KVM test를 선호한다.
새 hardware feature enable에는 negative testcase가 필수다. 단순 VM 실행으로 error와 exception flow가 거의 실행되지 않기 때문이다.
유일한 예외는 KVM_GET_SUPPORTED_CPUID를 통해 support를 알리기만 하는 feature다. KVM이 guest 사용을 막을 수 없고 실제 enable 동작도 없는 instruction/feature가 이에 해당한다.
새 feature는 새 hardware feature만 뜻하지 않는다. 기존 KVM selftests 또는 KVM-unit-tests로 충분히 검증할 수 없는 모든 새 기능에 test가 필요하다.
Early feedback을 위해 test 없이 새 feature 개발을 게시하는 것은 환영하지만 RFC tag를 붙이고 cover letter에 원하는 feedback 종류를 명확히 적어야 한다. RFC 절차를 남용해서는 안 되며 RFC는 보통 깊은 review를 받지 않는다.
Bug fix reproducer와 regression test
294-310Code inspection만으로 명백한 bug를 제외하면 fix에는 reproducer가 있어야 한다. Build error와 test failure처럼 reproducer가 암묵적인 경우도 있지만 무엇이 깨졌고 fix를 어떻게 검증하는지 reader가 명확히 알아야 한다.
Non-public workload/test에서 찾은 bug에는 어느 정도 예외를 허용하지만 regression test 제공을 강하게 선호한다. 일반적으로 쉽게 재현되지 않는 모든 bug에는 regression test가 좋다. Syzkaller 같은 fuzzer가 처음 찾았더라도 백만 번에 한 번 생기는 race라면 targeted regression test가 필요할 수 있다.
KVM bug가 긴급하면서 동시에 재현하기 어려운 경우는 드물다. Reproducer 없이 fix를 게시하기 전에 정말 세상이 끝날 만큼 긴급한지 자문한다.
Lore link와 git base 정보
312-344Bug report나 이전 patch/series version을 In-Reply-To header로 직접 reference하지 않는다. 큰 series나 version 수가 많으면 thread가 복잡해지고, original message를 받지 못했거나 version 사이 recipient가 바뀐 사람에게는 In-Reply-To가 쓸모없다.
Bug report, 이전 version 또는 관련 정보는 lore link를 사용한다. 이전 version link는 git history에 기록할 필요가 없으므로 보통 changelog의 formal Link tag로 넣지 않고 cover letter 또는 git이 무시하는 영역에 둔다. Bug report나 patch로 이어진 discussion에는 formal Link를 제공한다. Change 이유의 context는 미래 reader에게 매우 가치 있다.
Git 2.9.0 이상에서는 git format-patch --base로 generated patch에 base tree 정보를 자동 포함한다.
git format-patch --base=<base-commit-or-branch>--base=auto는 branch upstream이 base topic branch로 설정된 경우에만 올바르게 동작한다. Backup용 personal repository를 upstream으로 두면 잘못된 결과를 낸다. 대안은 development branch 이름을 KVM x86 topic에 맞추고 wrapper가 이름에서 topic을 추출해 --base에 넘기는 것이다. 예를 들어 x86/pmu/my_branch_name에서 pmu를 추출하여 --base=x/pmu를 만들 수 있다. x는 local repository에서 KVM x86 remote를 추적하는 이름이다.
KVM selftests와 KVM-unit-tests 게시 순서
346-358KVM bug fix의 regression test처럼 KVM change와 연결된 KVM selftest는 KVM change와 하나의 series로 함께 게시한다. Standard kernel bisection rule을 지켜 KVM change가 test failure를 일으킨다면 selftest update를 먼저 배치한다. 반대로 새 test가 기존 KVM bug 때문에 실패한다면 KVM fix를 먼저 배치한다.
KVM-unit-tests는 항상 별도 series로 게시한다. b4 am 같은 tool은 KVM-unit-tests가 별도 repository임을 몰라 한 series의 patch가 서로 다른 tree에 적용되면 혼란을 겪는다. 먼저 KVM change를 게시한 뒤 KVM-unit-tests patch에서 해당 KVM patch/series의 lore Link를 제공한다.
Acceptance notification과 SHA1 stability
360-382Patch/series가 공식 accept되면 original posting, multi-patch series라면 cover letter에 reply로 notification email을 보낸다. 적용된 tree와 topic branch, patch commit SHA1을 포함한다.
일부 patch만 적용했다면 notification에서 명확히 말한다. 별도 설명이 없다면 accept되지 않은 patch는 추가 작업이 필요하며 새 version으로 다시 제출해야 한다.
공식 accept 뒤 patch를 drop하면 notification email에 reply하여 이유와 다음 단계를 설명한다.
SHA1은 Linus tree에 들어갈 때까지 100% 안정적이지 않다. Notification 뒤에는 보통 안정적이지만 예외가 있다. 적용 patch SHA1이 바뀌면 대부분 notification update를 보내지만 모든 KVM x86 branch를 rebase해야 하는 상황처럼 individual notification을 보내지 않을 때도 있다.
Guest에서 host를 공격할 수 있는 취약점
384-390Guest가 host kernel 또는 userspace를 공격할 수 있거나 nested VM이 자신의 host, 즉 L2가 L1을 공격할 수 있는 bug는 KVM에서 특히 중요하다. Escape, data leak 등으로 이어질 수 있다고 의심하면 Documentation/admin-guide/security-bugs.rst의 security bug protocol을 따른다.
Tree, branch와 lifecycle
maintainer-kvm-x86.rst:3-81KVM x86 변경은 kvm-x86 maintainer tree의 목적별 branch에서 review·queue되고 linux-next integration 뒤 KVM 또는 upstream pull request로 이동한다. Branch 이름과 target은 개발 기능, fix와 next cycle을 구분하므로 posting 전 current tree 상태를 확인한다.
Merge window와 -rc timeline을 역산해 feature는 충분한 review·testing 시간을 두고 보내며 urgent fix는 영향 release와 stable 필요성을 명시한다.