1 .. SPDX-License-Identifier: GPL-2.0
2
3 KVM x86
4 =======
5
6 Foreword
7 --------
8 KVM strives to be a welcoming community; contr
9 valued and encouraged. Please do not be disco
10 length of this document and the many rules/gui
11 makes mistakes, and everyone was a newbie at s
12 an honest effort to follow KVM x86's guideline
13 and learn from any mistakes you make, you will
14 torches and pitchforks.
15
16 TL;DR
17 -----
18 Testing is mandatory. Be consistent with esta
19
20 Trees
21 -----
22 KVM x86 is currently in a transition period fr
23 tree, to being "just another KVM arch". As su
24 main KVM tree, ``git.kernel.org/pub/scm/virt/k
25 specific tree, ``github.com/kvm-x86/linux.git`
26
27 Generally speaking, fixes for the current cycl
28 main KVM tree, while all development for the n
29 KVM x86 tree. In the unlikely event that a fi
30 through the KVM x86 tree, it will be applied t
31 making its way to the main KVM tree.
32
33 Note, this transition period is expected to la
34 the status quo for the foreseeable future.
35
36 Branches
37 ~~~~~~~~
38 The KVM x86 tree is organized into multiple to
39 using finer-grained topic branches is to make
40 of development, and to limit the collateral da
41 commits, e.g. dropping the HEAD commit of a to
42 in-flight commits' SHA1 hashes, and having to
43 delays only that topic branch.
44
45 All topic branches, except for ``next`` and ``
46 via a Cthulhu merge on an as-needed basis, i.e
47 As a result, force pushes to ``next`` are comm
48
49 Lifecycle
50 ~~~~~~~~~
51 Fixes that target the current release, a.k.a.
52 directly to the main KVM tree, i.e. do not rou
53
54 Changes that target the next release are route
55 requests (from KVM x86 to main KVM) are sent f
56 typically the week before Linus' opening of th
57 following rc7 for "normal" releases. If all g
58 rolled into the main KVM pull request sent dur
59
60 The KVM x86 tree doesn't have its own official
61 close around rc5 for new features, and a soft
62 the next release; see above for fixes that tar
63
64 Timeline
65 ~~~~~~~~
66 Submissions are typically reviewed and applied
67 room for the size of a series, patches that ar
68 especially for the current release and or stab
69 Patches that will be taken through a non-KVM t
70 tree) and/or have other acks/reviews also jump
71
72 Note, the vast majority of review is done betw
73 The period between rc6 and the next rc1 is use
74 i.e. radio silence during this period isn't un
75
76 Pings to get a status update are welcome, but
77 current release cycle and have realistic expec
78 acceptance, i.e. not just for feedback or an u
79 can, within reason, to ensure that your patche
80 on series that break the build or fail tests l
81
82 Development
83 -----------
84
85 Base Tree/Branch
86 ~~~~~~~~~~~~~~~~
87 Fixes that target the current release, a.k.a.
88 ``git://git.kernel.org/pub/scm/virt/kvm/kvm.gi
89 automatically warrant inclusion in the current
90 rule, but typically only fixes for bugs that a
91 introduced in the current release should targe
92
93 Everything else should be based on ``kvm-x86/n
94 select a specific topic branch as the base. I
95 dependencies across topic branches, it is the
96 out.
97
98 The only exception to using ``kvm-x86/next`` a
99 is a multi-arch series, i.e. has non-trivial m
100 and/or has more than superficial changes to ot
101 arch patch/series should instead be based on a
102 history, e.g. the release candidate upon which
103 you're unsure whether a patch/series is truly
104 caution and treat it as multi-arch, i.e. use a
105
106 Coding Style
107 ~~~~~~~~~~~~
108 When it comes to style, naming, patterns, etc.
109 priority in KVM x86. If all else fails, match
110
111 With a few caveats listed below, follow the ti
112 :ref:`maintainer-tip-coding-style`, as patches
113 non-KVM x86 files, i.e. draw the attention of
114
115 Using reverse fir tree, a.k.a. reverse Christm
116 variable declarations isn't strictly required,
117
118 Except for a handful of special snowflakes, do
119 functions. The vast majority of "public" KVM
120 they are intended only for KVM-internal consum
121 privatize KVM's headers and exports to enforce
122
123 Comments
124 ~~~~~~~~
125 Write comments using imperative mood and avoid
126 provide a high level overview of the code, and
127 what it does. Do not reiterate what the code
128 speak for itself. If the code itself is inscr
129
130 SDM and APM References
131 ~~~~~~~~~~~~~~~~~~~~~~
132 Much of KVM's code base is directly tied to ar
133 Intel's Software Development Manual (SDM) and
134 Manual (APM). Use of "Intel's SDM" and "AMD's
135 "APM", without additional context is a-ok.
136
137 Do not reference specific sections, tables, fi
138 not in comments. Instead, if necessary (see b
139 snippet and reference sections/tables/figures
140 and APM are constantly changing, and so the nu
141
142 Generally speaking, do not explicitly referenc
143 APM in comments. With few exceptions, KVM *mu
144 therefore it's implied that KVM behavior is em
145 Note, referencing the SDM/APM in changelogs to
146 context is perfectly ok and encouraged.
147
148 Shortlog
149 ~~~~~~~~
150 The preferred prefix format is ``KVM: <topic>:
151
152 - x86
153 - x86/mmu
154 - x86/pmu
155 - x86/xen
156 - selftests
157 - SVM
158 - nSVM
159 - VMX
160 - nVMX
161
162 **DO NOT use x86/kvm!** ``x86/kvm`` is used e
163 changes, i.e. for arch/x86/kernel/kvm.c. Do n
164 paths as the subject/shortlog prefix.
165
166 Note, these don't align with the topics branch
167 more about code conflicts).
168
169 All names are case sensitive! ``KVM: x86:`` i
170
171 Capitalize the first word of the condensed pat
172 punctionation. E.g.::
173
174 KVM: x86: Fix a null pointer dereference i
175
176 not::
177
178 kvm: x86: fix a null pointer dereference i
179
180 If a patch touches multiple topics, traverse u
181 first common parent (which is often simply ``x
182 ``git log path/to/file`` should provide a reas
183
184 New topics do occasionally pop up, but please
185 you want to propose introducing a new topic, i
186
187 See :ref:`the_canonical_patch_format` for more
188 do not treat the 70-75 character limit as an a
189 use 75 characters as a firm-but-not-hard limit
190 limit. I.e. let the shortlog run a few charac
191 you have good reason to do so.
192
193 Changelog
194 ~~~~~~~~~
195 Most importantly, write changelogs using imper
196
197 See :ref:`describe_changes` for more informati
198 a short blurb on the actual changes, and then
199 background. Note! This order directly confli
200 approach! Please follow the tip tree's prefer
201 that primarily target arch/x86 code that is _N
202
203 Stating what a patch does before diving into d
204 for several reasons. First and foremost, what
205 is arguably the most important information, an
206 find. Changelogs that bury the "what's actuall
207 3+ paragraphs of background make it very hard
208
209 For initial review, one could argue the "what'
210 for skimming logs and git archaeology, the gor
211 E.g. when doing a series of "git blame", the d
212 way are useless, the details only matter for t
213 changed" makes it easy to quickly determine wh
214 interest.
215
216 Another benefit of stating "what's changing" f
217 possible to state "what's changing" in a singl
218 the most simple bugs require multiple sentence
219 the problem. If both the "what's changing" an
220 short then the order doesn't matter. But if o
221 "what's changing), then covering the shorter o
222 it's less of an inconvenience for readers/revi
223 preference. E.g. having to skip one sentence
224 painful than having to skip three paragraphs t
225
226 Fixes
227 ~~~~~
228 If a change fixes a KVM/kernel bug, add a Fixe
229 need to be backported to stable kernels, and e
230 an older release.
231
232 Conversely, if a fix does need to be backporte
233 "Cc: stable@vger.kernel" (though the email its
234 KVM x86 opts out of backporting Fixes: by defa
235 do get backported, but require explicit mainta
236
237 Function References
238 ~~~~~~~~~~~~~~~~~~~
239 When a function is mentioned in a comment, cha
240 for that matter), use the format ``function_na
241 context and disambiguate the reference.
242
243 Testing
244 -------
245 At a bare minimum, *all* patches in a series m
246 KVM_AMD=m, and KVM_WERROR=y. Building every p
247 isn't feasible, but the more the merrier. KVM
248 X86_64 are particularly interesting knobs to t
249
250 Running KVM selftests and KVM-unit-tests is al
251 obvious, the tests need to pass). The only ex
252 negligible probability of affecting runtime be
253 modify comments. When possible and relevant,
254 strongly preferred. Booting an actual VM is e
255
256 For changes that touch KVM's shadow paging cod
257 disabled is mandatory. For changes that affec
258 with TDP disabled is strongly encouraged. For
259 being modified depends on and/or interacts wit
260 the relevant settings is mandatory.
261
262 Note, KVM selftests and KVM-unit-tests do have
263 a failure is not due to your changes, verify t
264 occurs with and without your changes.
265
266 Changes that touch reStructured Text documenta
267 htmldocs cleanly, i.e. with no new warnings or
268
269 If you can't fully test a change, e.g. due to
270 what level of testing you were able to do, e.g
271
272 New Features
273 ~~~~~~~~~~~~
274 With one exception, new features *must* come w
275 tests aren't strictly required, e.g. if covera
276 sufficiently enabled guest VM, or by running a
277 but dedicated KVM tests are preferred in all c
278 particular are mandatory for enabling of new h
279 exception flows are rarely exercised simply by
280
281 The only exception to this rule is if KVM is s
282 feature via KVM_GET_SUPPORTED_CPUID, i.e. for
283 can't prevent a guest from using and for which
284
285 Note, "new features" does not just mean "new h
286 that can't be well validated using existing KV
287 must come with tests.
288
289 Posting new feature development without tests
290 than welcome, but such submissions should be t
291 should clearly state what type of feedback is
292 the RFC process; RFCs will typically not recei
293
294 Bug Fixes
295 ~~~~~~~~~
296 Except for "obvious" found-by-inspection bugs,
297 reproducer for the bug being fixed. In many c
298 e.g. for build errors and test failures, but i
299 readers what is broken and how to verify the f
300 bugs that are found via non-public workloads/t
301 tests for such bugs is strongly preferred.
302
303 In general, regression tests are preferred for
304 hit. E.g. even if the bug was originally foun
305 a targeted regression test may be warranted if
306 one-in-a-million type race condition.
307
308 Note, KVM bugs are rarely urgent *and* non-tri
309 if a bug is really truly the end of the world
310 reproducer.
311
312 Posting
313 -------
314
315 Links
316 ~~~~~
317 Do not explicitly reference bug reports, prior
318 via ``In-Reply-To:`` headers. Using ``In-Repl
319 for large series and/or when the version count
320 is useless for anyone that doesn't have the or
321 wasn't Cc'd on the bug report or if the list o
322 versions.
323
324 To link to a bug report, previous version, or
325 links. For referencing previous version(s), g
326 a Link: in the changelog as there is no need t
327 put the link in the cover letter or in the sec
328 formal Link: for bug reports and/or discussion
329 context of why a change was made is highly val
330
331 Git Base
332 ~~~~~~~~
333 If you are using git version 2.9.0 or later (G
334 use ``git format-patch`` with the ``--base`` f
335 base tree information in the generated patches
336
337 Note, ``--base=auto`` works as expected if and
338 set to the base topic branch, e.g. it will do
339 is set to your personal repository for backup
340 solution is to derive the names of your develo
341 KVM x86 topic, and feed that into ``--base``.
342 and then write a small wrapper to extract ``pm
343 to yield ``--base=x/pmu``, where ``x`` is what
344 track the KVM x86 remote.
345
346 Co-Posting Tests
347 ~~~~~~~~~~~~~~~~
348 KVM selftests that are associated with KVM cha
349 bug fixes, should be posted along with the KVM
350 standard kernel rules for bisection apply, i.e
351 failures should be ordered after the selftests
352 tests that fail due to KVM bugs should be orde
353
354 KVM-unit-tests should *always* be posted separ
355 know that KVM-unit-tests is a separate reposit
356 in a series apply on different trees. To tie
357 KVM patches, first post the KVM changes and th
358 KVM patch/series in the KVM-unit-tests patch(e
359
360 Notifications
361 -------------
362 When a patch/series is officially accepted, a
363 in reply to the original posting (cover letter
364 notification will include the tree and topic b
365 the commits of applied patches.
366
367 If a subset of patches is applied, this will b
368 notification. Unless stated otherwise, it's i
369 series that were not accepted need more work a
370 version.
371
372 If for some reason a patch is dropped after of
373 will be sent to the notification email explain
374 well as the next steps.
375
376 SHA1 Stability
377 ~~~~~~~~~~~~~~
378 SHA1s are not 100% guaranteed to be stable unt
379 SHA1 is *usually* stable once a notification h
380 In most cases, an update to the notification e
381 patch's SHA1 changes. However, in some scenar
382 need to be rebased, individual notifications w
383
384 Vulnerabilities
385 ---------------
386 Bugs that can be exploited by the guest to att
387 userspace), or that can be exploited by a nest
388 L1), are of particular interest to KVM. Pleas
389 :ref:`securitybugs` if you suspect a bug can l
390
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.