[PATCH v2] Documentation/process: Add a maintainer entry profile for KVM/arm64

[PATCH v2] Documentation/process: Add a maintainer entry profile for KVM/arm64

[Matthias Goergens]

KVM/arm64 has no P: entry in MAINTAINERS, so nothing tells a contributor
that the kvmarm tree is used for integration only, or what the
maintainers expect patches to be based on.  Marc Zyngier said a profile
would help.

Add one covering the trees, the base for patches, the submit checklist,
key cycle dates and review cadence, and point the KVM/arm64 entry at it.

Link: https://lore.kernel.org/all/875wzu4vuv.wl-maz@kernel.org/
Link: https://lore.kernel.org/all/87tsnb2dtq.wl-maz@kernel.org/
Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>
---
Changes since the RFC
(https://lore.kernel.org/all/20260925085621.562448-1-matthias.goergens@gmail.com/):

- Point at the MAINTAINERS entry instead of naming maintainers and lists.
- Describe master, topic branches and shared branches; drop the open
  questions, which the RFC's Sashiko review had also flagged.
- Base: prefer -rc1 to -rc3, not kvmarm/next; leave conflicts visible.
- Subject lines: capital letter after the prefixes.
- Architecture references: prefer rule identifiers; drop the comparison
  with KVM x86.
- Testing: selftests usually at the end of the series, reproducible
  performance measurements, tests encouraged rather than required for NV.
- Key cycle dates: no new features after -rc6; how fixes are sent.
- Review cadence: stability of commit IDs; answering bot reviews.
- Posted as a new thread, with the documentation maintainers and lists
  on Cc.

Steffen, Marc asked you for a short addition on KVM/arm64 on s390 for
the Trees section.  I've left it out and can add it as a follow-up.

Oliver, thanks for inviting an updated patch.  Corrections are welcome.

 .../process/maintainer-kvm-arm64.rst          | 181 ++++++++++++++++++
 MAINTAINERS                                   |   2 +
 2 files changed, 183 insertions(+)
 create mode 100644 Documentation/process/maintainer-kvm-arm64.rst

diff --git a/Documentation/process/maintainer-kvm-arm64.rst b/Documentation/process/maintainer-kvm-arm64.rst
new file mode 100644
index 0000000..3b0bb56
--- /dev/null
+++ b/Documentation/process/maintainer-kvm-arm64.rst
@@ -0,0 +1,181 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+KVM/arm64
+=========
+
+This document describes how KVM/arm64 (``arch/arm64/kvm/`` and the other
+files listed under "KERNEL VIRTUAL MACHINE FOR ARM64 (KVM/arm64)" in
+MAINTAINERS) is maintained.  It supplements
+Documentation/process/submitting-patches.rst.
+
+Overview
+--------
+
+The maintainers, reviewers and mailing lists for KVM/arm64 are listed in its
+MAINTAINERS entry.
+
+Trees
+~~~~~
+
+The KVM/arm64 tree is::
+
+  git://git.kernel.org/pub/scm/linux/kernel/git/kvmarm/kvmarm.git
+
+This tree is used for integration only: no development happens in it, and
+most patches should not be based on it (see `Base for patches`_).  Its
+branches are:
+
+``next``
+  Changes queued for the next merge window.  linux-next merges this branch.
+
+``fixes``
+  Fixes for the release currently in its -rc phase.  linux-next merges this
+  branch too.
+
+``master``
+  Follows the -rc tags in Linus Torvalds' tree.
+
+Changes leave the tree as signed tags, which are pulled into the main KVM tree
+(``git://git.kernel.org/pub/scm/virt/kvm/kvm.git``) and from there reach Linus
+Torvalds.
+
+Topic branches are managed by the maintainers in their private trees, and only
+the result of integrating them is pushed out.  The exception is shared
+branches, which are published when necessary.  Where a series also touches
+code maintained elsewhere, most often the arm64 architecture code, the
+maintainers may set up a shared stable branch, based on an -rc tag, that both
+trees merge.  Say in the cover letter which parts of a series touch other
+subsystems.
+
+Base for patches
+~~~~~~~~~~~~~~~~
+
+Base your patches on a tag published in Linus Torvalds' tree, preferably -rc1
+to -rc3.  If you rely on something merged later, for example a fix merged in
+-rc4, say why in the cover letter.  Patches based on linux-next are
+discouraged.
+
+Do not base patches on ``kvmarm/next`` either: it is rebuilt regularly, so a
+commit on it is generally the wrong base.  If your series conflicts with work
+queued there, leave the conflict for the maintainers to see, as it is a sign
+that something needs a closer look.  A proposed resolution is welcome.  The
+exception is a series that strictly continues one that has already been
+queued.
+
+If your series depends on something else that is not yet in mainline, such as
+another series under review, say so in the cover letter and name exactly what
+it applies on top of.
+
+Use ``git format-patch --base`` so that the base commit is recorded in the
+patches.
+
+Submit Checklist Addendum
+-------------------------
+
+Recipients and threading
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Send the whole series to all of the maintainers and reviewers listed for
+KVM/arm64, not a selection of them.  Post each new version as a new thread,
+not as a reply to the previous version, with a cover letter for anything
+longer than a single patch.
+
+Subject lines
+~~~~~~~~~~~~~
+
+Changes to KVM/arm64 use the ``KVM: arm64:`` prefix, often followed by a
+sub-topic such as ``nv:`` or ``vgic:``.  Selftest changes use ``KVM: arm64:
+selftests:`` or ``KVM: selftests:``.
+``git log --oneline`` on the files you touch shows what is in use.  The text
+after the prefixes starts with a capital letter, for example ``KVM: arm64: nv:
+Fix life cycle of the nested_mmus array``.
+
+Architecture references
+~~~~~~~~~~~~~~~~~~~~~~~
+
+KVM/arm64 code tracks the Arm Architecture Reference Manual (the "Arm ARM",
+document DDI0487) closely.  Where a change depends on architected behaviour,
+explain why the change is needed and cite the Arm ARM in the commit message
+or in a comment.  Where the rule has an identifier, such as ``R_QXXPC``, quote
+that: identifiers stay the same across revisions of the document, while
+section numbers do not.  Otherwise give the revision along with the section,
+for example ``DDI0487L.a D24.2.70``.  The same applies to other architecture
+documents.
+
+Testing
+~~~~~~~
+
+Say in the cover letter how the series was tested: which tests, and on which
+hardware or model.  The KVM selftests (``tools/testing/selftests/kvm/``) and
+kvm-unit-tests are the usual test suites.  Put selftest changes in patches of
+their own, separate from the KVM changes and usually at the end of the series.
+
+KVM/arm64 can run in several modes, which are described under
+``kvm-arm.mode=`` in Documentation/admin-guide/kernel-parameters.txt.  Test
+the modes your change can affect.
+
+If a patch aims to improve performance, describe exactly how you measured it,
+in enough detail for others to reproduce the results.  Measurements made on a
+software model such as QEMU or the Arm FVP say nothing about performance on
+hardware.
+
+New tests are encouraged, particularly for nested virtualisation, where
+coverage is poor.  Depending on the change, selftests may not be enough; the
+maintainers may ask for testing with a VMM, for example.
+
+Userspace API
+~~~~~~~~~~~~~
+
+Document changes to the userspace API, usually in
+Documentation/virt/kvm/api.rst or in the files under
+Documentation/virt/kvm/devices/ and Documentation/virt/kvm/arm/.
+
+Fixes
+~~~~~
+
+Add a ``Fixes:`` tag for bug fixes.  If the fix should go to stable kernels,
+add ``Cc: stable@vger.kernel.org``; the maintainers may add it when applying
+if the bug calls for it.
+
+Key Cycle Dates
+---------------
+
+Changes for the next merge window are queued on ``next``.  New features are
+usually not merged once -rc6 has been published; from then on, only fixes are
+queued.  This is not a hard rule, but posting a feature just before -rc6
+guarantees nothing.
+
+Fixes for the current release are queued on ``fixes`` and sent upstream at
+intervals that depend on how severe the bugs are.  There is no cut-off for
+fixes, but the maintainers may defer a low-priority fix to the next merge
+window.
+
+Review Cadence
+--------------
+
+Unless the maintainers ask for a new version sooner, allow at least a week
+between versions of a series, and only post a new version once there has
+been enough review to justify it.  Posting more often delays review rather
+than speeding it up.
+
+Pinging a series that has had no response is fine.
+
+Answer reviews from bots such as Sashiko as you would any other review, even
+if only to say that a finding is wrong.  Pre-existing problems that a bot
+points out, and that are unrelated to the series, need not be fixed in its
+initial posting.
+
+Applied patches are normally acknowledged in reply to the posting, naming the
+branch (``next`` or ``fixes``) and the commits.  The maintainers try not to
+change the commit IDs of applied patches, but the IDs of merge commits almost
+always change.
+
+Minor problems are often fixed up by the maintainers when applying; if they
+say "no need to resend", don't.
+
+Security issues
+---------------
+
+Bugs that let a guest attack its host, or a nested guest attack its guest
+hypervisor, should be reported as described in
+Documentation/process/security-bugs.rst.
diff --git a/MAINTAINERS b/MAINTAINERS
index 7a162e9..183bf34 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14596,7 +14596,9 @@ R:	Zenghui Yu <yuzenghui@huawei.com>
 L:	linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
 L:	kvmarm@lists.linux.dev
 S:	Maintained
+P:	Documentation/process/maintainer-kvm-arm64.rst
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/kvmarm/kvmarm.git
+F:	Documentation/process/maintainer-kvm-arm64.rst
 F:	Documentation/virt/kvm/arm/
 F:	Documentation/virt/kvm/devices/arm*
 F:	arch/arm64/include/asm/kvm*

base-commit: d89e1d186ec9271bf78e62771779e9fc03bf0fc3
-- 
2.56.0

Re: [PATCH v2] Documentation/process: Add a maintainer entry profile for KVM/arm64

[Zenghui Yu]

Hi Matthias,

On 2026/10/30 16:33, Matthias Goergens wrote:
> KVM/arm64 has no P: entry in MAINTAINERS, so nothing tells a contributor
> that the kvmarm tree is used for integration only, or what the
> maintainers expect patches to be based on.  Marc Zyngier said a profile
> would help.
> 
> Add one covering the trees, the base for patches, the submit checklist,
> key cycle dates and review cadence, and point the KVM/arm64 entry at it.
> 
> Link: https://lore.kernel.org/all/875wzu4vuv.wl-maz@kernel.org/
> Link: https://lore.kernel.org/all/87tsnb2dtq.wl-maz@kernel.org/
> Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>
> ---
> Changes since the RFC
> (https://lore.kernel.org/all/20260925085621.562448-1-matthias.goergens@gmail.com/):
> 
> - Point at the MAINTAINERS entry instead of naming maintainers and lists.
> - Describe master, topic branches and shared branches; drop the open
>   questions, which the RFC's Sashiko review had also flagged.
> - Base: prefer -rc1 to -rc3, not kvmarm/next; leave conflicts visible.
> - Subject lines: capital letter after the prefixes.
> - Architecture references: prefer rule identifiers; drop the comparison
>   with KVM x86.
> - Testing: selftests usually at the end of the series, reproducible
>   performance measurements, tests encouraged rather than required for NV.
> - Key cycle dates: no new features after -rc6; how fixes are sent.
> - Review cadence: stability of commit IDs; answering bot reviews.
> - Posted as a new thread, with the documentation maintainers and lists
>   on Cc.
> 
> Steffen, Marc asked you for a short addition on KVM/arm64 on s390 for
> the Trees section.  I've left it out and can add it as a follow-up.
> 
> Oliver, thanks for inviting an updated patch.  Corrections are welcome.
> 
>  .../process/maintainer-kvm-arm64.rst          | 181 ++++++++++++++++++
>  MAINTAINERS                                   |   2 +
>  2 files changed, 183 insertions(+)
>  create mode 100644 Documentation/process/maintainer-kvm-arm64.rst

This looks pretty good. Thanks a lot for your efforts!

Acked-by: Zenghui Yu <yuzenghui@huawei.com>

Re: [PATCH v2] Documentation/process: Add a maintainer entry profile for KVM/arm64

[Wei-Lin Chang]

On Fri, Oct 30, 2026 at 04:33:51PM +0800, Matthias Goergens wrote:

[...]

> +Review Cadence
> +--------------
> +
> +Unless the maintainers ask for a new version sooner, allow at least a week
> +between versions of a series, and only post a new version once there has
> +been enough review to justify it.  Posting more often delays review rather
> +than speeding it up.
> +
> +Pinging a series that has had no response is fine.
> +
> +Answer reviews from bots such as Sashiko as you would any other review, even
> +if only to say that a finding is wrong.  Pre-existing problems that a bot
> +points out, and that are unrelated to the series, need not be fixed in its
> +initial posting.
> +
> +Applied patches are normally acknowledged in reply to the posting, naming the
> +branch (``next`` or ``fixes``) and the commits.  The maintainers try not to
> +change the commit IDs of applied patches, but the IDs of merge commits almost
> +always change.
> +
> +Minor problems are often fixed up by the maintainers when applying; if they
> +say "no need to resend", don't.

The second half of this is a little silly :P
What about just:

Minor problems are often fixed up by the maintainers when applying; ask
if you are unsure whether to resend.

Thanks,
Wei-Lin Chang

> +
> +Security issues
> +---------------
> +
> +Bugs that let a guest attack its host, or a nested guest attack its guest
> +hypervisor, should be reported as described in
> +Documentation/process/security-bugs.rst.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 7a162e9..183bf34 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -14596,7 +14596,9 @@ R:	Zenghui Yu <yuzenghui@huawei.com>
>  L:	linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
>  L:	kvmarm@lists.linux.dev
>  S:	Maintained
> +P:	Documentation/process/maintainer-kvm-arm64.rst
>  T:	git git://git.kernel.org/pub/scm/linux/kernel/git/kvmarm/kvmarm.git
> +F:	Documentation/process/maintainer-kvm-arm64.rst
>  F:	Documentation/virt/kvm/arm/
>  F:	Documentation/virt/kvm/devices/arm*
>  F:	arch/arm64/include/asm/kvm*
> 
> base-commit: d89e1d186ec9271bf78e62771779e9fc03bf0fc3
> -- 
> 2.56.0
> 

Re: [PATCH v2] Documentation/process: Add a maintainer entry profile for KVM/arm64

[Matthias Goergens]

On Sat, 31 Oct 2026 21:03:17 +0000, Wei-Lin Chang wrote:
>> +Minor problems are often fixed up by the maintainers when applying; if they
>> +say "no need to resend", don't.
>
> The second half of this is a little silly :P
> What about just:
>
> Minor problems are often fixed up by the maintainers when applying; ask
> if you are unsure whether to resend.

Agreed, that reads better.  I'll use your wording in v3.

Thanks,
Matthias

Re: [PATCH v2] Documentation/process: Add a maintainer entry profile for KVM/arm64

[Marc Zyngier]

On Mon, 02 Nov 2026 08:37:59 +0000,
Matthias Goergens <matthias.goergens@gmail.com> wrote:
> 
> On Sat, 31 Oct 2026 21:03:17 +0000, Wei-Lin Chang wrote:
> >> +Minor problems are often fixed up by the maintainers when applying; if they
> >> +say "no need to resend", don't.
> >
> > The second half of this is a little silly :P
> > What about just:
> >
> > Minor problems are often fixed up by the maintainers when applying; ask
> > if you are unsure whether to resend.
> 
> Agreed, that reads better.  I'll use your wording in v3.

If that's the only change, I'll fix it when applying.

Thanks,

	M.

-- 
Without deviation from the norm, progress is not possible.

Re: [PATCH v2] Documentation/process: Add a maintainer entry profile for KVM/arm64

[Krzysztof Kozlowski]

On 30/10/2026 09:33, Matthias Goergens wrote:
> +
> +If your series depends on something else that is not yet in mainline, such as
> +another series under review, say so in the cover letter and name exactly what
> +it applies on top of.
> +
> +Use ``git format-patch --base`` so that the base commit is recorded in the
> +patches.

You should rather encourage usage of b4, which does above for you.

...

> +
> +Security issues
> +---------------
> +
> +Bugs that let a guest attack its host, or a nested guest attack its guest
> +hypervisor, should be reported as described in
> +Documentation/process/security-bugs.rst.

Do we need to repeat standard stuff in every maintainer profile? Above
is quite obvious, so maybe skip it which would make the document shorter
increasing the chances anyone will read it.

Best regards,
Krzysztof

Re: [PATCH v2] Documentation/process: Add a maintainer entry profile for KVM/arm64

[Marc Zyngier]

On Mon, 02 Nov 2026 07:16:47 +0000,
Krzysztof Kozlowski <krzk@kernel.org> wrote:
> 
> On 30/10/2026 09:33, Matthias Goergens wrote:
> > +
> > +If your series depends on something else that is not yet in mainline, such as
> > +another series under review, say so in the cover letter and name exactly what
> > +it applies on top of.
> > +
> > +Use ``git format-patch --base`` so that the base commit is recorded in the
> > +patches.
> 
> You should rather encourage usage of b4, which does above for you.

No. People use whatever they want to use, and we don't have to be
prescriptive.

>
> ...
> 
> > +
> > +Security issues
> > +---------------
> > +
> > +Bugs that let a guest attack its host, or a nested guest attack its guest
> > +hypervisor, should be reported as described in
> > +Documentation/process/security-bugs.rst.
> 
> Do we need to repeat standard stuff in every maintainer profile? Above
> is quite obvious, so maybe skip it which would make the document shorter
> increasing the chances anyone will read it.

I'm perfectly happy to have this here. Most people will only read the
one document they need to (if any). And I really doubt that the
mention of a nested guest escape is that common (as a basic grep would
have shown you).

	M.

-- 
Without deviation from the norm, progress is not possible.